| name | architecture-decision-records |
| description | Claude Code 세션 중 내려진 아키텍처 결정을 구조화된 ADR로 기록합니다. 의사결정 시점을 감지하고, 맥락, 검토한 대안, 근거를 남깁니다. 미래 개발자가 왜 코드베이스가 현재 형태가 되었는지 이해할 수 있도록 ADR 로그를 유지합니다. |
| origin | ECC |
아키텍처 의사결정 기록
코딩 세션 중 발생하는 아키텍처 결정을 바로 기록합니다. 결정이 Slack 스레드, PR 댓글, 개인 기억 속에만 남지 않도록, 이 스킬은 코드와 함께 보관되는 구조화된 ADR 문서를 만듭니다.
사용 시점
- 사용자가
"let's record this decision" 또는 "ADR this"라고 명시할 때
- 사용자가 중요한 대안들 사이에서 선택할 때(프레임워크, 라이브러리, 패턴, 데이터베이스, API 설계)
- 사용자가
"we decided to..." 또는 "the reason we're doing X instead of Y is..."라고 말할 때
- 사용자가
"why did we choose X?"라고 물을 때(기존 ADR 조회)
- 계획 단계에서 아키텍처 트레이드오프를 논의할 때
ADR 형식
Michael Nygard의 경량 ADR 형식을 AI 보조 개발에 맞게 적용해 사용합니다.
# ADR-NNNN: [Decision Title]
**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]
## Context
What is the issue that we're seeing that is motivating this decision or change?
[2-5 sentences describing the situation, constraints, and forces at play]
## Decision
What is the change that we're proposing and/or doing?
[1-3 sentences stating the decision clearly]
## Alternatives Considered
### Alternative 1: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]
### Alternative 2: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]
## Consequences
What becomes easier or more difficult to do because of this change?
### Positive
- [benefit 1]
- [benefit 2]
### Negative
- [trade-off 1]
- [trade-off 2]
### Risks
- [risk and mitigation]
워크플로
새 ADR 작성
의사결정 시점을 감지하면 다음 순서로 진행합니다.
- 초기화(최초 1회만) —
docs/adr/가 없으면, 디렉터리와 인덱스 표 헤더가 들어간 README.md, 수동 작성용 빈 template.md를 만들기 전에 사용자 확인을 받습니다. 명시적 동의 없이 파일을 만들지 않습니다.
- 의사결정 식별 — 지금 내려지는 핵심 아키텍처 선택을 추출합니다.
- 맥락 수집 — 어떤 문제가 이 결정을 만들었는지, 어떤 제약이 있는지 정리합니다.
- 대안 기록 — 어떤 옵션을 검토했고 왜 기각했는지 적습니다.
- 결과 정리 — 어떤 트레이드오프가 있고 무엇이 쉬워지거나 어려워지는지 적습니다.
- 번호 부여 —
docs/adr/의 기존 ADR을 스캔해 다음 번호를 정합니다.
- 확인 후 작성 — 초안 ADR을 사용자에게 보여주고 검토를 받습니다. 명시적 승인 후에만
docs/adr/NNNN-decision-title.md에 기록합니다. 사용자가 거절하면 파일을 쓰지 않고 폐기합니다.
- 인덱스 갱신 —
docs/adr/README.md에 추가합니다.
기존 ADR 읽기
사용자가 "why did we choose X?"라고 물으면 다음 순서로 처리합니다.
docs/adr/가 있는지 확인합니다. 없으면 "No ADRs found in this project. Would you like to start recording architectural decisions?"라고 답합니다.- 존재하면
docs/adr/README.md 인덱스에서 관련 항목을 찾습니다.
- 일치하는 ADR 파일을 읽고
Context, Decision 섹션을 제시합니다.
- 일치 항목이 없으면
"No ADR found for that decision. Would you like to record one now?"라고 답합니다.
ADR 디렉터리 구조
docs/
└── adr/
├── README.md ← index of all ADRs
├── 0001-use-nextjs.md
├── 0002-postgres-over-mongo.md
├── 0003-rest-over-graphql.md
└── template.md ← blank template for manual use
ADR 인덱스 형식
# Architecture Decision Records
| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 |
의사결정 감지 신호
대화에서 다음 패턴이 보이면 아키텍처 결정으로 판단합니다.
명시적 신호
- "Let's go with X"
- "We should use X instead of Y"
- "The trade-off is worth it because..."
- "Record this as an ADR"
암묵적 신호(ADR 기록을 제안하되 사용자 확인 없이 자동 생성하지 않음)
- 두 프레임워크나 라이브러리를 비교한 뒤 결론에 도달함
- 근거를 동반한 데이터베이스 스키마 설계 선택을 함
- 아키텍처 패턴 사이에서 선택함(모놀리식 vs 마이크로서비스, REST vs GraphQL)
- 인증/인가 전략을 결정함
- 대안을 평가한 뒤 배포 인프라를 선택함
좋은 ADR의 조건
해야 할 것
- 구체적으로 작성 —
"ORM을 쓴다"가 아니라 "Prisma ORM을 사용한다"
- 왜를 기록 — 무엇보다 근거가 중요합니다
- 기각한 대안 포함 — 미래 개발자는 무엇을 검토했는지 알아야 합니다
- 결과를 솔직하게 작성 — 모든 결정에는 트레이드오프가 있습니다
- 짧게 유지 — ADR은 2분 안에 읽을 수 있어야 합니다
- 현재형 사용 —
"We will use X"가 아니라 "We use X"
피해야 할 것
- 사소한 결정을 기록하지 않기 — 변수명, 포매팅 선택은 ADR 대상이 아닙니다
- 장문 에세이처럼 쓰지 않기 —
Context가 10줄을 넘으면 너무 깁니다
- 대안을 생략하지 않기 —
"그냥 골랐다"는 유효한 근거가 아닙니다
- 사후 기록을 표시 없이 남기지 않기 — 과거 결정을 기록하는 경우 원래 날짜를 적습니다
- ADR을 방치하지 않기 — 대체된 결정은 새 ADR을 참조해야 합니다
ADR 생명주기
proposed → accepted → [deprecated | superseded by ADR-NNNN]
- proposed: 논의 중이지만 아직 확정되지 않음
- accepted: 현재 효력이 있으며 따르고 있음
- deprecated: 더 이상 관련이 없음(예: 기능 제거)
- superseded: 더 새로운 ADR이 이 결정을 대체함. 항상 대체 ADR을 링크합니다.
기록할 가치가 있는 결정 범주
| Category | Examples |
|---|
| 기술 선택 | 프레임워크, 언어, 데이터베이스, 클라우드 공급자 |
| 아키텍처 패턴 | 모놀리식 vs 마이크로서비스, 이벤트 기반, CQRS |
| API 설계 | REST vs GraphQL, 버전 전략, 인증 방식 |
| 데이터 모델링 | 스키마 설계, 정규화 결정, 캐싱 전략 |
| 인프라 | 배포 모델, CI/CD 파이프라인, 모니터링 스택 |
| 보안 | 인증 전략, 암호화 방식, 시크릿 관리 |
| 테스트 | 테스트 프레임워크, 커버리지 목표, E2E와 통합 테스트의 균형 |
| 프로세스 | 브랜치 전략, 리뷰 프로세스, 릴리스 주기 |
다른 스킬과의 연계
- Planner agent: 아키텍처 변경을 제안할 때 ADR 작성을 함께 제안합니다
- Code reviewer agent: 해당 ADR 없이 아키텍처 변경을 넣은 PR을 표시합니다
