architecture-decision-records

아키텍처 의사결정 기록

코딩 세션 중 발생하는 아키텍처 결정을 바로 기록합니다. 결정이 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. 초기화(최초 1회만) — docs/adr/가 없으면, 디렉터리와 인덱스 표 헤더가 들어간 README.md, 수동 작성용 빈 template.md를 만들기 전에 사용자 확인을 받습니다. 명시적 동의 없이 파일을 만들지 않습니다.
2. 의사결정 식별 — 지금 내려지는 핵심 아키텍처 선택을 추출합니다.
3. 맥락 수집 — 어떤 문제가 이 결정을 만들었는지, 어떤 제약이 있는지 정리합니다.
4. 대안 기록 — 어떤 옵션을 검토했고 왜 기각했는지 적습니다.
5. 결과 정리 — 어떤 트레이드오프가 있고 무엇이 쉬워지거나 어려워지는지 적습니다.
6. 번호 부여 — docs/adr/의 기존 ADR을 스캔해 다음 번호를 정합니다.
7. 확인 후 작성 — 초안 ADR을 사용자에게 보여주고 검토를 받습니다. 명시적 승인 후에만 docs/adr/NNNN-decision-title.md에 기록합니다. 사용자가 거절하면 파일을 쓰지 않고 폐기합니다.
8. 인덱스 갱신 — docs/adr/README.md에 추가합니다.

기존 ADR 읽기

사용자가 "why did we choose X?"라고 물으면 다음 순서로 처리합니다.

1. docs/adr/가 있는지 확인합니다. 없으면 "No ADRs found in this project. Would you like to start recording architectural decisions?"라고 답합니다.
2. 존재하면 docs/adr/README.md 인덱스에서 관련 항목을 찾습니다.
3. 일치하는 ADR 파일을 읽고 Context, Decision 섹션을 제시합니다.
4. 일치 항목이 없으면 "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을 표시합니다