에이전트 AI - O’Reilly Radar, 코딩 에이전트의 Architectural Decision Records (ADRs)

https://oreillyradar.substack.com/p/coding-agents-love-decision-records

2026.10.30
[Coding Agents Love Decision Records]

소프트웨어 개발 프로젝트에서 아키텍처 결정 기록(ADRs)은 인간 개발자뿐만 아니라 코딩 인공지능 에이전트에게도 핵심적인 맥락을 제공하는 중요한 도구이다. 에이전트는 제한된 기억력과 시야를 극복하고 프로젝트의 숨은 의도를 정확히 파악하기 위해 이러한 기록에 크게 의존한다. 그러나 에이전트는 규칙을 지나치게 엄격하게 따르는 성향이 있어, 쓸모없어진 과거의 지침까지 맹목적으로 고수하거나 불필요하게 장황한 수정 이력을 남기는 부작용을 낳기도 한다. 따라서 개발자는 명확한 지침을 통해 에이전트가 현재 유효한 결론에만 집중하도록 돕고, 규칙이 현실과 맞지 않을 때는 과감하게 의문을 제기할 수 있는 권한을 부여해야 한다.

• 저자: Duncan Davidson
• 매체: O’Reilly Radar — 저자 블로그 글을 허락받아 재게시
• 재게시일: 2026년 10월 2일
• 성격: 코딩 에이전트를 활용한 프로젝트 운영 경험에 기반한 실무 에세이입니다. 통제 실험이나 성능 벤치마크를 제시하는 연구 논문은 아닙니다.[1]

핵심 주장은 “에이전트에게 기억을 더 많이 주자”가 아니라, “현재 유효한 결정·그 결정의 이유·충돌 시 처리 절차를 명확히 제공하자”입니다.

원문에는 별도의 챕터 제목이 없습니다. 아래는 실제 문단 진행 순서에 따라 재구성한 분석용 6개 절이며, 원문 주장과 분석·권고를 구분했습니다.

 

2. 챕터 1 — ADR: 코드를 설명하는 문서가 아니라 ‘선택의 이유’를 보존하는 문서

원문의 내용

저자는 ADR, 즉 Architectural Decision Record — 아키텍처 의사결정 기록을 중요한 설계 선택, 당시의 맥락, 선택 이유를 담는 기록으로 설명합니다. 인간 팀이 규칙을 정하고 맥락을 이어가기 위해 사용하는 ADR이 코딩 에이전트에도 유용하다는 것이 출발점입니다.[1][2]

분석

이 절의 핵심은 구현 결과와 의사결정 근거의 차이입니다.

코드를 읽으면 “무엇을 구현했는가”는 확인할 수 있지만, “왜 다른 대안을 배제했는가”까지 알기는 어렵습니다. 예를 들어 특정 저장소나 API 구조를 사용한다는 사실만으로는 다음을 구분하기 어렵습니다.

• 성능·보안·계약상의 제약 때문에 선택했는가?
• 당시 개발 편의 때문에 임시로 선택했는가?
• 이후에도 반드시 유지해야 하는 원칙인가?

ADR은 구현에서 추론하기 어려운 ‘선택의 이유와 적용 맥락’을 명시하는 장치로 해석할 수 있습니다.

실무 시사점

분석·권고: ADR 작성 대상은 모든 구현 세부사항이 아니라, 이후 작업에서 반복적으로 참조할 만한 지속성 있는 제품·아키텍처 결정으로 제한하는 편이 적절합니다.

ADR 후보	일반 작업 기록으로 충분한 내용
서비스 간 통신 방식과 선택 이유	특정 함수의 변수명 변경
데이터 격리·보존 전략	일회성 디버깅 과정
인증·인가 구조	단순 코드 정리
주요 기술 선택과 배제한 대안	일상적인 개발 진행 상황

이 구분이 없으면 ADR이 설계 기준이 아니라 작업 일지로 변합니다.

 

3. 챕터 2 — 에이전트의 문제는 ‘기억 부족’만이 아니라 ‘기억의 유효성 불명확’이다

원문의 내용

저자는 에이전트가 이전 작업에 대한 기억이 적고 코드베이스를 제한적으로 이해한 상태에서 시작하는 경우가 많다고 설명합니다. 또한 영속 메모리가 있더라도, 보존된 정보가 정확한지, 최신인지, 인간 팀이 수용한 것인지까지 보장되지는 않는다고 지적합니다.[2]

저장소 안에 의사결정 기록을 두면 이슈·채팅·과거 코드를 뒤져 의도를 재구성할 필요가 줄고, 구현 세부사항을 근본적인 규칙으로 오인할 가능성도 줄어든다는 주장입니다.[1][2]

