AI를 헷갈리게 하거나 되묻게 하지 않기 위해 ADR을 작성하는 이야기

AI에게 "적당히 고쳐줘"라고 부탁했더니,
과거의 판단을 무시한 구현이 돌아왔다 - AI에게 매번 "
Firebase / Stripe / AI API 키가 설정되지 않아 작동하지 않습니다"라고 지적받는다. 실제로는 키를 서버에 직접 수동으로 설정하거나, GitHub Secrets / GitLab CI/CD Variables / AWS Secrets Manager로 관리하고 있을 뿐인데, 매번 로컬에 없다는 것을 문제 삼아 설명해야 하는 상황이 발생한다 - 여러 AI 도구(Claude Code / Codex / Cursor) 간에 규칙이 어긋나서,
무엇이 정답인지 알 수 없게 된다 - 반년 전에 결정한 기술 선정 이유를 자신도 AI도 대답할 수 없다

저는 이 모든 것을 경험해 보았습니다. 그래서 여러 가지를 조사한 끝에 도달한 것이 바로 **ADR(Architecture Decision Record)**이었습니다.

이 기사에서는 ADR이란 결국 무엇인가? 어떻게 운영해야 지속될 수 있는가? 그리고 **AI 코딩과 결합하면 어떤 일이 일어나는가?**를 최소한의 범위에서 정리합니다.

먼저 정리해 두자면, ADR은 "설계 문서(Design Document)"와는 별개의 것입니다.

설계 문서	ADR
목적	현재 시스템의 전체상
...	...

ADR은 "결정된 순간의 판단"을 냉동 보관하는 이미지입니다.

나중에 그 판단이 뒤집히더라도 ADR을 수정하지 않고, **새로운 ADR을 작성하여 "Superseded by ADR-00XX"**라고 적습니다. 이 부분이 은근히 효과적입니다. "그때는 이렇게 생각했지만, 지금은 이쪽으로 결정했다"라는 이행 과정 자체가 자산이 됩니다.

파생 형태는 몇 가지 있지만, 처음에는 원전인 Nygard 형식이 가장 편합니다. 딱 5개 항목뿐입니다.

# ADR-0007: 디렉토리 구조를 기능별 (feature-based)로 통일한다
## Status
Accepted (2026-05-30)
...

이것뿐입니다. 「Decision(결정)」과 「Consequences(결과: 긍정적 영향과 부정적 영향 모두)」를 능동태로 작성하는 것이 요령입니다.

"~할 수 있다", "~가 된다"라고 단정 지어 말합니다. "~할 수도 있다"라며 모호하게 표현하지 않습니다.

여기서부터가 본론이자, 제가 가장 전달하고 싶은 부분입니다.

Claude Code나 Codex 같은 AI 코딩 지원을 사용하게 되면서, ADR의 가치가 한 단계 높아졌다는 실감이 듭니다. 이유는 5가지입니다.

AI는 지시받은 태스크에는 강하지만, "이 프로젝트가 무엇을 피하고 싶어 하는지", "왜 지금 이 구성인지"는 모릅니다.

ADR을 docs/adr/에 두면, AI가 "이 변경 사항은 ADR-0007과 모순되지 않나요?"라고 알아차릴 확률이 훨씬 높아집니다. 실제로 저는 CLAUDE.md나 AGENTS.md에 "중요한 설계 판단은 docs/adr/를 참조할 것"이라고 적어두는 것만으로도, 빗나간 제안이 눈에 띄게 줄었습니다.

AI가 제안한 코드에 대해, "이것은 ADR-0012에 적힌 방침과 다르다"라고 인간이 즉각적으로 판단할 수 있습니다.

리뷰 기준이 머릿속에만 있으면 AI의 출력이 늘어날수록 판단 피로도가 높아집니다. 외부화된 리뷰 기준으로서의 ADR은 AI 시대에 오히려 필요성이 높아집니다.

"앞으로 하려는 변경 사항에 대해 Nygard 형식으로 ADR 초안을 작성해줘"라고 부탁하면, 논점의 누락이나 대안 검토 미비 등을 보완해 줍니다.

사람이 작성하면 번거로웠던 Context(맥락)나 Consequences(결과)의 망라성이 AI의 도움으로 한 단계 높아집니다. 작성 허들이 낮아지므로 운영을 지속하기 쉬워진다는 효과가 서서히 나타납니다.

이 부분이 개인적으로는 가장 클지도 모릅니다.

평소 프론트엔드와 백엔드를 모두 다루면서 곤란한 점은, 코드를 읽어도 알 수 없는 규칙의 존재입니다. 예를 들어:

• 인프라 계층 / 애플리케이션 계층 / 모바일 앱 계층의 책임 분계(이 유효성 검사는 앱 측, 속도 제한은 인프라 측과 같은 구분)
• API 키 및 시크릿 관리 정책

