에이전트에게 ADR만 주고 구현하게 하려면?

채팅으로 “대충 이렇게 해줘”만 넘기면, 에이전트는 범위·대안·합격 기준을 스스로 채웁니다. 에이전트 ADR 구현은 그 채움값을 줄이기 위해 Architecture Decision Record(ADR) 한 장(또는 소수) 을 유일한 구현 스펙으로 두고, 코드·검증은 그 문서의 경계 안에서만 하게 하는 방식입니다.

이 글은 **필수 섹션은? · 코드 범위를 어떻게 제한? · 검증 단계는?**만 다룹니다. 제품·벤더 홍보, 요금·제휴는 없습니다. 근거는 MADR 템플릿(Context / Options / Decision Outcome / Consequences / Confirmation)과, Nygard식 ADR의 Context · Decision · Consequences 최소 골격입니다.

ADR에 필수 섹션은?

한 줄 답: 에이전트 위임용 ADR에는 최소한 Context and Problem Statement · Considered Options · Decision Outcome(+Consequences) · Confirmation(검증 방법) 이 있어야 합니다. 제목·status만 있는 메모는 스펙이 아닙니다.

MADR full template에서 에이전트가 실제로 읽는 핵심만 고르면 다음과 같습니다.

섹션	에이전트에게 주는 신호	빠지면 생기는 일
Context and Problem Statement	무엇을 풀지, 비목표는 무엇인지	인접 모듈까지 “개선”
Decision Drivers (권장)	품질·제약·KO 기준	옵션을 취향으로 고름
Considered Options	선택지 목록(선택하지 않은 것도)	문서에 없는 제3안 도입
Decision Outcome	Chosen option + because	구현 중 슬며시 옵션 교체
Consequences	Good/Bad 결과	부작용을 코드로 메우려다 범위 폭주
Confirmation	리뷰·테스트·아키 규칙으로 확인	“돌아간다”만으로 done

최소(MADR bare)만 쓸 때도 Context · Considered Options · Decision Outcome · Consequences는 비우지 않습니다. 에이전트용으로는 Confirmation을 사실상 필수로 올립니다. “어떻게 맞는지 재현 가능한가”가 없으면 Done 게이트를 걸 수 없습니다.

메타데이터(status, date, deciders)는 사람·감사 추적용입니다. 구현 프롬프트에는 accepted(또는 equivalent) ADR만 넘기고, proposed/deprecated는 위임 대상에서 제외합니다.

복붙용 에이전트 프리앰블 예:

You implement ONLY what ADR-NNNN decides.
Do not reopen Considered Options.
Do not invent a 4th option.
Out of scope = anything not required by Decision Outcome + Confirmation.
If ADR text conflicts with existing code, STOP and report the conflict; do not “fix by rewriting neighbors”.

경계: ADR은 결정 기록이지 API 스펙 전체가 아닙니다. 인터페이스 세부는 링크된 OpenAPI/코드 스켈레톤을 More Information에 두고, 본문 Decision Outcome에는 선택과 이유만 남깁니다.

코드 범위를 어떻게 제한하나?

한 줄 답: ADR 본문에 허용 경로·금지 경로·완료 정의(DoD) 를 명시하고, 에이전트 Skill/Rule에 경로 allowlist + “옵션 재논의 금지” 를 같은 문구로 고정합니다. “레포 전체에서 알아서”는 범위가 아닙니다.

실무에서 쓰는 제한 축:

축	ADR/프롬프트에 적을 것	실패 신호
경로	`src/billing/`, `tests/billing/`만	무관 패키지 diff
결정 고정	Chosen option 이름 그대로	다른 라이브러리/패턴으로 교체
비목표	“마이그레이션·리네임·포맷 전체 금지”	대규모 정리 커밋
의존성	신규 패키지 금지 또는 허용 목록	문서에 없는 dep 추가
인터페이스	공개 API 시그니처 변경 금지(해당 시)	호출부 연쇄 수정
커밋	한 ADR = 한 논리 변경(또는 명시된 N커밋)	잡동사니 섞임

ADR 하단(또는 More Information)에 Implementation Boundary 블록을 둡니다.