분석

이 글에서 가장 중요한 구분 중 하나는 다음과 같습니다.

정보가 남아 있다는 사실과, 그 정보가 현재 작업을 지배할 권한이 있다는 사실은 다릅니다.

예를 들어 “이 프로젝트는 저장 방식 A를 사용한다”는 메모만 존재하면 다음이 모호합니다.

• 현재도 유효한가?
• 검토 중인 제안인가?
• 이미 폐기된 결정인가?
• 구현 현황을 묘사한 것인가, 준수해야 하는 규칙인가?

따라서 단순한 메모리 확장만으로는 해결되지 않고, 정보에 상태와 권위를 부여해야 한다는 방향으로 논지가 이어집니다.

한계

“ADR이 탐색 부담과 오해를 줄인다”는 주장은 타당한 실무 가설이지만, 본문에는 탐색 시간·토큰 비용·오류율을 비교한 측정 결과가 없습니다.[2]

따라서 “효율 향상이 기대된다”고 해석할 수는 있어도, 특정 수준의 생산성 개선이 검증되었다고 말할 수는 없습니다.

실무 시사점

분석·권고: 에이전트에게 제공하는 프로젝트 지식은 다음 세 가지를 구분해야 합니다.

• 사실: 현재 구현이 어떻게 되어 있는가?
• 결정: 앞으로 무엇을 따라야 하는가?
• 이력: 과거에 무엇을 검토하거나 사용했는가?

세 범주를 같은 권위로 읽게 하면, 과거의 사실이 현재의 제약으로 변할 수 있습니다.

 

4. 챕터 3 — 첫 번째 실패: 폐기되어야 할 결정을 지나치게 충실하게 따른다

원문의 내용

저자는 자신의 프로젝트에서 에이전트가 이미 낡은 결정을 강하게 고수하는 모습을 관찰했다고 설명합니다. 구체적으로, ADR이 오래된 저장소 추상화를 필수로 규정하고 있어 에이전트가 신규 기능에도 이를 유지한 사례를 제시합니다.[2]

에이전트는 새 요구사항과 기존 결정의 불일치를 알리는 대신, 추가 계층을 도입하여 과거 결정과 형식적으로 호환되게 만들었습니다.[1][2]

분석

이 사례는 단순한 “지시 불이행”의 반대편에 있는 문제입니다.

에이전트가 규칙을 어겨서 실패한 것이 아니라, 잘못된 규칙을 너무 충실하게 지켜서 설계를 복잡하게 만든 것입니다.

이를 분석 관점에서 정리하면 다음과 같습니다.

새 요구사항 발생 ↓ 기존 ADR과 충돌 ↓ 충돌을 보고하지 않고 기존 ADR 유지 ↓ 우회 계층 추가 ↓ 불필요한 설계 복잡성 발생

 

이 흐름은 원문 사례를 재구성한 것으로, 모든 에이전트에서 검증된 일반 법칙은 아닙니다.

실무 시사점

분석·권고: “ADR을 준수하라”는 지시만으로는 부족합니다. 준수 지침과 함께 충돌 감지·중단·변경 제안 절차가 필요합니다.

특히 다음 상황은 재검토 신호로 볼 수 있습니다.

• 기존 결정을 유지하기 위해서만 새로운 추상화 계층이 필요하다.
• 원래 결정의 전제와 현재 요구사항이 달라졌다.
• 보안·성능·운영 요구를 만족하려면 예외가 반복된다.
• ADR과 실제 구현이 서로 다른 방향을 가리킨다.

다만 충돌을 발견했다고 해서 에이전트가 스스로 기존 결정을 폐기하는 것은 별개의 문제입니다. 원문의 지침도 일단 멈추고 논의하라는 방향입니다.[2]

 

5. 챕터 4 — 두 번째 실패: 의사결정 기록이 ‘논쟁의 속기록’으로 변한다

원문의 내용

저자는 에이전트에게 낡은 결정을 의심하고 업데이트하도록 허용하면 또 다른 문제가 나타난다고 설명합니다. 에이전트가 검토 과정 자체를 보존하려 하면서 다음 현상이 발생한다는 것입니다.[2]

• 설명을 보충할 때마다 수정 이유를 덧붙인다.
• 작은 구현 세부사항을 규칙으로 승격한다.
• 다른 ADR을 참조하면서 같은 내용을 다시 설명하고 정당화한다.
• 결과적으로 인간이 읽기 어려운 장황한 문서가 된다.[1][2]

분석

앞선 절이 규칙의 경직성 문제였다면, 이 절은 문서의 과잉 축적 문제입니다.

