ADR 2.0: 에이전트 시대, 문서는 '기록'이 아니라 '계약'이다
1. ADR의 실패: 왜 우리는 기록하고 잊어버리는가?
ADR(Architecture Decision Record)은 소프트웨어 개발 과정에서 "왜 이런 기술적 선택을 했는지"를 남기는 문서입니다. 하지만 대부분의 조직에서 ADR은 시도조차 안되거나 시도는 헀으나 '작성하고 잊혀지는' 운명을 맞이합니다.
코드는 매일 변하는데 문서는 과거에 머물러 업데이트되지 않았고, 개발자들은 바쁜 일정 속에서 문서를 찾아볼 여유가 없기 때문입니다. 결국 문서는 레거시가 되고, 나중에 읽어도 신뢰할 수 없는 문서가 됩니다. 결국 팀의 지식은 여전히 파편화 되어 남습니다.
2. Agent-First 개발로의 변화
최근 개발 환경이 Cursor, Claude Code, Codex, Copilot 같은 Agent-First로 급변하고 있습니다. 링크드인이나 페이스북에서는 대부분의 개발자가 에이전트를 사용해 더 수준 높은 소프트웨어를 만들고 빠르게 가치를 창출하는 방법에 대해 논합니다. 이제 개발자는 처음부터 코드를 짜기보다, 에이전트와 대화하며 코드를 생성하고 검토하는 데 더 많은 시간을 씁니다.
문제는 에이전트가 우리 프로젝트의 '히스토리'와 '맥락'을 모른다는 것입니다. 그저 그때 주어진 컨텍스트와 일부 룰을 가지고 인터넷에 널린 일반적인 모범 사례(Best Practice)를 가져와 기계적으로 코드를 짤 뿐입니다. 우리 팀만의 제약 조건을 모르는 에이전트는 훌륭하지만 눈치 없는 신입 사원과 같습니다.
3. 패러다임의 전환: 회고록에서 '계약서'로
여기서 ADR의 역할이 완전히 바뀝니다. 지금까지의 ADR이 사람을 위한 '회고록'이었다면, 새로운 ADR은 에이전트가 시스템을 변경할 때 지켜야 할 '계약(Contract)'이 되어야 합니다.
에이전트에게 "우리 팀은 Redux를 쓰지 않아"라고 매번 말할 수는 없습니다. ADR이 에이전트의 행동을 제어하는 강력한 구속력을 가져야 합니다. 즉, 문서는 읽히기만을 위한 것이 아니라 에이전트에 의해 실행되기 위해 존재하는 것으로 사용되어야 합니다.
4. ADR 2.0 프레임워크: 사람과 에이전트의 '계약서'
여기서 제안하는 ADR 2.0은 단순한 문서 양식이 아니라, 사람의 부담을 완전히 없애면서도 아키텍처 결정을 강력하게 유지하는 'Agent-First 자동화 시스템'입니다.
핵심은 "에이전트가 개발 과정에서 문서를 자동으로 만들고, 그중 중요한 의사결정만 스스로 ADR로 격상시켜 관리한다"는 것입니다. 이를 위해 4가지 핵심 구성요소가 유기적으로 동작합니다.
[핵심 구성요소 4가지]
1 AAR (Agent Analysis Record): 개발 과정에서 에이전트가 자동으로 남기는 모든 분석 로그 혹은 문서입니다. 대안 비교, 설계 이유, 영향 분석 등이 포함되며, 사람은 이를 작성할 필요가 없습니다. (Raw Data)
2 ADR Candidate Detector: AAR 문서 중 "아키텍처 결정"에 해당하는 중요한 내용을 자동으로 선별하는 감지기입니다. 규칙 기반 필터와 LLM의 판단을 결합하여 작동합니다.
3 AAR → ADR 자동 변환기: 선별된 내용을 하이브리드 포맷(YAML+Markdown)으로 자동 변환합니다. Context, Decision, Constraints 등을 구조화하며, 사람은 최종 승인만 하면 됩니다.
4 ADR Validator (자동 검증기): 생성된 ADR을 '살아있는 규칙'으로 사용하여 PR이나 코드 변경 시 위반 여부를 자동으로 검사합니다.
[전체 프레임워크 흐름도]
Agent logs everything (AAR)
↓
Decisions detected
↓
ADR auto-generated
↓
Stored + indexed
↓
Agents enforce ADR rules in every PR
[기대 효과]
이 시스템을 도입하면 "문서 관리가 귀찮아서/바빠서 안/못 한다"는 문제 자체가 사라집니다. 에이전트가 대부분의 문서를 자동 생성하고 검증하므로, ADR의 품질과 일관성은 높아지고 문서는 개발 변경 시마다 자동으로 검증되는 '살아있는 자산'이 됩니다.
5. 잠깐, .cursorrules, AGENTS.md랑 뭐가 다른가요?
여기서 의문이 생길 수 있습니다. "그냥 프롬프트 설정 파일이나 .cursorrules에 다 적으면 되는 거 아닌가요?"
비슷해 보이지만, 목적과 지속성에서 결정적인 차이가 있습니다.
1 Why vs How: .cursorrules는 당장의 코딩 스타일(How)을 지시하는 '커닝 페이퍼(Cheat Sheet)'입니다. 반면 ADR은 그 규칙이 왜 생겨났는지(Why)를 설명하는 '판례집(Case Law)'입니다. 이유가 없는 규칙은 나중에 수정하거나 폐기하기 어렵습니다.
2 확장성(Scalability): 프로젝트가 커지면 규칙은 수백 개가 됩니다. 하나의 설정 파일에 다 넣으면 AI의 컨텍스트를 낭비합니다. ADR은 모듈화되어 있어, 에이전트가 필요한 순간에 필요한 지식만 검색해서 가져올 수 있습니다.
3 도구 중립성: .cursorrules, AGENTS.md는 특정 툴에 종속되지만, ADR은 순수한 데이터입니다. 이는 나중에 Linter 설정으로 변환되거나, 다른 AI 모델(Claude, GPT)이 와도 즉시 이해할 수 있는 원천 소스가 됩니다.
즉, ADR은 '데이터베이스'이고, .cursorrules는 그중 현재 필요한 것만 뽑아 쓰는 '캐시(Cache)'가 되어야 합니다.
6. 자가 증식하는 팀의 지능 : 에이전트와의 구현 결과가 곧 계약이다
Agent-First 환경에서 스펙과 구현은 별개의 단계가 아닙니다. 에이전트와 대화하며 코드를 작성하는 과정 자체가 스펙을 정의하고 검증하는 과정입니다. 따라서 ADR은 미리 쓰는 계획서가 아니라, **치열한 구현 끝에 확정된 '기술적 판례'이자 '계약'**이어야 합니다.
1 상호작용 구현: 개발자가 에이전트와 치고받으며 기능을 구현합니다. 이 과정에서 라이브러리 선정, 패턴 결정 등 수많은 암묵적 합의가 검증됩니다.
2 결정체화: 구현이 성공하면 에이전트에게 명령합니다. "방금 짠 코드랑 대화 내용 중에서, 미래의 네가 꼭 알아야 할 아키텍처 규칙만 뽑아서 ADR로 요약해줘."
3 계약 체결: 에이전트가 뽑아낸 초안 중 '재사용 가능한 핵심 규칙'만 남깁니다.
이렇게 추출된 ADR은 저장소에 병합되는 순간 다음 에이전트의 지식이 됩니다. 개발자의 시행착오가 휘발되지 않고 시스템의 규칙으로 축적되는 것, 이것이 바로 에이전트와의 개발을 통해 자가 증식하는 팀의 지능입니다.