/decide

당신은 ai-docs/decisions/ 디렉토리 아래 단일 ADR(Architectural Decision Record)의 작성자입니다. 결정 레지스트리는 이전 추론을 회상 가능하게 만드는 기반입니다. 미래 작업을 제한하거나, 대안을 명시적으로 배제하거나, 만료일을 설정하는 모든 의미 있는 선택이 기록되어 미래의 엔지니어와 AI 에이전트가 이를 추적할 수 있습니다.

이 스킬에서는 프로덕션 코드를 편집하지 않습니다. 작성하는 유일한 산출물은 신규 또는 수정된 ADR 파일입니다. canonical-patterns.md / architectural-smells.md에 대한 백레퍼런스 제안은 요약에서 권장될 뿐, 직접 실행하지 않습니다(명시적 편집 작업은 사람의 검토 후에 수행됩니다).

성공 판단 기준

신규/수정된 ADR이 Stage 3 검증을 통과함: .venv/bin/python scripts/decisions.py audit 및 link-check가 깨끗하게 통과하며, 실제 출력이 보고됩니다.
Stage 1에서 주제를 이미 다루는 기존 결정이 없음을 확인함. 중복은 --amend 또는 대체(supersession)로 중단되며, 동일한 선택에 대해 두 번째 ADR을 생성하지 않습니다.
related_smell / related_pattern 백레퍼런스가 적용되는 경우 설정되며, 요약에서 일치하는 Decided in: NNNN 라인을 권장합니다(직접 실행하지 않고 권장).
ai-docs/decisions/ 외부에는 아무것도 작성되지 않았습니다. 이러한 게이트를 향해 Stage 0부터 작성하십시오.

핵심 신념

결정의 기준은 현실적입니다. (a) 미래 스킬이나 리팩토링을 제한하거나, (b) 대안을 명시적으로 배제하거나, (c) 만료일을 설정하는 모든 선택이 후보입니다. 놀라움, 디버깅 노트, 프로젝트 상태는 결정이 아닙니다 — 이러한 내용은 .claude/tasks/lessons.md, 커밋 메시지, 또는 작업 목록에 기록됩니다.
선택당 하나의 ADR. 작업이 두 개의 연결된 선택에 걸쳐 있는 경우 두 개의 ADR을 작성하십시오. 두 개의 독립적인 포크를 문서화하는 단일 ADR은 대체하기 어렵고, 연결하기 어렵고, 묘지 항목이 됩니다.
백레퍼런스는 레지스트리를 탐색 가능하게 만듭니다. 모든 ADR은 적용되는 경우 related_smell 및/또는 related_pattern 프론트매터를 설정해야 하며, 요약은 일치하는 canonical-patterns.md / architectural-smells.md 항목에 Decided in: NNNN 백레퍼런스를 추가할 것을 권장합니다. 백레퍼런스가 없으면 레지스트리는 쓰기 전용입니다.
삭제보다는 대체. 대체된 결정은 status: superseded 및 superseded_by: NNNN과 함께 레지스트리에 남아 있습니다. ADR을 절대 삭제하지 마십시오 — 체인이 감사 추적입니다.
목표 주기: 분기당 2-5개. 단일 프로젝트에서 그 이상은 과도한 기록을 의미합니다 — 원장이 잡동사니 서랍이 됩니다. 일주일 안에 세 번째 ADR을 초안 작성하고 있다면, 후자의 것들이 실제 결정인지 아니면 단순한 선호인지 멈추고 질문하십시오.
소급 작성된 ADR도 유효합니다. 미래 작업을 제한하는 오랜 관행은 레지스트리보다 먼저 존재하더라도 ADR을 받을 자격이 있습니다. 본문에 > 소급 작성된 ADR.이라고 표시하십시오.

인수 구문 분석

네 가지 형식 중 정확히 하나를 선택하십시오.

형식 A — 새 ADR (기본값)

/decide <slug>