Firebase / Stripe / AI API 키는 로컬의 .env

로컬에도 두지 않는다. 실제 저장 위치는 다음 중 하나이다:

• 프로덕션 서버에 접속하여 수동으로 환경 변수(Environment Variable)로 설정한다
• GitHub Secrets (Repository / Environment / Organization)
• GitLab CI/CD Variables (Masked / Protected 옵션)
• AWS Secrets Manager / AWS Systems Manager Parameter Store

로컬 환경에서는 키가 설정되어 있지 않거나 샘플 키가 들어있는 경우가 많아서, AI가 매번 "키가 없어서 동작하지 않습니다"라고 지적하곤 한다. 여기에는 두 가지 해결 방법이 있다:

• 새로운 서비스를 도입하는 타이밍에 ADR에 작성해 둔다: 예를 들어 "Stripe를 도입한다", "Firebase를 도입한다"라고 결정했을 때, 해당 ADR 안에 **"로컬 환경에서는 키 미설정이 정상 상태임. 프로덕션은 GitHub Secrets로부터 주입함"**이라고 한 줄만 넣어둔다. 이것만으로도 다음에 AI가 이 프로젝트를 다룰 때 동일한 지적을 하지 않게 된다.
• 규칙(Rule) 측 / 서브 에이전트(Sub-agent) 측에서 차단한다: ADR이 아니더라도 동일한 문제를 해결할 수 있다. 규칙 파일(CLAUDE.md, .cursor/rules 등)에 직접 작성하거나, 리뷰용 서브 에이전트 또는 스킬을 준비하여 그곳에서 체크하도록 하는 선택지도 있다.

ADR이 유일한 해결책은 아니므로, 자신의 워크플로(Workflow)에 맞는 방법을 선택하면 된다. 다만 여러 AI 도구를 병용한다면, 최종적으로 ADR을 단일 소스(Single Source)로 만들어 두는 편이 편하다.

이러한 사항들은 코드상에 작성되어 있지 않기 때문에, AI에게 "적절하게 수정해 줘"라고 부탁하면 매번 규칙을 벗어난 제안이 돌아온다. 판단 기준을 전달하지 않으면 AI 리뷰어(AI Reviewer)도 동일한 지적을 반복한다.

ADR을 한 건 작성해 두면, 사람의 리뷰도 AI의 리뷰도 동일한 단일 소스(Single Source)를 참조할 수 있다.

덤으로 "왜 그것을 채택하지 않았는지" (기각된 선택지)도 남길 수 있으므로, "왜 여기서 ○○를 사용하지 않나요?"라고 AI가 제안하는 낭비도 없앨 수 있다.

이 또한 체감상 효과가 매우 크다.

나는 Claude Code와 Codex를 모두 사용하는 경우가 많은데, AI 코딩 도구는 각각 고유한 설정 파일을 가지고 있다.

도구	설정 파일
Claude Code	CLAUDE.md
...

동일한 규칙을 각 파일에 중복해서 복사-붙여넣기 하는 것은 작성하기도 힘들 뿐만 아니라, 규칙이 어긋나면 어느 쪽이 정답인지 알 수 없게 된다. CLAUDE.md를 업데이트했는데 AGENTS.md 업데이트를 잊어서, Codex만 옛날 규칙으로 동작하고 있는... 식의 상황이 흔히 발생한다.

그래서, 진정한 판단 기준은 docs/adr/에 둔다고 결정해 버리고, 각 도구의 설정 파일에는 "중요한 설계 판단은 docs/adr/를 참조할 것"이라고 한 줄만 적어둔다. 그러면:

• Claude Code에서도 Codex에서도 동일한 판단 기준으로 동작한다.
• 규칙을 업데이트할 때는 ADR 파일 하나만 수정하면 된다.
• "Claude에서는 통과된 제안이 Codex에서는 거절되는" 식의 편차가 줄어든다.
• 새로운 AI 도구를 테스트할 때도 docs/adr/를 참조하게 하는 것만으로 즉시 시작할 수 있다.

요컨대 **ADR이 AI 간의 "single source of truth" (단일 진실 공급원)**가 되는 방식이다.

팀 내에서 여러 AI를 병용하는 흐름은 앞으로도 늘어날 것이라고 생각하므로, 여기서 한 번 "벤더 비의존적인 팀 규칙 저장소"를 만들어 두면 도구의 교체나 추가가 한결 수월해진다.

좋은 점만 썼지만, 당연히 함정도 있다. 오히려 이쪽이 본론일지도 모른다.

"결정된 후에 AI에게 ADR을 쓰게 하자"가 가장 위험하다.

당시의 논점이나 기각된 대안의 생생함이 빠진 채, "정답 같아 보이지만 알맹이가 없는" ADR이 양산된다. Olaf Zimmermann이 말하는 "Fairy Tale" 안티 패턴(장점(Pros)만 적음 / 대안을 단 하나만 검토함)에 AI 생성 ADR은 빠지기 쉽다.

