메뉴
기술 의사결정 기록 (Architecture Decision Record). 중요한 기술적 결정의 맥락, 대안, 근거를 구조화하여 기록합니다.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | adr |
| description | 기술 의사결정 기록 (Architecture Decision Record). 중요한 기술적 결정의 맥락, 대안, 근거를 구조화하여 기록합니다. |
| when_to_use | 이 결정 기록해둬, 왜 이렇게 했는지 남겨줘, 의사결정 기록. 결정 전 대안 비교는 rfc. |
| allowed-tools | Read, Write, Glob, Grep, Bash |
외부-가시 문서:
rules/external-doc.md10원칙 준수. ADR은 신규 입사자, 감사, 파트너 참조 전제. 내부 경로 금지, What > How, 정량과 절대 표기, 추측/확정 구분(근거 출처 명시).
"왜 이렇게 결정했는지"를 미래의 팀원(또는 미래의 나)이 이해할 수 있도록 기술 의사결정을 구조화하여 기록한다.
톤: 간결하고 객관적. 근거 명확, 감정과 정치 배제.
| 질문 | 담당 | 이 스킬에서 |
|---|---|---|
| 결정 전 복수안 비교와 협의 (제안/협의) | /rfc | [FAIL] 다루지 않음 |
| 아이디어 발산 (비교와 결정 없음) | /brainstorm | [FAIL] 다루지 않음 |
| 이미 내려진 기술 결정의 맥락, 대안, 근거 기록 | 이 스킬 | [OK] 핵심 |
| 데이터 | 경로 | 필수/선택 | 부재 시 동작 |
|---|---|---|---|
| 프로젝트 컨텍스트 | CLAUDE.md | 선택 | 일반 가정으로 진행, [프로젝트 규칙 미확인] 태그 |
| 봇 인덱스 | bot/INDEX.md 또는 .local.claude/ONBOARDING.md | 선택 | 디렉터리 Glob 으로 fallback |
| 비즈니스 규칙 | .local.claude/biz-rules.md | 선택 | 일반 SW 관점으로만 진행 (Tier 1) |
| 모듈 상세 | .local.claude/modules/{name}.md | 선택 | 코드 Grep 직접 fallback |
| 이전 ADR | docs/adr/ 또는 .local.claude/adr/ | 선택 | ADR 번호 새로 시작 (ADR-0001) |
| RFC/브레인스토밍 | .local.claude/rfc/, .local.claude/brainstorm/ | 선택 | 결정 배경 자동 수집 불가, 사용자에게 질문 |
$ARGUMENTS로 결정 제목이나 맥락을 받는다.
| 입력 예 | 동작 |
|---|---|
/adr 드라이브 파일 저장소를 NCloud로 전환 | 해당 결정에 대한 ADR 작성 |
/adr (인자 없음) | 최근 ADR 목록을 보여주고 새로 작성할지 질문 |
/adr list | 기존 ADR 목록 표시 |
[1M 활용] 다음을 단일 메시지에서 병렬 호출:
- Bash:
ls .local.claude/adr/(기존 ADR 번호 충돌 방지)- Read: 기존 ADR
.local.claude/adr/*.md,CLAUDE.md,.local.claude/biz-rules.md, 관련.local.claude/modules/{name}.md- Grep: 결정과 관련된 코드/설정 키워드 (
*.java,*.yml)- Read: 관련
.local.claude/rfc/*.md,.local.claude/brainstorm/*.md(배경)
인자만으로 충분하지 않으면 아래를 질문:
결정과 관련된 코드가 있으면 확인:
# 관련 모듈/설정 확인
grep -r "관련키워드" --include="*.java" --include="*.yml" -l
ls .local.claude/adr/ 2>/dev/null
번호 충돌 방지 및 관련 ADR 연결을 위해 기존 목록 확인.
.local.claude/biz-rules.md: 비즈니스 규칙에 영향 주는 결정인지.local.claude/modules/{name}.md: 영향받는 모듈CLAUDE.md: 기존 컨벤션과 충돌 여부| 상태 | 설명 |
|---|---|
| 제안 | 아직 논의 중. 피드백 필요 |
| 승인 | 결정 확정. 실행 단계 |
| 대체됨 | 이후 다른 ADR로 대체됨 (대체 ADR 번호 링크) |
| 폐기 | 결정이 철회됨 |
# ADR-{번호}: {결정 제목}
| 항목 | 내용 |
|------|------|
| 상태 | 제안 / 승인 / 대체됨 / 폐기 |
| 날짜 | YYYY-MM-DD |
| 결정자 | (논의 참여자) |
| 영향 범위 | 모듈, 고객사, 인프라 등 |
## 상황 (Context)
왜 이 결정이 필요한가? 어떤 문제나 변화가 이 결정을 촉발했는가?
- 배경 설명
- 현재 상태의 문제점
- 제약 조건 (일정, 비용, 기술, 인력, 고객 요구 등)
## 대안 (Options)
### 대안 A: {이름}
- 설명
- 장점
- 단점
- 예상 비용/기간
### 대안 B: {이름}
- 설명
- 장점
- 단점
- 예상 비용/기간
### 대안 C: {이름} (고려했으나 제외)
- 설명
- 제외 사유
## 결정 (Decision)
**{선택한 대안}을 채택한다.**
선택 근거:
- 근거 1
- 근거 2
- 근거 3
## 결과 (Consequences)
### 긍정적
- ...
### 부정적/리스크
- ...
- 완화 방안: ...
### 후속 작업
- [ ] ...
- [ ] ...
## 관련 ADR
- ADR-{번호}: {제목} ({관계 설명})
[메타인지] 출력 전 자기 검증:
- 근거 재점검: 각 대안의 장/단점, 비용, 기간에 근거(측정, 벤치마크, 모듈 문서)가 있는가?
- 전제 검증: 결정이 유효하려면 어떤 전제(제약 조건, 트래픽 규모, 팀 역량)가 성립해야 하는가? 전제 변경 시 재고해야 할 ADR인가?
- 반대 증거: "미래의 신규 입사자가 이 ADR만 보고 '왜 이 결정?'에 답할 수 있는가?" 자기 완결성 반박 1개 이상
Frontmatter (CONTRACT 7-2절 표준): category: adr, retention: permanent, harvest_targets: [biz-rules.md]
ls .local.claude/adr/ 2>/dev/null | sort -t'-' -k1 -n | tail -1
기존 ADR의 마지막 번호 + 1. 없으면 0001부터 시작.
.local.claude/adr/{번호}-{kebab-case-제목}.mdmkdir -p로 생성.local.claude/adr/0001-ncloud-migration.md.local.claude/adr/0002-elasticsearch-index-strategy.mdADR 작성 완료 후 안내:
/todo (작업 분해)/draft (공유용 초안)/biz-rules (규칙 업데이트)rules/external-doc.md (가독성 5 + 정직성 5). ADR은 팀 외부(신규 입사자, 감사, 파트너)에도 참조될 수 있음./todo에서.공통 3블록(빈 / 부분 / 풀 데이터)은 CONTRACT 6-1절 참조.
[데이터 결함] 기존 ADR 번호가 겹침
.local.claude/adr/ADR-NNN-*.md 에서 부여하려는 번호가 이미 존재[사용자 개입 필요] 대안과 근거가 부재
/brainstorm 으로 대안 발산, /rfc 로 비교 권장 후 중단지정 디렉터리의 문서를 심층 분석하여 지식을 추출하고, 기존 문서 갱신 + 신규 문서 생성으로 프로젝트 지식 베이스에 반영합니다.
현재 디렉터리의 내용을 분석하여 어떤 목적의 폴더인지 파악
슬랙/메일/메신저로 받은 업무 요청 메시지를 분석하여 의도, 핵심 내용, 판단, 액션 플랜, 대응 가이드를 정리합니다.
비즈니스 규칙, 도메인 규칙, 상태 전이 규칙을 하나의 문서로 관리합니다. 변경 이력이 누적됩니다.
열린 질문, 문제 해결, 기술 의사결정, 아이디어 발산을 구조화합니다. 회의록이나 메모 파일 경로를 인자로 전달하거나 직접 질문하세요.
아침 브리핑. 최근 커밋을 분석하여 오늘 개발 시작 전에 알아야 할 변경 사항, 영향 범위, 주의 사항을 요약합니다.