99 lines
12 KiB
Markdown
99 lines
12 KiB
Markdown
---
|
|
description: "빈 브랜치 노트를 source claim 기반으로 채우고(필요시 자동조사) 끝에 /depth로 검증"
|
|
---
|
|
|
|
사용자가 `/branch-spec <브랜치 이름> [추가 source URL ...]` 를 입력하면 아래 절차를 수행한다.
|
|
|
|
`/branch` 로 만든 빈 브랜치 노트를 **되묻지 않을 수준으로 채우는** 오케스트레이터입니다.
|
|
source claim 에서 결정 후보·대안 비교를 도출하고, 근거 없는 결정은 **먼저 자동조사**한 뒤 그래도 없으면 `UNSUPPORTED_DECISION` 으로 라벨링하고, 끝에 `/depth` 로 깊이를 검증합니다.
|
|
|
|
**브랜치 이름:** <브랜치 이름> [추가 source URL ...]
|
|
|
|
## 참조 (작업 시 정독)
|
|
|
|
- `rules/subagent-input-contracts.md` — 본 명령 + dispatch 할 agent 들의 입력 계약
|
|
- `rules/branch-depth-gate.md` — 끝에 적용할 깊이 판정 4축(R1~R4)
|
|
- `rules/coverage-gate.md` — 끝에 적용할 완전성 판정(빠진 관심사 3단계). depth 의 짝
|
|
- `templates/branch-note-template.md` — 채울 대상 구조(특히 `## Decision Evidence Map`, `## 구현 가이드`)
|
|
- `CLAUDE.md` §11, §15 — 근거 없는 결정 금지, 근거 기반 구현 명세
|
|
|
|
### ca-tmpl 구현·계약 ground truth (필수 — §2 에서 읽음, 읽기 전용)
|
|
|
|
이 wiki 의 branch-note 는 별도 레포 **`/home/donghyeon/workspace/ca-tmpl`** 의 *설계·계약 rationale 층*이다 (ca-tmpl `CLAUDE.md` HARD-STOP #8: 구현 종료 시 이 wiki 의 branch-note 갱신 의무 — 코드↔노트 양방향 결합). 명세를 추측이 아니라 **실제 구현·계약에 정합**시키려면 다음을 본다:
|
|
|
|
- `/home/donghyeon/workspace/ca-tmpl/CLAUDE.md` + `AGENTS.md` + 해당 `src/<module>/CLAUDE.md` — 아키텍처 HARD-STOP, module map, 레이어 규칙.
|
|
- `/home/donghyeon/workspace/ca-tmpl/docs/registries/*.yaml` — **계약 값의 SSOT**: `error-codes.yaml`(category enum·code·owner_branch·owner_layer·client_safe), `env-keys.yaml`, `headers.yaml`, `metrics.yaml`, `mdc-keys.yaml`, `capabilities.yaml`, `secrets-classification.yaml`. 각 row 의 `owner_branch:` 가 그 계약을 정한 branch-note 를 가리킨다.
|
|
- `/home/donghyeon/workspace/ca-tmpl/docs/runbooks/*.md` — 운영 시나리오(장애 대응). retryable/category 정책의 운영측 근거.
|
|
- `/home/donghyeon/workspace/ca-tmpl/src/<module>/` — **무엇이 실제 구현됐는지의 최종 SSOT.** registry 주석조차 drift 가능(예: `error-codes.yaml` L580 의 stale `PERSISTENCE`) → enum/클래스 실체는 `src/shared-contract/src/main/java/dev/caskeleton/shared/error/Category.java` 같은 코드가 authoritative. module: `domain-core`·`application-core`·`adapter-web`·`adapter-persistence`·`adapter-outbound`·`shared-contract`·`sample-portfolio`·`app-bootstrap`.
|
|
- **완수한 sibling branch-notes** (`raw/branch-notes/feature-*.md` 중 구현 완료분) — registry `owner_branch` 로 발견. 앞선 결정·구조·계약을 알아야 일관성을 깨지 않는다.
|
|
|
|
## 작업 절차
|
|
|
|
1. **전제 확인**
|
|
- 인자 비면 브랜치 이름 요청(종료). `.md`·prefix 누락은 관대히 보정(`rules/naming-conventions.md` §2.1).
|
|
- `raw/branch-notes/<slug>.md` 가 **없으면** 생성하지 말고 `/branch <slug>` 먼저 실행하도록 안내(종료). 채움은 본 명령, 생성은 `/branch`.
|
|
- 노트의 `## Parent` 가 비어 있으면 `NEEDS_CONTEXT`.
|
|
|
|
2. **구현·계약 현황 확인 (ca-tmpl ground truth — 필수, 추측 방지)**
|
|
- 위 §참조의 ca-tmpl 자료를 **읽기 전용**으로 확인. 순서: 아키텍처 진입점(`CLAUDE.md`/`AGENTS.md` + 건드리는 레이어의 `src/<module>/CLAUDE.md`) → 결정이 건드리는 `docs/registries/*.yaml` → 관련 `docs/runbooks/` → `src/<module>/` grep.
|
|
- **계약 값은 invent 금지** — 결정이 error code / category / env key / header / metric / capability / secret 을 건드리면 registry 의 *기존 값*을 재사용. 없으면 "신규 제안"임을 명시. registry row 의 `owner_branch` 로 그 계약을 정한 sibling branch-note 를 찾아 정합 확인.
|
|
- **`actually-implemented` 주장은 코드로 확인** — 클래스/메커니즘이 "구현됐다"고 적기 전 `src/` 를 grep. *노트의 자기 보고만으로 FACT 화 금지.* 코드에 없으면 `documented-only`/`planned` 로 표기.
|
|
- **drift 발견 시 surface** — branch-note 의 명칭/매핑이 registry 또는 코드 enum 과 어긋나면(예: stale category 명) `## Audit & Findings` 에 `CATEGORY_DRIFT` 등으로 기록. 사용자 작성 결정 영역이면 자동 rewrite 말고 *정합 권고만*.
|
|
- ca-tmpl 경로 부재 시 `NO_GROUND_TRUTH` 라벨 + registry/노트 근거로만 진행하고 그 한계를 §8 에서 보고.
|
|
|
|
3. **Sources 수집**
|
|
- 노트의 `## Sources / 근거` 표 + 인자로 받은 추가 URL 을 합친다.
|
|
- URL 이면 `wiki-source-summarizer` dispatch (source_type + parent + 정당화 결정 한 줄 전달 — 입력 계약 §wiki-source-summarizer). 결과 raw 의 Claim ID 를 수집.
|
|
|
|
4. **결정 후보 추출**
|
|
- 수집한 source Claim 과 노트의 `## TODO`·`## 결정 사항`, 그리고 §2 에서 본 ca-tmpl 구현·계약 현황에서 *내려야 할 결정*과 *각 결정의 대안*을 도출.
|
|
- 각 후보를 `Decision ID`(D1, D2 …)로 부여.
|
|
|
|
5. **자동조사 (bounded — DD4)**
|
|
- Supporting Claim 이 없는 결정마다 `wiki-decision-researcher` dispatch (decision_topic + parent_branch + constraints + N — 입력 계약 §wiki-decision-researcher). 공식문서 + 대기업 블로그를 webfetch 로 조사해 대안 비교 + Claim 생성.
|
|
- **bound: 회당 최대 6개 결정.** 초과분은 채우지 말고 `deferred` 목록으로 보고(절대 silent 절단 금지). 사용자가 재실행하거나 수동 조사.
|
|
- 조사는 **개수가 아니라 근거** — 회사 블로그 1개로 "공식" 승격 금지(`rules/branch-depth-gate.md` 출처 타입 적정성).
|
|
|
|
6. **라벨링**
|
|
- 조사 후에도 근거가 없는 결정은 **추측 금지**. `Decision Evidence Map` 에 `UNSUPPORTED_DECISION` + trade-off 한 줄로 남긴다.
|
|
- 구현 가이드의 근거 없는 detail 은 `UNSUPPORTED_IMPL_DECISION` 라벨(CLAUDE.md §15.5 R2).
|
|
|
|
7. **노트 채움 (기존 표 포맷 유지)**
|
|
- `## Decision Evidence Map` 표를 채운다: Decision / 선택 조건(언제 이 결정/언제 대안) / Supporting Claims(`raw/<slug>.md#C1`) / Evidence Strength / Open Risk.
|
|
- `## 구현 가이드` 는 in-scope 항목을 명명·경로·메커니즘으로 구체화하거나 `UNSUPPORTED_IMPL_DECISION` 라벨(CLAUDE.md §15.5 3-rule). §2 에서 확인한 *실제 클래스/패키지/registry 값*을 anchor 로 쓰되, 코드로 확인 안 된 것은 `planned` 로 표기.
|
|
- **템플릿 섹션 순서 정합 (린터 미검사 — 필수 수기 확인)**: `wiki_structure_lint.py` 는 섹션 *존재*만 검사하고 *순서·중복*은 검사하지 않는다(린트 PASS ≠ 템플릿 정합). pre-template 노트(템플릿 도입 전 작성분)는 섹션 순서가 템플릿과 다를 수 있으므로, 채운 뒤 `grep '^## ' <노트>` 와 `templates/branch-note-template.md` 의 `## ` 순서를 대조해 **템플릿 순서로 재배치**한다. 템플릿에 없는 *노트 고유 섹션*(예: `## 테스트 계약`, `## Secret Source Defaults`, `## Work Item Contract`)은 **삭제 금지** — *가장 관련된 템플릿 섹션 바로 옆*에 슬롯한다(검증성 섹션 → `## Claims To Verify` 앞, 결정 테이블 → `## Decision Evidence Map` 앞, Sources 보강 → `## Sources` 뒤).
|
|
- 파일 편집은 직접 Edit 하거나 대규모(전면 재배치 포함)면 `wiki-doc-author`(mode=migrate)에 위임. **기존 사용자 작성 본문 verbatim 보존.**
|
|
|
|
8. **자동 게이트 — 깊이 + 완전성 (맨 끝, 나란히)**
|
|
- **(8a) /depth (깊이)** — `python3 .claude/hooks/wiki_structure_lint.py --file raw/branch-notes/<slug>.md` (1차 구조) → 통과 시 `branch-depth-auditor` dispatch (2차 R1~R4). 판정 `Ready`(Blocking 0) / `Not ready`.
|
|
- **(8b) /coverage (완전성)** — `/coverage <slug>` 흐름: 1차 `python3 .claude/hooks/wiki_structure_lint.py --coverage-pre raw/branch-notes/<slug>.md` (0 PASS / 1 FAIL / 3 EXEMPT) → PASS 시 `coverage-auditor` dispatch (governing 문서·선례 브랜치·ca-tmpl 코드 대조). 판정 `Covered`(missing 0) / `Not-covered`.
|
|
- **(8c) 루프백 — 천장 2회 (project-spec §9 와 동일 규율)** — depth `Not ready` *또는* coverage `Not-covered`(🔴 missing) 이면 → §3~§7 로 되돌아가 *빠진 관심사를 결정으로 채우거나 깊이를 보강* → 8a·8b 재실행. **루프는 최대 2회** — 2회 초과에도 미통과면 무한 재조사로 컨텍스트를 태우지 말고 `Not ready`/`Not-covered` 로 **깨끗이 종료**하고 잔여 finding 을 사용자에게 보고(다음 세션 재개).
|
|
- coverage 가 찾은 missing 관심사는 §3 결정 후보로 편입 → §5 자동조사 대상이 됨(깊이·완전성이 한 루프에서 수렴).
|
|
|
|
9. **요약 보고 (DD5 — 짧게, 상세는 노트에)**
|
|
- 사람이 5초에 읽을 요약만: `채운 결정 N / UNSUPPORTED K / 조사한 결정 M / deferred D / drift D' / depth: Ready|Not ready / coverage: Covered|Not-covered (missing X)`.
|
|
- 통과 못하면 *무엇을 더 채워야 하는지* 한 줄씩(depth·coverage finding 인용). 상세는 노트 본문에.
|
|
- **funnel 계측 (no-silent-truncation — 게이트/컨트롤러가 균형 검증)**: 요약 끝에 기계 파싱용 블록을 방출한다. `found = processed + dropped` 균형 필수:
|
|
|
|
```wiki-stats
|
|
agent: branch-spec
|
|
found: {{대상 결정 총수 = 채움 + UNSUPPORTED + deferred}}
|
|
processed: {{채운 결정 + UNSUPPORTED_DECISION 라벨 수}}
|
|
dropped: {{deferred 수}}
|
|
dropped_reason: {{deferred 사유 (bound 6 초과 등), 0 이면 행 생략 가능}}
|
|
```
|
|
|
|
## 규칙
|
|
|
|
- **추측해서 FACT 로 채우지 않는다.** 근거 없으면 자동조사 → 실패 시 `UNSUPPORTED_*` 라벨(CLAUDE.md §11).
|
|
- **계약 값을 지어내지 않는다.** error code / category enum / env key / header / metric 등은 `ca-tmpl/docs/registries/*.yaml` + 코드 enum(예: `shared/error/Category.java`)이 SSOT. registry 에 없으면 "신규 제안"으로만 표기, 기존 값처럼 단정 금지.
|
|
- **`actually-implemented` 는 `src/` grep 으로만 확정.** 다른 노트의 자기 보고(note→note 전이)는 근거가 아니다. 코드 미확인 항목은 `documented-only`/`planned`.
|
|
- **기존 본문 보존** — 채움은 빈 셀/skeleton 에만. 사용자가 쓴 결정·메모를 덮어쓰지 않는다.
|
|
- **템플릿 순서·중복은 린터가 안 잡는다** — 채움 후 `## ` 헤더 순서를 `templates/branch-note-template.md` 와 대조해 템플릿 순서로 정렬(§7). 노트 고유 섹션은 관련 템플릿 섹션 옆에 보존(삭제 금지). pre-template 노트일수록 이 단계가 필수다.
|
|
- **자동조사는 bounded** — §4 의 6개 한도. 초과는 `deferred` 명시(`UNBOUNDED_RESEARCH` 실패 모드 방지). deferred 는 §9 의 `wiki-stats` funnel 에 계측된다(silent 절단 불가).
|
|
- **루프 천장 2회** — §8c. 2회 초과 미통과는 실패가 아니라 *정상 종료 경로* (잔여 finding 보고 후 다음 세션 재개).
|
|
- **새 agent 를 만들지 않는다** — 기존 서브에이전트(`wiki-source-summarizer` / `wiki-decision-researcher` / `wiki-doc-author`)만 dispatch.
|
|
- **검증은 /depth + /coverage 에 위임** — 본 명령은 *채움*에 집중. 깊이(`/depth`)·완전성(`/coverage`) 판정 로직을 중복 구현하지 않는다. 두 게이트가 모두 통과해야 완성.
|
|
- `wiki/log.md` 기록 안 함(브랜치 작업은 빈번, 로그 노이즈) — `/branch`·`/depth` 와 동일 정책.
|
|
</content>
|