AI 에이전트 개발 시대에 필수적인 MADR이란 무엇인가? 지금이야말로 '결정의 기록'이 필요한 이유

코드를 읽으면 시스템이 어떻게 작동하는지는 알 수 있습니다. 하지만, 왜 그렇게 만들었는지는 코드 어디에도 쓰여 있지 않습니다.

"왜 캐시에 Redis를 사용하지 않는가", "왜 이 API만 동기적으로 호출하는가". 이러한 질문에 대한 답은 결정한 사람의 머릿속이나 당시의 대화 속에밖에 없습니다. 인간만으로 이루어진 팀이라도, 이 '왜'라는 것은 조금씩 사라집니다. AI 코딩 에이전트와 개발하게 되면서, 그것이 빠르고 조용히 사라지게 되었습니다.

본문에서는 그 '왜'를 남기기 위한 오래된 습관인 **ADR(Architecture Decision Record)**을 AI와 개발한다는 전제 하에 설명합니다. 후반부에서는 AI와의 대화에서 ADR을 초안하는 시스템을 만들었을 때 결정한 내용을 작성할 예정입니다.

ADR은 '결정 1건을 파일 1장'에 쓰는 것

ADR은 설계상의 결정 1건을 짧은 텍스트 파일 1장에 기록한 것입니다. 2011년 Michael Nygard가 "Documenting Architecture Decisions"라는 기사에서 제안했습니다. Thoughtworks의 Technology Radar에서도 경량 ADR은 '채택(Adopt)'으로 소개되어 왔습니다.

ADR을 이해하려면, 비슷한 것과의 차이점을 보는 것이 빠릅니다.

ADR은 시스템의 설명서가 아닙니다. 설명서는 시스템이 바뀌면 다시 쓰여집니다. ADR은 그 시점의 판단을 기록한 것이며, 나중에 다시 쓰지 않습니다. 생각이 바뀌면 새로운 ADR을 추가합니다(나중에 자세히 작성하겠습니다).

ADR의 형식은 몇 가지가 있지만, 본문에서는 현재 자주 사용되는 MADR(Markdown Architectural Decision Records) 버전 4에 따라 작성할 것입니다. MADR은 보관 위치와 파일명도 정해두었습니다. 보관 위치는 docs/decisions/이고, 파일명은 4자리 숫자에 제목을 하이픈으로 연결한 소문자 이름입니다.

docs/decisions/
├── adr-template.md
├── 0001-keep-orders-in-postgresql.md
...

adr-template.md는 MADR이 배포하는 템플릿을 해당 폴더에 둔 것입니다. MADR은 설명이 붙은 완전한 형태, 필수 섹션만 있는 최소 형태, 설명을 제외한 형태를 배포하고 있습니다.

한 장의 내용: MADR의 섹션들은 각각 하나의 질문에 답한다

Nygard의 원래 형태는 제목(Title)·상태(Status)·배경(Background)·결정(Decision)·결과(Result)의 5가지였습니다. MADR은 여기에 '무엇을 기준으로 선택했는지', '그 외 무엇을 비교했는지', '결정이 지켜지고 있음을 어떻게 확인할지'를 추가했습니다. MADR 한 장은 다음 형태입니다(내용은 한국어로 쓸 수 있습니다. 섹션 이름과 Chosen option이나 Good, because 같은 정해진 표현은 MADR 그대로 영어로 남깁니다).

---
status: accepted
date: 2026-09-30
...

섹션별로 답해야 할 질문이 정해져 있습니다. MADR에서 필수적인 것은 단 4가지이며, 나머지는 작성할 때가 되면 추가합니다.

섹션별로 답해야 할 질문이 정해져 있습니다. MADR에서 필수적인 것은 단 4가지이며, 나머지는 작성할 때가 되면 추가합니다.

• 새로운 의존성(라이브러리, 외부 서비스, 데이터베이스)을 추가하는 것
• 데이터의 형태나 스키마를 변경하는 것
• 새로운 타입을 도입하는 것(캐시, 큐, 재시도, 이벤트 기반)
• API의 약속을 변경하는 것
• 두 가지 이상의 방법을 비교하고 하나를 선택한 것

크기는 하나의 결정당 한 번입니다. '마이크로서비스로 마이그레이션한다'는 하나의 결정이 아닙니다. 서비스 경계, 서비스 간 통신 방식, 배치 방식을 각각 별도의 결정으로 봐야 합니다. '캐시에 Redis를 사용한다'와 'Redis는 관리형 서비스를 사용한다' 역시 별도의 ADR(Architecture Decision Record)을 작성해야 합니다. 한 문서에 너무 많은 것을 담으면, 일부만 변경되었을 때 대체하기가 어려워집니다.

왜 AI와 개발할 때 ADR이 필요한가

여기부터가 본론입니다. AI 에이전트와 개발하면 ADR의 필요성이 크게 달라집니다. 이유는 네 가지가 있다고 생각합니다.

