ADR 은 되돌리기 어려운 결정의 이유만 남기고, 대안 기각은 옵션마다 줄을 나눈다

AI 에이전트와 함께 개발하면 설계 결정을 코드보다 먼저 문서에 남기게 된다. 에이전트는 대화를 기억하지 못하므로, 결정의 이유를 읽을 수 있는 곳이 문서뿐이기 때문이다. 이 글은 그 문서 가운데 ADR(Architecture Decision Record, 아키텍처 결정 기록)을 쓸 때의 기준을 정리한다. 어떤 결정을 ADR 로 남길지, 한 항목을 어떤 구조로 쓸지, 같은 템플릿인데도 읽기 좋은 ADR 과 읽기 어려운 ADR 이 갈리는 이유를 다룬다.

사례는 공개 저장소 fos-skills의 planning 스킬과 nhncloud-cli의 docs/adr/ 에서 가져왔다.

문서는 AI 의 컨텍스트로 읽힌다

사람이 읽는 문서라면 배경을 길게 설명해도 된다. 에이전트가 읽는 문서는 다르게 쓴다.

• 간결하게 쓴다. 읽을 때마다 컨텍스트를 쓰기 때문이다.
• 같은 내용을 두 번 쓰지 않는다. 한쪽만 고치면 두 문서가 어긋난다.
• "왜" 를 적는다. "무엇" 과 "어떻게" 는 코드가 말해 준다.
• 코드 스니펫은 넣지 않는다. 구현 세부는 코드가 가장 정확한 설명이다.

설계 결정은 구현 작업을 만들기 전에 먼저 문서로 커밋한다. fos-skills 의 planning 스킬은 영향을 받는 문서와 필요한 ADR 을 실제로 갱신한 뒤에 작업을 만들고, 문서에 적어야 할 결정을 작업 파일로 미루지 않는다. 구현이 끝난 뒤에는 작업 파일을 지운다. 현재 사실은 docs/ 와 코드가 소유하고, 계획서는 곧 낡아 틀린 근거가 되기 때문이다.

어떤 결정을 ADR 로 남기는가

모든 결정을 ADR 로 남기면 정작 구조를 정한 결정이 목록에 묻힌다. planning 스킬은 아래 둘 중 하나를 만족할 때만 ADR 로 남긴다.

둘 다 아니면 남기지 않는다. 라이브러리나 제품 선택은 교체 비용이 커도 핵심 개념을 바꾸지 않으면 ADR 이 아니다.

ADR 은 최종 상태만 담는다. 결정이 뒤집히면 이전 ADR 의 status 를 superseded 로 바꾸고 새 ADR 이 대체한 부분을 밝힌다. 이전 ADR 은 이력으로만 읽는다. 쌓이기만 하는 ADR 은 주기적으로 줄이고 폐기한다.

한 항목의 구조

planning 스킬의 ADR 템플릿은 결정 하나에 파일 하나를 쓰며 다음 항목으로 구성된다.

항목을 번호 있는 파일 하나로 나누는 이유는 끝에 계속 쌓이는 문서의 머지 충돌은 항목마다 파일을 나눠 없앤다에서 다룬다.

nhncloud-cli 의 ADR-017 이 같은 요소를 쓴 예다. 컨테이너 레지스트리의 이미지 목록을 조회할 방법을 정하는 결정이다.

• 맥락: 처음에는 Docker Registry 의 /v2/_catalog 를 우회로 가정했으나, 실측해 보니 시스템 관리자 전용이라 일반 자격으로는 401 이 났다. 실측 날짜가 함께 적혀 있다.
• 대안 기각: 세 가지 대안이 각각 한 줄씩 있고, 각 줄이 기각 이유를 말한다.
• 트레이드오프: 인증 모델이 하나 늘어나는 비용과, 사용자가 추가 설정을 하지 않아도 되는 이점을 함께 적는다.

같은 템플릿인데 읽기 쉬운 ADR 과 어려운 ADR

같은 템플릿(결정, 맥락, 대안 기각, 트레이드오프)을 쓰는 두 프로젝트의 ADR 문서를 비교한 적이 있다. 한쪽은 개인 CLI 도구의 ADR 열한 개였고, 다른 쪽은 운영 중인 백엔드 서비스의 ADR 스물다섯 개였다. 후자가 더 읽기 좋다는 관찰에서 시작해 원인을 분석했다.

결론은 가독성 차이가 템플릿에서 나오지 않는다는 것이다. 같은 템플릿에 줄 바꿈 규칙을 얼마나 엄격하게 적용했는가에서 나온다.

탐색만은 반대로 첫 번째 프로젝트가 나았다. 이상적인 ADR 은 두 장점을 합친 것이다.

쓸 때 지킬 규칙 여섯 가지

1. 대안 기각은 옵션마다 줄을 나눈다. Go(이유), Python(이유) 처럼 괄호로 이어 쓰면 대안 비교가 눈으로 되지 않는다. **옵션** — 이유 를 줄마다 끊는다.
2. 한 줄에 사실 하나만 쓴다. 200자를 넘는 줄은 정보 네 개가 뭉친 신호이므로 나눈다.
3. 모든 ADR 이 같은 호흡으로 쓴다. 한 파일 안에서 ADR 마다 밀도가 다르면 읽는 흐름이 끊긴다.
4. 파일 상단에 작성 원칙을 한 줄 둔다. "결정의 무엇과 왜와 대안만 쓰고, 구현 세부는 코드에 둔다" 같은 문장이 미래의 작성자에게 형식을 고정한다.
5. 근거는 실측값으로 쓴다. 측정한 수치와 확인한 날짜를 적으면 정성 서술보다 결정의 신뢰도가 오른다.
6. 목차를 둔다. 구분선만 있는 긴 문서보다 ADR 번호와 제목을 모은 목차가 있어야 특정 ADR 로 바로 간다.

nhncloud-cli 의 docs/adr/INDEX.md 는 여섯 번째 규칙을 따른다. 번호와 제목을 모은 목록 위에 번호 glob 으로 파일을 여는 방법을 적어 두었다. 전체를 읽지 않고 필요한 ADR 만 읽게 하려는 설계다.

변경 유형별로 읽을 ADR 을 정해 둔다

라이브러리 함정은 같은 곳에서 다시 터진다. 변경 유형별로 반드시 읽어야 하는 ADR 을 표로 정해 두면, 에이전트가 작업을 시작하기 전에 해당 ADR 을 읽도록 강제할 수 있다.

표의 행은 저장소의 ADR 에 맞춰 채운다. 예를 들어 "의존 라이브러리 교체" 행은 그 라이브러리를 고른 ADR 을 가리킨다.

정리