<slug>는 짧은 케밥-케이스 주제 식별자입니다(예: textchoices-for-state, spec-first-refactor, celery-safe-dispatch). 오케스트레이터는 사용 가능한 다음 4자리 id(사용되지 않은 가장 낮은 정수, 0으로 채움)를 선택하고, 슬러그에서 제목을 추출하며, proposed 상태의 ADR을 스캐폴드합니다.

형식 B — 기존 ADR 대체

/decide --supersede <existing-id> --slug <new-slug>

supersedes: [<existing-id>]와 함께 새 ADR(다음 id, 상태 proposed)을 작성합니다. 또한 대체된 ADR의 프론트매터(status: superseded, superseded_by: <new-id>)를 편집하기 위한 스테이지를 수행하지만 커밋하지는 않습니다 — 새 ADR은 먼저 사람의 승인을 받아야 합니다.

형식 C — 기존 ADR 수정

/decide --amend <id>

status, superseded_by, applies_to, tags, related_smell, related_pattern 중 하나를 편집합니다. 본문 편집은 범위 밖입니다(이러한 경우 직접 파일을 여십시오 — ADR의 결정을 수정하는 것은 그 자체로 결정이므로, 일반적으로 대체(supersession)여야 합니다).

형식 D — 목록

/decide --list

.venv/bin/python scripts/decisions.py list의 약어입니다. 새 파일이 작성되지 않습니다.

구문 분석된 사양을 사용자에게 제시하고(의도 + 대상 id + canonical-patterns.md / architectural-smells.md에서 표면화된 related_smell/related_pattern 후보) 형식 A와 B에서는 쓰기 전에 승인을 기다립니다. 형식 C / D는 즉시 실행됩니다.

승인 토큰 계약은 /extract-enum 및 /fix-workflow와 일치합니다: 첫 번째 공백이 아닌 토큰은 approved, approve, go, lgtm, proceed 또는 yes여야 합니다.

파이프라인

Stage 0 — 설정

전제: 인수 구문 분석됨. 후제: 다음 id 확인됨(형식 A, B); 대상 파일 경로 확인됨(형식 C); ${REPO_ROOT}/ai-docs/decisions/가 존재함.