1. AI는 세션마다 새로 온 사람이다

새로 온 개발자가 전례 없는 결정에 부딪혔다고 가정해 봅시다. 이유가 적혀 있지 않으면, 몇 시간 동안 조사하거나 그것을 '오류'로 간주하고 수정해 버립니다. ADR이 예전부터 권장되어 온 이유 중 하나가 바로 이 신입 사원의 문제였습니다.

AI 에이전트는 세션을 시작할 때마다 이 신입 사원과 같습니다. 이전 세션의 대화를 기억하지 못합니다. 긴 세션도, 문맥이 길어지면 요약되면서 세부 내용이 떨어집니다. 팀의 다른 사람이 사용하는 AI는 애초에 그 대화를 보고 있지 않습니다.

신입 사원의 문제가 회사에 입사할 때뿐만 아니라, 매일, 여러 번 발생하게 된 것이 가장 큰 변화입니다.

2. AI는 일반론적인 최선의 방법을 추천한다

AI의 제안은 일반적으로 좋은 아이디어입니다. Redis 캐시는 많은 프로젝트에서 올바른 선택입니다. 따라서, 이 프로젝트에서는 기각되었다는 사실을 모르는 AI는 순순히 Redis를 추천합니다. 프로세스 내부의 캐시를 보고

두 번째 줄이 중요합니다. '반박할 때는 명시적으로 지적하라'고 적어 놓으면, AI가 묵비권으로 트집을 잡는 것이 아니라, 'ADR-0004에서는 이렇게 결정했지만, 상황이 바뀌었으니 재검토하지 않겠습니까?'라고 상담하는 형태로 만들 수 있습니다. 재검토할지 여부는 사람이 결정합니다.

ADR은 리포지토리 내의 Markdown 파일이기 때문에 어떤 AI나 에디터, GitHub 화면도 동일하게 읽을 수 있습니다. 데이터베이스나 전용 서비스에 두면 AI는 그곳으로 갈 도구를 가지고 있지 않습니다. 단순한 파일이라는 것이 AI 시대에는 가장 큰 강점이 되었습니다.

흔히 하는 실수 (よくある失敗)

• 배경이 추상적이다. '빨리 해야 했다'로는 결정의 유효 기간을 판단할 수 없습니다. 숫자가 아니면, 적어도 구체적인 제약 조건을 작성해야 합니다.
• 비교한 안이 없다. 사후 정당화처럼 보입니다. '아무것도 하지 않는 것'도 하나의 안입니다.
• 한 장에 여러 결정이 있다. 일부만 변경되었을 때 대체할 수 없습니다.
• 상태가 오래된 채로 남아있다. 대체되었는데 accepted 상태인 ADR은 사람과 AI 모두를 오도합니다. 특히 AI는 적혀 있는 상태를 그대로 믿습니다.
• 설명서와 섞는다. '어떻게 작동하는지'는 README나 설계서에 작성하고, ADR에는 '왜'만 작성합니다.

제작한 것: AI의 옆에서 ADR을 운영하다

제가 만들고 있는 것은 Claude Code나 Codex를 탭으로 나란히 실행하는 Windows용 터미널(SHIKISHA-TERM)입니다. 여기에 오른쪽 열에 'ADR' 탭을 추가했습니다.

프로젝트 설정에서 '결정 기록 남기기'에 체크하면 사용할 수 있습니다 (기본값은 꺼져 있고, 저장 위치의 기본값은 docs/decisions입니다). 형식은 MADR 4를 따르며, 해당 폴더에 adr-template.md가 있으면 팀의 형식으로 그것을 사용합니다. 아래에서는 만들 때 결정한 사항들을 위의 설명과 대응시켜 작성하겠습니다.

대화에서 초안 만들기. 단, 대화에 없는 것은 쓰게 하지 않는다

'새 ADR' 폼에서 ✨를 누르면 현재 앞에 나온 AI 탭의 대화 내용으로부터 초안이 생성됩니다. 화면의 글자는 읽지 않습니다. Claude Code, Codex, Gemini CLI는 대화 기록을 파일로 남기기 때문에, 그 최신 부분을 어시스턴트 AI에게 전달하여 MADR 섹션별로 작성하게 합니다.

지시의 핵심은 위의 '함정'에 대한 대비입니다.

Use only what the conversation says. Do not add options, reasons or results it does not give, and leave out a section the conversation says nothing for.

