ADR 2.0 후기와 다음 단계

1. ADR 2.0이란 무엇인가?

과거의 ADR이 사람이 결정한 사항을 사후에 기록하는 '일기장'이었다면, ADR 2.0은 에이전트와 사람 사이의 '살아있는 계약서'입니다. ADR2.0 은 에이전트를 위한 지도가 됩니다.

자세한 설명은 기존 포스팅으로 대체합니다. https://juhyungson.com/blog/adr-20-

여전히 유효한 핵심 원칙

- 문서는 기록이 아니라 '계약'이다: 문서는 단순히 지나간 일을 적어두는 것이 아니라, 에이전트가 코드를 작성할 때 반드시 준수해야 하는 규칙이자 계약입니다.

- 에이전트 중심의 관리: 개발 과정에서 발생하는 수많은 문서는 에이전트가 자동으로 생성합니다. 그중 설계상 중요한 의사결정만을 스스로 선별하여 ADR로 격상시켜 관리합니다.

- 사람은 '판단'만 한다: 사람은 일일이 문서를 쓰거나 수정하는 '노동'에 개입하지 않습니다. 에이전트가 제안한 결정사항에 대해 최종적인 판단과 승인만을 담당합니다.

- 설명서가 아닌 '지도': 에이전트에게 모든 세세한 지침을 주는 '설명서(Manual)'를 제공하기보다, 스스로 길을 찾을 수 있는 '지도(Map)'를 제공하는 것에 집중합니다.

2. 실전 도입 후기: 무엇이 바뀌었나?

ADR 2.0을 실제 프로젝트에 적용하며 느낀 가장 큰 변화는 **에이전트와의 협업 밀도**였습니다.

지도의 힘

프론티어 모델들은 긴 컨텍스트를 처리하는 능력이 뛰어나지만, 모든 정보를 주입하는 것보다 "어디에서 무엇을 찾아야 하는지"에 대한 지도를 제공했을 때 훨씬 더 정확하게 동작했습니다. 이는 토큰 비용 절감뿐만 아니라 결과물의 품질 향상으로 이어졌습니다.

인간 동료와 같은 '싱크'

번거로운 컨텍스트 주입 작업이 눈에 띄게 줄었습니다. 비슷한 작업을 반복할 때, 마치 숙련된 인간 동료와 일하는 것처럼 에이전트와 저 사이에 '암묵적인 싱크'가 맞춰져 있다는 느낌을 받았습니다. 특히 에이전트가 `plan` 모드에서 기존 ADR을 참고해 설계를 제안할 때 그 효용성이 극대화되었습니다.

담당자가 없어도 돌아가는 코드

제가 직접 관여하지 않았던 모듈을 개발할 때도 에이전트는 ADR 문서를 기반으로 훌륭하게 워킹했습니다. 아직은 최종 확인 후 담당자에게 토스하고 있지만, 시스템이 고도화된다면 이 과정조차 자동화될 수 있다는 가능성을 보았습니다.

3. 여전한 갈증: 해결해야 할 과제들

완벽해 보이는 ADR 2.0에도 몇 가지 현실적인 한계가 존재했습니다.

1. 레포지토리 종속성: ADR은 현재 단일 레포에 종속되어 있습니다. 하지만 실제 기능 개발은 여러 레포를 넘나들며 이루어지기에, 레포 간 컨텍스트를 동기화하고 의사결정을 공유하는 것이 쉽지 않습니다.

2. 에이전트의 기술 부채: 사람과 마찬가지로 에이전트도 코드를 작성하며 부채를 쌓습니다. 이 부채를 어떻게 감지하고 청산할지에 대한 메커니즘이 필요합니다.

3. 낡아가는 문서: 코드의 변화 속도가 빠르면 ADR 또한 쉽게 낡아버립니다. 다행히 최근에는 에이전트가 스스로 모순을 발견하고 "이 문서가 낡았는데 고칠까요?"라고 먼저 묻는 빈도가 늘고 있습니다.

4. 관측 가능성의 부재: 로그와 메트릭을 에이전트가 직접 분석하고 문제 지점을 찾아내는 단계까지는 아직 도달하지 못했습니다.

4. OpenAI의 'Harness Engineering'

최근 OpenAI에서 올린 ‘Harness Engineering' 포스트는 제가 고민하던 방향에 확신을 주었습니다. 그들이 제시한 아이디어 중 특히 공감했던 부분은 다음과 같습니다.

문서는 시스템의 기록이다: 문서 자체가 코드만큼이나 시스템의 핵심적인 자산임을 강조합니다.

모든 컨텍스트를 레포로: 에이전트가 별도의 외부 지식 없이도 레포지토리 내의 정보만으로 완결성 있게 동작해야 합니다.

Never start from zero: 에이전트가 처음부터 모든 것을 개발하도록 두지 않고, 기존의 맥락과 위치를 교육시켜 그 위에서 시작하게 합니다.

특히 "기술 부채를 소액으로 꾸준히 상환한다"는 개념은 인상적이었습니다. 에이전트가 주기적으로 부채를 확인하고 스스로 PR을 올려 조금씩 해결해 나가는 구조는 ADR 2.0이 나아가야 할 다음 단계입니다.

5. 다음 단계: 수동 코딩 0%를 향하여

에이전트가 단순히 보조를 넘어 우리 조직의 '코딩 머신'이 되기 위해, 저는 다음 단계의 실험을 준비하고 있습니다.

1. 엄격한 계층과 규제: 에이전트에게 너무 높은 자유도를 주기보다, 명확한 아키텍처 계층을 정의하고 Linter를 통해 이를 강제합니다. 규칙을 지키는 선 안에서 자유롭게 일하게 만드는 것입니다.

2. 지속적인 자동 부채 정리: OpenAI의 방식처럼 에이전트 스스로 부채를 감지하고 수정하도록 하여, 기술 부채가 쌓이지 않는 선순환 구조를 만듭니다.

3. 개발 환경의 관측성 강화: 에이전트에게 로그와 메트릭에 대한 접근 권한을 주고, 문제가 발생했을 때 스스로 원인을 파악할 수 있는 환경을 제공합니다.

4. 서비스 단위의 단일 레포(Service-Unit Repo): 기존에는 직무별(프론트, 백엔드 등)로 레포를 나누었지만, 이는 에이전트의 시야를 가두는 장애물이 됩니다. 서비스 기능 자체를 온전히 구현할 수 있도록 서비스 단위의 레포지토리 구성을 고려해야 합니다.

ADR 2.0은 시작일 뿐입니다. 에이전트가 개발의 주체가 되는 세상에서, 우리의 역할은 더 정교한 '지도'를 그리고 에이전트가 올바른 결정을 내릴 수 있도록 '계약'을 설계하는 일로 변화해 나갈 것입니다.

ADR 2.0 동작 사례