# 다음 id 찾기 (형식 A, B)
NEXT_ID=$(.venv/bin/python -c "
import pathlib, re
ids = []
for p in pathlib.Path('ai-docs/decisions').glob('[0-9][0-9][0-9][0-9]-*.md'):
    m = re.match(r'(\d{4})-', p.name)
    if m: ids.append(int(m.group(1)))
print(f'{(max(ids)+1) if ids else 1:04d}')
")
NEW_PATH="ai-docs/decisions/${NEXT_ID}-${SLUG}.md"

슬러그가 다른 id에 이미 존재하는 경우 중단하고 기존 ADR에 --amend할 것을 권장합니다.

Stage 1 — 컨텍스트 수집

전제: 대상 id 알려짐. 후제: 관련 패턴 및 관련 냄새 후보 식별됨.

다음 파일을 읽습니다(작고 빠르며 주제에 한정됨):

ai-docs/decisions/README.md — 레지스트리 규칙
.claude/docs/canonical-patterns.md — 결정 주제와 일치하는 패턴 이름 검색(슬러그 단어에 대한 대소문자 구분 없는 grep)
.claude/docs/architectural-smells.md — 냄새 이름에 대한 동일한 검색
.venv/bin/python scripts/decisions.py list --json — 전체 레지스트리(이미 결정된 질문을 실수로 다시 결정하지 않도록)

형식 B(대체)의 경우, 대체된 ADR의 본문도 읽어 새 ADR이 무엇이 변경되었는지 명명할 수 있도록 합니다. 대체된 결정의 결정 문장을 직접 인용한 다음 차이점을 설명합니다.

Stage 2 — ADR 초안 작성

전제: 컨텍스트 수집됨. 후제: ${NEW_PATH} 작성됨(형식 A, B) 또는 --amend 필드 업데이트됨(형식 C).

레지스트리 스크립트로 형식 A/B를 스캐폴드한 다음 생성된 파일을 편집합니다. 스캐폴드는 프론트매터 형태에 대한 실행 가능한 진실 공급원입니다:

.venv/bin/python scripts/decisions.py init "${SLUG}"

scripts/decisions.py init에 의해 생성되는 ADR 형태 — 값이 비어 있더라도 다음 프론트매터 필드를 유지하십시오:

---
id: "<NNNN>"
nmespace: core
title: "<대문자로 시작하는 제목 문장 — 가능하면 동사로 시작>"
status: proposed              # proposed | accepted | superseded | deprecated
date: <YYYY-MM-DD 오늘>
deciders: []                  # 불확실하면 채우기 전에 질문
supersedes: []                # 형식 B에서만 채움
superseded_by: null
applies_to: []
embodied_by: []               # 수락되면 필요; ADR 0033 참조
tags: []
related_smell: <냄새-앵커 또는 null>      # architectural-smells.md에서
related_pattern: <패턴-앵커 또는 null>    # canonical-patterns.md에서
---

# <제목>

<선택적 소급 작성 부인>

## 컨텍스트

<이전 상태, 반복되는 문제 및 이 결정의 트리거를 설명하는 2-4개 단락. 구체적으로 작성하십시오 — 실제 파일, 실제 사고, 실제 실패 모드를 인용하십시오. 모호한 컨텍스트 = 나중에 대체 불가능.>

## 결정

<규칙을 설명하는 하나의 짧은 단락, 여러 하위 규칙이 있는 경우 글머리 기호. 결정 섹션은 단일 하중 지지 문장입니다; 다른 모든 것은 이를 지원하기 위해 존재합니다.>

## 고려된 대안

- **<대안 1 이름>.** <한 줄 설명>. 기각: <이유>.
- **<대안 2 이름>.** <한 줄 설명>. 기각: <이유>.
- (최소 두 개의 대안; "결정 없음"은 일반적으로 하나로 간주됩니다.)

## 결과

**더 쉬워짐:**
- <지속 가능한 개선>

**더 어려워짐:**
- <결정이 수용하는 트레이드오프>

**이제 예상됨 / 이제 허용되지 않음:**
- <린터, 검토자 또는 미래 에이전트가 시행할 새로운 제약>

## 검증

- **도구**: <린트 규칙 / 테스트 / 감사 명령, 파일 경로 포함>
- **문서 백레퍼런스**: <어떤 canonical-patterns.md / architectural-smells.md 항목이 `Decided in: <NNNN>`을 포함할지>
- **기존 아티팩트**: <이미 준수하는 사양 / 커밋 / PR에 대한 포인터>

스캐폴딩 후, 제목/본문 및 알려진 deciders, applies_to, tags, related_smell, related_pattern 값을 채웁니다. 형식 B의 경우 새 ADR에서 supersedes: [<existing-id>]를 편집합니다.

형식 C(수정)의 경우, Edit 도구를 통해 요청된 프론트매터 필드만 편집합니다. 본문은 건드리지 않습니다. 수정이 superseded_by 없이 status: superseded를 설정하는 경우 중단하고 대체하는 id를 요청합니다.

Stage 3 — 검증

전제: ADR 작성됨. 후제: decisions.py audit 및 link-check가 exit 0.

.venv/bin/python scripts/decisions.py audit && \
  .venv/bin/python scripts/decisions.py link-check

둘 중 하나라도 실패하면 진단을 표면화하고 중단하십시오 — ADR은 디스크에 있지만 등록되지 않았습니다. 일반적인 실패:

proposed > 30 days — 오래된 ADR에만 관련됨(새로 작성된 ADR에서는 발생하지 않음)
broken supersedes — 형식 B의 대체된 ADR 편집이 적용되지 않음
applies_to path missing — applies_to 글로브 수정

Stage 4 — 효과성 로그

전제: 검증 통과. 후제: reports/_meta/effectiveness.jsonl에 한 줄 추가.

.venv/bin/python scripts/log_effectiveness.py \
  --skill decide \
  --scan-id "decision-${NEXT_ID}" \
  --target "${NEW_PATH}" \
  --findings-total 1 \
  --buckets "{\"new_decision\": 1}"

형식 C(수정)의 경우 버킷은 {"amended_decision": 1}이고 findings-total은 1로 유지됩니다.

Stage 5 — 요약

≤8줄로 사용자에게 보고:

새 (또는 수정된) ADR의 경로.
ID 및 제목.
Stage 1에서 표면화된 관련 패턴 및 관련 냄새 백레퍼런스 후보, 각 항목이 추가해야 할 정확한 줄: Decided in: ${NEXT_ID} 해당 패턴/냄새 아래.
제안된 다음 명령:
- 형식 A/B: 사람 검토 → 승인되면 /decide --amend ${NEXT_ID}를 통해 status: accepted 표시.
- 형식 C: 없음 — 수정이 작업입니다.

canonical-patterns.md / architectural-smells.md를 직접 편집하지 마십시오. 백레퍼런스 후보를 표면화하는 것이 작업입니다; 사람이 적용 여부를 결정합니다.

비목표

canonical-patterns.md 또는 architectural-smells.md 편집 (백레퍼런스 권장, 작성하지 않음 — 별도 검토).
린트 규칙 추가 (/prevent-regression의 역할; ADR은 검증 섹션에서 하나를 권장할 수 있음).
새 기능 / 리팩토링 구축 (ADR은 작업을 동기부여하며, 작업은 /plan-feature 또는 /refactor-subsystem이 수행).
교훈 또는 놀라움 기록 (이러한 내용은 .claude/tasks/lessons.md에 기록).
실제 교차 절단 선택의 상응하는 증가 없이 분기당 2-5개 ADR 초과 — 일시 중지하고 재평가.

문제 발생 시

증상	조치
슬러그가 다른 id에 이미 존재함	중단; `--amend <existing>` 권장
`--supersede` 대상이 존재하지 않음	중단; 올바른 id 요청 (`/decide --list`로 확인)
`--amend` 대상의 프론트매터 필드를 알 수 없음	중단; 지원되는 필드 나열 (status, superseded_by, applies_to, tags, related_smell, related_pattern)
`decisions.py audit`이 1로 종료됨	정확한 진단 표면화; 효과성을 기록하지 않음; 재시도 전에 레지스트리 수정 요청
`link-check`가 `Decided in: NNNN` 참조에서 깨진 링크를 찾음	보고하지만 깨진 참조를 편집하지 않음; 별도 정리 작업
형식 B가 이미 대체된 ADR을 대체하도록 요청됨	체인을 따라 리프로 이동하고 리프를 대체; 요약에서 체인 깊이 표시
Stage 1이 이 주제를 이미 다루는 기존 결정을 찾음	새 ADR 초안 중단; 사용자가 `/decide --amend <existing>`을 통해 `applies_to`를 확장하거나 대체를 통해 에스컬레이션할 것을 권장

저장소 레이아웃

.claude/skills/decide/
├── SKILL.md                  # 이 파일 — 오케스트레이터
└── knowledge/
    └── rules.md              # ADR 임계값 휴리스틱, 안티패턴

오케스트레이터(당신)는 knowledge/rules.md를 읽지 않습니다 — 해당 파일은 설계자 / 미래 유지 관리자를 위한 오프라인 참조로, 스킬이 방지하도록 설계된 임계값 규칙 및 일반적인 ADR 안티패턴을 설명합니다. 미래의 정찰 하위 에이전트(추가된 경우)가 이를 읽을 수 있습니다.

시니어 바이브 엔지니어