둘은 상반되어 보이지만 공통점이 있습니다.

과거 정보를 충분히 정리하지 못하면, 현재 판단에 필요한 정보가 흐려집니다.

의사결정 기록은 “현재 무엇이 유효하고 왜 그런가”를 빠르게 알 수 있어야 합니다. 모든 논쟁과 수정 경위를 본문에 남기면 독자가 현재 규칙을 다시 추출해야 합니다.

구분	의사결정 기록	논쟁·수정 과정의 기록
주된 질문	현재 무엇을 따라야 하는가?	어떻게 이 결론에 도달했는가?
중심 내용	결정·근거·적용 맥락	의견 교환·수정 경위
적합한 위치	현재 ADR 본문	Git 이력, 검토 기록, 관련 이슈
위험	근거를 지나치게 생략	현재 규칙을 장황한 이력 속에 묻음

실무 시사점

분석·권고: 간결함은 “이유를 삭제한다”는 뜻이 아닙니다.

• 유지할 내용: 현재 결정, 적용에 필요한 근거, 중요한 제약
• 별도 이력으로 분리할 내용: 반복된 설명, 수정 과정, 중복 규칙

저자도 결론에서 결정을 적용할 수 있을 만큼의 근거는 남겨야 한다고 강조합니다.[2]

 

6. 챕터 5 — AGENTS.md로 ADR의 권위와 변경 절차를 명시한다

이 절은 글에서 가장 실행 가능성이 높은 부분입니다. 저자는 자신의 프로젝트에서 사용하는 AGENTS.md 지침을 제시합니다.[1][2]

6.1 상태별로 문서의 권위를 구분

상태	원문에서 부여한 의미	작업에 대한 효력
Accepted	수용된 결정	구속력 있는 기준
Proposed	제안 단계의 결정	참고 맥락이며 비구속적
Superseded	다른 결정으로 대체된 기록	역사적 맥락이며 현재 작업을 지배하지 않음

상태를 구분하는 목적은 단순한 문서 정리가 아니라, 에이전트가 어떤 내용을 규칙으로 적용해야 하는지 명확히 하는 것입니다.[2]

6.2 작업과 유효한 ADR이 충돌하면 중단·논의

원문 지침은 작업이 Accepted ADR과 충돌할 경우 다음을 요구합니다.

1. 멈춘다.

1. 작업을 바꿀지 ADR을 바꿀지 논의한다.

1. 에이전트가 적절하다고 판단하는 변경안을 제시한다.[2]

분석: 에이전트의 역할은 충돌을 숨기거나 독단적으로 규칙을 바꾸는 것이 아니라, 충돌을 드러내고 선택지를 제안하는 것입니다.

6.3 본문과 변경 이력을 분리

저자의 프로젝트 관례는 다음과 같습니다.[2]

항목	원문 지침
저장 위치	docs/decisions의 Markdown 파일
ADR 본문	현재 내용만 유지
변경 이력	Git history 사용
본문 내 수정 로그	헤더에 추가·유지하지 않음
수용된 ADR의 실질적 변경	Date: 다음에 단일 Updated: 날짜를 추가·갱신
대체된 ADR	Updated: 대신 Superseded-On: 날짜 기록
대체 관계	새 ADR의 Supersedes:와 연결
규칙의 중복	소유 ADR에서 한 번만 명시하고 다른 ADR에서는 교차 참조

분석상 중요한 한계

이것은 저자의 프로젝트 관례이지, 모든 팀이 따라야 하는 단일 표준은 아닙니다.

저자는 직접 수정하는 방식 대신, 기존 ADR을 불변으로 두고 새 ADR로 대체하는 방식을 선호하는 팀도 있을 것이라고 인정합니다.[2]

또한 제시된 AGENTS.md 지침에는 다음이 구체적으로 정의되어 있지 않습니다.

• 누가 Accepted 상태를 승인하는가?
• 변경 승인권자는 누구인가?
• 어떤 검토·증거를 거쳐 승인하는가?
• 에이전트의 수정 권한을 도구 수준에서 어떻게 제한하는가?

따라서 텍스트 지침은 운영 원칙이지, 변경 권한을 강제하는 기술적 통제 자체는 아닙니다.

 

7. 챕터 6 — 결론: 필요한 것은 모든 논쟁이 아니라 ‘오늘의 유효한 결정’이다

원문의 내용

저자는 팀마다 관례가 다를 수 있다고 전제하면서, 핵심 원칙을 다음과 같이 정리합니다.