→ 판단의 과정 중에 사람이 논점을 쏟아내고, AI에게 정형화(Formatting)를 시키는 정도의 역할 분담이 딱 적당하다.

ADR은 '그 시점에서의 판단'이지, 영원한 정답이 아닙니다. 하지만 AI에게 "ADR을 참조해"라고 말하면, 오래된 ADR을 맹신하여 상황이 변한 지금의 문맥에 맞지 않는 제안을 돌려주는 경우가 있습니다.

→ Deprecated / Superseded 상태 관리를 소홀히 하면 AI에게도 사람에게도 지뢰가 됩니다. 상태의 신선도는 AI 시대에 더 엄격하게 관리되어야 합니다.

ADR의 초안은 AI에게 맡겨도 OK, 아니 오히려 어시스턴트로서 최대한 활용하는 것이 좋습니다. 논점 정리나 망라성(Comprehensiveness) 체크도 AI의 특기 분야입니다.

다만, 생성된 문장을 그대로 커밋하지 마세요. 마지막에 사람이 한 번 다시 읽어보고, 2~3곳만 고쳐 쓰는 것만으로도 가독성이 완전히 달라집니다.

구체적으로는:

• "중요합니다", "다음과 같은 점을 들 수 있습니다", "총괄하자면"과 같은 AI 특유의 서론이나 결론을 덜어내기
• "~할 수 있습니다"를 "~할 수 있다"로 단축하기
• 경험담이나 위화감이 느껴지는 부분은 자신의 언어로 바꾸기

ADR은 최종적으로 사람이 판단을 이어받기 위한 것이므로, AI의 초안 + 사람의 최종 체크가 딱 적당한 역할 분담입니다.

처음부터 사람이 쓸 필요는 없지만, 그렇다고 검토만 하고 바로 머지(Merge)하는 것도 아닌, 그 사이 정도의 균형입니다.

그대로 두면 AI는 너무 친절하게 글을 씁니다. 3,000자짜리 ADR이 양산되면 아무도 읽지 않게 됩니다.

**"파일당 500자 기준, 이를 초과하면 입도(Granularity)가 너무 크다는 신호"**를 사람 측의 가드레일(Guardrail)로 삼아두는 것이 좋습니다.

AI 관련 내용을 제외하더라도, 두 가지 효과가 있었습니다.

1. 반년 뒤의 내가 도움을 받는다

ADR을 작성해 두면, 시간이 흐른 뒤에 다시 돌아와도 "왜 이렇게 했는지"를 즉시 알 수 있습니다. 미래의 나에게 쓰는 편지로서 효과적입니다. AI에게 물어봐도 답을 얻을 수 없는(코드에 적혀 있지 않기 때문에) 정보이므로, 이것은 ADR에만 남길 수 있는 가치입니다.

2. 쓰는 과정에서 논점이 명확해진다

이것은 의외의 부작용이었습니다. Context(맥락)와 Consequences(결과)를 쓰려고 하면, "어라, 나 이 관점을 제대로 생각하지 않았네"라고 깨닫는 경우가 꽤 많습니다. 쓰는 행위 자체가 사고의 도구가 됩니다. AI에게 초안을 쓰게 하고, 스스로 태클을 거는 방식과도 궁합이 좋습니다.

• ADR은 "중요한 설계 판단의 이유"를 남기는 짧은 문서
• Nygard 형식의 5개 항목(Status / Context / Decision / Consequences)부터 시작하면 OK
• 한 번 확정된 판단은 고쳐 쓰지 않는다. 뒤집혔다면 새로운 ADR을 만들고 "Superseded by ADR-XXX"로 링크를 연결
• AI 시대의 장점: 과거의 판단을 AI에게 전달 가능 / 리뷰 기준이 됨 / 집필 어시스턴트가 됨 / 코드에 나타나지 않는 규칙을 전달 가능 / 여러 AI 도구의 공통 언어가 됨
• AI 시대의 주의점: 사후 생성 / 오래된 ADR 맹신 / AI 문체 그대로 커밋 / 너무 많이 쓰기
• AI 초안 + 사람의 최종 체크가 적당한 분담

설계의 "왜(Why)"가 흘러가 버리는 느낌이 든다면, 밑져야 본전이라는 생각으로 3개만 써보세요. AI와 협업하고 있다면 더욱 그렇습니다.

• Documenting Architecture Decisions — Michael Nygard (원전)
• Architecture Decision Record — Martin Fowler bliki
• adr.github.io — ADR 커뮤니티의 허브
• adr/madr — MADR 공식
• joelparkerhenderson/architecture-decision-record — ADR 종합 가이드 모음
• npryce/adr-tools — bash 기반 번호 매기기 CLI
• How to create ADRs — and how not to (Olaf Zimmermann) — 안티 패턴 모음