형식 또한 MADR을 따르도록 합니다. Decision Outcome은 `Chosen option:

상담한 AI를 consulted에 남기기

MADR의 consulted는
(의견을 들은 상대방)이 RACI 모델의 'Consulted'에서 온 항목입니다. 사람에게 의견을 물었을 때 이름을 적는 것과 같아서, AI에게 의견을 물었다면 그렇게 쓰는 것이 자연스럽다고 생각했습니다. Claude Code 탭에서 초안 작성한 ADR에는 consulted: Claude Code (AI)라고 들어갑니다. 나중에 읽는 사람은 이 결정에 AI가 관여했다는 사실과 어떤 AI였는지 알 수 있습니다.

승인된 '편집'은 지우지 않고 회색으로 처리하기

승인된 ADR을 열면, '편집' 버튼이 회색으로 되어 있습니다. 누르면 '새로운 ADR로 대체할 것인지'와 '오타만 에디터에서 고칠 것인지' 두 가지 경로가 나옵니다. 대체하면, 새로운 ADR에 'Supersedes ADR-0002', 오래된 ADR에는 'superseded by ADR-0004'가 적히며 서로 링크됩니다.

버튼을 지우지 않은 이유는, 수정하지 않을 이유를 화면으로 설명하기 위해서입니다. 누를 수 없는 버튼이 침묵하면, 사람들은 다른 방법으로 수정합니다.

논의는 풀 리퀘스트로. 머지(Merge) 버튼은 두지 않기

'저장하고 풀 리퀘스트로 제안'은 ADR 파일만 커밋합니다(다른 파일이 스테이징 되어 있다면, 멈추고 이유를 요구합니다). main과 같은 보호 브랜치 위에서는, ADR 전용 브랜치를 분리한 후 GitHub에 풀 리퀘스트를 열게 됩니다.

머지 버튼은 두지 않았습니다. 채택할지 여부는 팀이 논의하여 결정하는 것이지, 작성한 사람의 로컬 앱이 결정하는 것이 아니기 때문입니다.

이름은 파일에만 적고, 이메일 주소는 쓰지 않기

'결정한 사람'을 위해 사용자 등록 기능을 추가할까도 생각했지만, 포기했습니다. ADR은 리포지토리 안에 들어가며, 리포지토리는 공개될 수 있습니다. 이름은 쓰는 사람이 폼에 적은 것을 파일에만 기록하고, 앱은 어디에도 기억하지 않습니다.

일본어 제목을 그대로 파일명으로 하기

파일명은 MADR의 규칙대로, 4자리 번호와 제목을 하이픈(-)으로 연결한 소문자 이름입니다. 다만, 영숫자로만 변환하면 일본어 제목이 사라지기 때문에, 문자(한자・가나・영문)와 숫자는 남기고, 영문만 소문자로 처리하며 나머지는 -로 하고 60글자로 자릅니다. 0004-주문 목록을 프로세스 내에 캐시하기.md

처럼 됩니다. 바이트 수로 자르면 일본어 1글자의 중간에서 잘릴 때가 있기 때문입니다.

기록에게 묻기

목록 위에서 질문하고 'AI에게 묻기'를 누르면, 어시스턴트 AI가 폴더의 ADR만 읽고 답변합니다. 답에 사용된 ADR을 ADR-0004처럼 명시하게(누르면 열립니다) 하고, 승인된 것은 '현재 유효', 대체된 것은 '더 이상 유효하지 않으며, 대안은 이것'으로 처리하게 합니다. ADR은 현재 유효한 것부터 순서대로 전달하므로, 양이 많을 때는 더 이상 유효하지 않은 것부터 떨어집니다.

그 외 (v0.24.0부터)

• 이 PC의 단말기가 앱을 닫아도 계속 움직임 (0.24.0) -
• 마스터 비밀번호로 앱 전체에 잠금 설정 가능 (0.25.0). 스마트폰에서도 해제 가능 -
• 브라우저 탭에 페이지 내 검색과 다운로드 목록 (0.25.0) -
• Markdown을 세 가지 방식으로 보기 (0.26.0). 텍스트・보는 그대로의 편집・미리보기. ADR도 미리보기로 읽고 PDF로 만들 수 있습니다.

자세한 변경 사항은 CHANGELOG에 있습니다.

맺음말

ADR은 결정 이유를 한 장씩 리포지토리에 남기는, 소박한 습관입니다. 사람만으로 이루어진 팀에서는 '적는 수고가 과하다'라는 말을 듣기 쉬웠습니다.

AI와 개발하면서 상황이 두 가지로 바뀌었습니다. AI는 매번 '새로운 사람'이 되므로, 이유가 적혀 있다는 것의 가치가 올라갔습니다. 결정에 이르는 대화가 손안에 있으므로, 작성하는 수고는 줄었습니다. 소박한 습관이 딱 맞는 도구가 된 것입니다.

우선 docs/decisions/를 만들고, 최근 결정 중 하나를 작성하고, CLAUDE.md나 AGENTS.md에 'ADR을 읽은 후 제안하기'라는 한 줄을 추가해 보세요. 대화부터 초안 작성까지 맡기고 싶은 분은 v0.26.0부터 사용하세요. Microsoft Store에서 받을 수 있습니다.

Discussion