branch-spec 조립 파이프라인 — 설계 (Phase 1, 축소판)

작성: 2026-06-02 · 상태: 합의됨(축소판) · 후속: Phase 2(검증 강화), Phase 3(윤문)

1. 배경 / 문제

현재 자동화는 좋은 기반이지만 /branch(빈 스캐폴드)와 /depth(읽기 전용 깊이 게이트) 사이를 내용으로 채우는 단계가 없다. 결과적으로:

문서 작성 agent는 입력이 부족하면 NEEDS_CONTEXT로 멈춘다(.claude/agents/wiki-doc-author.md 의 ## Required Inputs). 안전하지만 "되묻지 않는 구조적 문서 작성"과는 다르다.
agent별 필수 입력이 산문으로 박혀 있어 재사용 가능한 입력 계약이 없다.

"되묻지 않으려면 controller가 dispatch 전에 입력 패키지를 완성"해야 한다. 그 controller 단계가 빠진 것이 핵심 갭이다.

2. 범위 (축소판)

순수 추가 — 신규 파일 2개. 기존 template·linter·문서는 건드리지 않는다.

산출물	성격
`rules/subagent-input-contracts.md`	dispatch 전 입력을 agent별 form schema로 고정
`.claude/commands/branch-spec.md`	조립 오케스트레이터 명령

명시적 비범위 (후속 phase로 연기):

G3 중첩 체크리스트 포맷 — 기존 Decision Evidence Map 표를 그대로 사용(template 개정·린터 변경·마이그레이션 없음).
G4 한국어 윤문 standard / "쉬운 설명" 기준 → Phase 3.
G5 린터 C1/C3 hook 추가, /lint --fix-plan → Phase 2.

3. 확정된 설계 결정

ID	결정	근거
DD1	근거 없는 결정은 자동조사 후 라벨링 — 먼저 webfetch 조사로 Claim 생성 시도, 실패 시에만 `UNSUPPORTED_DECISION` + trade-off. 추측해서 FACT 승격 절대 금지	"되묻지 않기" vs "근거 없는 결정 금지" 충돌 해소. CLAUDE.md §11 준수
DD2	명령 경계: `/branch` → `/branch-spec` → 끝에 `/depth` 자동 호출	세 명령이 각자 한 일(생성/채움/검증). 루프가 자동으로 닫힘
DD3	아키텍처: 오케스트레이터 명령(접근 1). 새 agent 0개, 기존 서브에이전트 재사용	"agent 늘리지 말고 controller 계약" 합의. 서브에이전트는 다른 서브에이전트를 못 부르지만 명령을 실행하는 메인 에이전트는 부를 수 있음
DD4	자동조사는 bounded — 회당 최대 N개 결정(기본 6), 초과분은 `deferred`로 명시 로그(silent 절단 금지)	조사 비용(토큰·시간) 폭주 방지
DD5	최종 보고는 짧은 사람용 요약(채운 것/UNSUPPORTED/조사/depth 판정), 상세는 노트에	요구사항 3: 구조적·쉬운 답변 + 상세는 문서

4. 데이터 흐름 (`/branch-spec <slug>`)

1. 전제 확인     raw/branch-notes/<slug>.md 존재? 없으면 /branch 먼저 안내(종료)
2. Sources 수집  노트 ## Sources + 사용자 제공 URL
                 └ URL → wiki-source-summarizer (webfetch + verbatim + self-grep)
3. 결정 후보 추출 source Claim에서 decision 후보 + 대안 도출
4. 자동조사      Supporting Claim 없는 결정마다 (DD4 bound 적용):
   (bounded)     └ wiki-decision-researcher (공식문서 + 대기업 블로그, 대안 비교)
5. 라벨링        조사 후에도 근거 없으면 UNSUPPORTED_DECISION + trade-off 한 줄
6. 노트 채움      Decision Evidence Map 표(기존 포맷) + 구현 가이드 skeleton
7. 자동 /depth   wiki_structure_lint.py(1차) + branch-depth-auditor(2차) → Ready/Not-ready
8. 요약 보고      채운 것/UNSUPPORTED/조사 N/depth 판정 (DD5)

5. 컴포넌트 계약

5.1 `rules/subagent-input-contracts.md`

기존 rules 문서 스타일(표 + 명명된 실패 모드). 각 agent/명령의 필수 입력 · 선택 입력 · 누락 시 행동을 고정. 최소 커버: /branch-spec, wiki-source-summarizer, wiki-decision-researcher, wiki-doc-author. 산문으로 흩어진 Required Inputs를 재사용 가능한 schema로 승격하되 agent 본문과 모순되지 않게 참조 관계만 명시(SSOT 이중화 회피).

5.2 `.claude/commands/branch-spec.md`

frontmatter(description, argument-hint) + §4 흐름 + DD4 bound + 규칙. rules/subagent-input-contracts.md, rules/branch-depth-gate.md, templates/branch-note-template.md를 참조.

6. 요구사항 충족 매핑 (Phase 1)

요구사항	Phase 1	후속
1 체계적 관리	입력 계약으로 강화
2 비효율 x	자동조사로 수동 왕복 제거
3 구조적·쉬운 답변	명령 요약 + 상세는 노트(DD5)
4a 검증 매번	자동 /depth(DD2)	hook C1/C3 → P2
4b webfetch 조사	자동조사 단계(DD1)
4c 개수 아닌 근거	R1 출처 적정성 유지
4d 대안비교+언제	기존 표의 선택조건 컬럼	체크리스트 가독성 → P3 후보
4e wiki 문서화 기준	기존 /ingest 유지
4f~4g 윤문	—	Phase 3

7. 리스크 / 비범위 확인

기존 표 유지 → 린터 C3·기존 노트 깨질 게 없음(축소판의 핵심 이점).
자동조사 무한 확장 → DD4 bound로 차단.
SSOT 이중화(입력 계약 vs agent 본문) → 5.1에서 참조 관계만, 값 복제 금지.

5.2 KiB Raw Blame History