결정 기록 (Recording Decisions)
개요
결정은 영속적인 인프라입니다. 메모리와 채팅 기록은 그렇지 않습니다. 한 번의 기록 비용은 한 번만 지불되지만, 잃어버린 결정의 비용은 누군가가 코드에서 의도를 역추적해야 할 때마다 지불됩니다.
기록 구조
모든 중요한 결정은 고정된 구조의 기록을 생성하므로, 모든 독자가 어디를 봐야 할지 알 수 있습니다:
| 섹션 | 내용 |
|---|---|
| 아키텍처 | 솔루션의 형태와 주요 파일 |
| 데이터 모델 | 엔티티, 필드, 관계 |
| 결정 (WHY 포함) | 각 선택과 그 근거 쌍 — 이유는 필수 |
| 인터페이스 | 다른 코드가 이 코드를 사용하는 방법 |
| 제약 조건 | 반드시 유지되어야 하는 사항 |
| 주의 사항 | 다음 사람을 위한 비자명한 함정 |
| 기각된 대안 | 고려했지만 버린 선택과 그 이유 — 이미 해결된 질문을 다시 논의하는 것을 방지 |
세 가지 보완 산출물
- 모든 결정의 인덱스 — 명시적인 종속성 추적(어떤 결정이 어떤 결정 위에 구축되는지)과 대체됨(superseded) 섹션을 포함합니다. 기록 더미를 탐색 가능한 그래프로 바꿉니다.
- '미래 고려 사항(Future Considerations)' 문서 — 연기된 아이디어와 알려진 우려 사항을 기록하며, 새 작업을 시작할 때 참조하여 아무것도 조용히 잊히지 않도록 합니다. 인시던트 액션 항목과 트리거가 있는 연기된 결정이 여기에 기록됩니다.
- 아카이브 — 대체된 기록은 삭제되지 않고 여기로 이동합니다. 역사는 보존되며 덮어쓰이지 않습니다.
빠른 참조
- 기록 위치 규칙:
docs/superpowers/decisions/YYYY-MM-DD-<주제>.md(YAML 프론트매터 포함:title,date,component,status,supersedes,dependencies). - 미래 고려 사항은
docs/superpowers/future-considerations.md에 위치합니다. 각 항목은 상태(open/triggered/done/dropped)와 해당되는 경우 트리거(재활성화 조건)를 포함합니다. 새 작업을 시작할 때 참조하십시오. - 프론트매터는 자동 생성된 인덱스를 지원합니다. 정확성을 유지하십시오.
- *이유(why)*와 *기각된 대안(rejected alternatives)*은 가장 가치 있는 두 섹션입니다. 이 섹션이 없는 기록은 지뢰와 같습니다.
- 파이프라인의 기록(Record) 단계에서 기록을 작성하십시오(
designing-before-building참조, Execute 단계 이후).
번들 도구
이 스킬은 자체 스크립트와 템플릿을 제공하므로, 스킬이 설치된 모든 저장소에서 작동합니다. 이 파일들은 SKILL.md 옆에 위치합니다:
recording-decisions/
scripts/doc-archive.sh 결정 기록이 없는 스펙/계획을 찾음
scripts/index-rebuild.sh 기록 프론트매터에서 인덱스 재생성
templates/decision-record.md
파일을 찾으려면 다음 명령어를 사용하세요 (스킬은 프로젝트별 또는 전역으로 설치될 수 있음):
for base in .claude/skills ~/.claude/skills; do
d="$base/recording-decisions/scripts"
[ -d "$d" ] && echo "$d" && break
done
doc-archive.sh [specs_dir] [plans_dir] [decisions_dir] [archive_dir]
일치하는 결정 기록이 없는 스펙을 나열하고 템플릿에서 생성된 변환 프롬프트를 출력합니다. 기본값은 docs/superpowers/{specs,plans,decisions,archive}입니다.
index-rebuild.sh [decisions_dir] [output_file]
모든 기록의 프론트매터에서 docs/superpowers/index.md를 다시 작성합니다 — 활성 테이블(component, title, date, dependencies)과 대체됨 테이블(component, title, superseded by)을 생성합니다. 전체를 재생성하므로 직접 편집하지 마십시오.
두 스크립트 모두 종속성이 없는 Bash입니다. 이 스킬을 사용하는 프로젝트에 yq, jq 또는 태스트 러너가 필요하지 않습니다. 스크립트가 없는 경우 위 절차는 독립적으로 수행 가능하므로 직접 작업하십시오.
이것이 컨텍스트에 중요한 이유
스펙과 계획은 의도적으로 장황합니다. 인간이 추론 과정을 따라갈 수 있도록 작성되기 때문입니다. 그 장황함은 Claude가 스펙을 열 때마다 컨텍스트에 비용으로 부과됩니다. 결정 기록은 앞으로 나아가는 데 필요한 것 — 결정, 이유, 인터페이스, 제약 조건, 주의 사항, 기각된 대안 — 을 약 30~50줄로 유지하는 반면, 원본 스펙은 archive/로 이동하여 인간이 읽을 수 있게 유지되며 의도적으로 열기 전까지 비용이 들지 않습니다.
사용하지 말아야 할 때
사소하고 자명한 변경에는 기록이 필요하지 않습니다. 판단 기준: 나중에 누군가 "왜 이렇게 했지?"라고 물을까? 그렇다면 기록하십시오.
전체 근거: 헌법 제2조, engineering-constitution/references/engineering-constitution.md에 번들로 제공됩니다.