## Implementation Boundary (agent)
- Allow paths: src/payments/retry/**, tests/payments/retry/**
- Forbid: src/payments/legacy/**, infra/**, package.json dependency bumps
- Must implement: Decision Outcome “exponential backoff with jitter”
- Must NOT: switch to linear backoff; add new HTTP client
- DoD: Confirmation section checklist all green

Skill에 동일 블록을 복사해 문서↔에이전트 지시가 한 소스가 되게 합니다. 두 곳에 다른 문구가 있으면 에이전트는 넓은 쪽을 따릅니다.

범위 밖을 만나면 동작 규칙:

On out-of-scope discovery:
1. STOP editing.
2. Quote the ADR section that lacks guidance (or conflicts).
3. Propose at most one follow-up ADR title — do not implement it.
4. Leave the tree only with in-boundary changes (or restore).

하지 말 것: “일단 전체 리팩터 후 ADR에 맞추기”. 순서는 ADR 확정 → 경계 안 구현 → Confirmation.

검증 단계는?

한 줄 답: MADR Confirmation을 재현 가능한 명령·체크리스트로 바꾸고, 에이전트 Done 훅에서 같은 명령이 exit 0일 때만 완료로 인정합니다. 채팅의 “확인했습니다”는 검증이 아닙니다.

Confirmation을 에이전트 게이트로 쪼개는 예:

정적/아키 규칙 — 예: 레이어 import 금지, 허용 모듈만 참조(팀 규칙·ArchUnit류·커스텀 lint).
단위/계약 테스트 — Decision Outcome의 동작을 이름으로 고정한 테스트가 통과.
경계 diff 검사 — git diff --name-only가 allow path 밖이면 실패.
옵션 회귀 금지 — 버린 옵션의 심볼/설정이 다시 들어오면 실패(간단 grep 또는 테스트).
사람 리뷰 포인트 — Consequences의 Bad 항목이 코드/운영 runbook에 반영됐는지 체크리스트.

Done 게이트 골격:

Gate (all must exit 0 before done):
  ./scripts/adr-confirm.sh ADR-00NN
  # internally:
  #  - path allowlist vs git diff
  #  - tests named/marked for this ADR
  #  - optional architecture rule pack
Report: failing step name + ADR Confirmation quote.

adr-confirm.sh는 ADR 파일에서 Confirmation 체크리스트를 파싱해도 되고, 팀이 유지하는 adr/NNN-confirm.yaml을 읽어도 됩니다. 중요한 것은 문서의 Confirmation ↔ 스크립트가 같은 항목을 가리키는 것입니다.

상태 전환 규칙:

ADR status	에이전트 구현	비고
`proposed`	위임하지 않음	사람 결정 전
`accepted`	경계 안 구현 + Confirmation	기본
`deprecated` / `superseded by …`	구현·확장 금지	후속 ADR만
구현 중 발견: 결정 불충분	STOP + 질문	추측으로 채우지 않음

한 줄 정리: 에이전트 ADR 구현 = MADR 필수 섹션을 채운 accepted ADR · Implementation Boundary로 코드 범위 고정 · Confirmation을 스크립트 게이트로 실행. 채팅 지시만으로는 대체하지 않습니다.

FAQ

Nygard ADR(Context/Decision/Consequences)만으로도 되나?

됩니다. 다만 에이전트 위임 시에는 Options를 한 줄이라도 적고, Confirmation(또는 동등한 테스트 목록) 을 반드시 붙입니다. 최소 3절만 있으면 에이전트가 옵션을 다시 고르기 쉽습니다.

ADR 여러 장을 한 번에 줘도 되나?

한 턴·한 PR에는 의존이 명확한 소수(보통 1) 만 권장합니다. 여러 장이면 적용 순서와 충돌 시 우선 ADR을 프리앰블에 적습니다. 순서가 없으면 에이전트가 편의대로 섞습니다.

코드가 ADR보다 먼저 있으면?

먼저 as-is를 반영해 ADR을 accepted로 올리거나, 불일치면 STOP합니다. “코드에 맞춰 ADR을 에이전트가 다시 쓰게” 하면 결정 기록이 붕괴합니다.

Confirmation에 사람 리뷰만 있으면?

게이트는 기계 가능한 항목을 먼저 통과시키고, 사람 리뷰는 잔여 체크리스트로 둡니다. 전부 주관이면 에이전트 Done을 자동화할 수 없습니다.

출처 (Sources)

MADR — Markdown Architectural Decision Records — full template: Context, Drivers, Options, Decision Outcome, Consequences, Confirmation
MADR template (GitHub) — bare/minimal/full 템플릿
Michael Nygard, “Documenting Architecture Decisions” — Context / Decision / Consequences 최소 골격(관행적 인용)
팀 관행: Implementation Boundary + adr-confirm.sh를 Done 훅에 연결 — 본문 표