• 현재 작업을 지배하는 ADR은 현재 유효한 결정을 설명해야 한다.
• 결정을 적용할 만큼의 근거를 제공해야 한다.
• 에이전트는 모든 논쟁의 기록을 필요로 하지 않는다.
• 결정이 더 이상 맞지 않을 때 멈출 수 있는 명확한 허용이 필요하다.[1][2]

분석

글의 전체 논리는 다음처럼 연결됩니다.

 

의도를 추론하기 어렵다 → ADR로 결정과 근거를 명시한다   낡은 결정을 과도하게 따른다 → 상태를 구분하고 충돌 시 멈추게 한다   수정 과정이 문서를 비대하게 만든다 → 현재 규칙과 과거 이력을 분리한다   인간이 검토하기 어렵다 → 간결한 본문과 중복 없는 규칙을 유지한다

 

이 글은 ADR 작성법에 대한 조언이면서, 동시에 에이전트가 따를 프로젝트 지식의 유효성을 관리하는 방법에 관한 글입니다.

 

8. 비판적 평가 — 무엇이 입증되었고, 무엇이 남아 있는가?

평가 항목	원문이 제공하는 근거	해석의 범위
ADR의 에이전트 활용 가치	저자의 경험과 작동 이유 설명	실무적으로 설득력 있는 제안
낡은 결정의 과도한 준수	오래된 저장소 추상화 유지 사례	사례 기반 관찰
문서의 과잉 설명	저자의 반복 경험에 대한 기술	정성적 관찰
AGENTS.md 운영 규칙	실제 사용하는 지침 발췌	적용 가능한 운영 사례
생산성·비용 개선	정량 비교 없음	개선 폭은 확인 불가
에이전트·모델 간 일반화	모델·버전·표본 정보 없음	보편적 효과는 확인 불가
승인·권한 통제	상세 절차 없음	별도 설계 필요

위 한계는 글의 가치가 없다는 뜻이 아니라, 운영 경험을 일반적인 성능 보장으로 확대해석하지 않아야 한다는 의미입니다.[2]

 

9. 공공 AI 사업·감리 관점의 적용

아래는 원문에 직접 제시된 내용이 아니라, 공공사업 및 품질보증 관점으로 확장한 분석·권고입니다.

9.1 ADR을 요구사항·변경관리와 연결

공공사업에서는 ADR만 독립적으로 관리하면 “기술적으로 합리적인 결정”과 “승인된 사업 범위”가 어긋날 수 있습니다.

권장 연결 구조는 다음과 같습니다.

REQ-ID ↕ ADR-ID — 승인 상태·선택 근거·적용 범위 ↕ 설계·구현 산출물 ↕ 시험·검증 증거

결정 변경 시에는 영향받는 요구사항과 설계·시험 항목도 함께 검토할 수 있어야 합니다.

9.2 우선순위별 보완 사항

우선순위	보완 사항	확인할 증거
높음	[보완 필요] 승인 주체·권한 명시	승인자, 승인일, PR·결재 기록
높음	[보완 필요] 충돌 시 작업 중단 범위 정의	중단·보고·재개 절차
높음	[확인 필요] 현재 유효한 ADR 식별	상태, 대체 관계, 구현과의 정합성
중간	[보완 필요] 요구사항과 변경 영향 연결	REQ-ID, 영향 분석, 회귀시험 항목
중간	[확인 필요] Git 이력의 추적·보존 가능성	저장소 접근, 이력 보존, 인수인계 방식
후순위	[보완 필요] 중복·장황한 기록 정리	규칙 소유 문서, 교차 참조, 문서 검토 결과

특히 “Git이 이력을 담당한다”는 방식과 “감사 가능한 승인·변경관리 체계가 있다”는 판단은 동일하지 않습니다. 승인과 추적 가능성을 별도로 확인해야 합니다.

 

종합 결론

이 글의 실무적 가치는 ADR을 많이 작성하라는 데 있지 않고, 에이전트가 따라야 할 결정의 권위와 유효성을 명확히 관리하라는 데 있습니다.

적용 원칙은 세 가지로 압축됩니다.

1. 현재 유효한 결정과 과거 기록을 구분한다.

1. 결정과 작업이 충돌하면 우회 구현보다 중단·논의를 우선한다.

1. 본문에는 현재 결정과 필요한 근거를, 이력에는 변경 과정을 남긴다.

공공 AI 사업이나 감리에서는 여기에 승인권자·REQ-ID·변경 영향·검증 증거를 연결해야, 에이전트용 맥락 문서가 실제로 검토 가능한 의사결정 관리체계로 발전할 수 있습니다.

출처

[1] O’Reilly Radar — Coding Agents Love Decision Records
[2] Duncan Davidson — Coding agents love decision records