67 lines
4.5 KiB
Markdown
67 lines
4.5 KiB
Markdown
# rules/branch-depth-gate — 브랜치 노트 구현 착수 깊이 게이트
|
|
|
|
> `rules/` 의 방법론 규칙. branch-note 1개가 **코딩 착수해도 되묻지 않을 만큼 깊은가**를 판정한다.
|
|
> 이 문서는 **"전체 계약"이 아니다** — 전체 계약은 `raw/project-notes/ca-skeleton-operational-contract.md`.
|
|
> `feature-implementation-readiness-scorecard`(스켈레톤 adoption 거시 게이트)와 **다른 층·다른 범위**로 공존한다. 본 게이트는 *브랜치 노트 1개의 깊이* 미시 게이트.
|
|
|
|
## 적용
|
|
|
|
- 대상: `raw/branch-notes/feature-*.md` (구현 착수 전).
|
|
- 실행: `/depth <branch>` →
|
|
1. **1차 결정론 검사** `.claude/hooks/wiki_structure_lint.py` (구조·링크 문법 — 싸고 빠름)
|
|
2. **2차 의미 판정** `branch-depth-auditor` (아래 4축 — 소스를 읽고 의미로 판정)
|
|
- 본 게이트는 **read-only**. 브랜치 노트를 편집하지 않으며 판정을 노트에 박지도 않는다.
|
|
|
|
## 역할 분담 (결정론 vs 의미)
|
|
|
|
| | 1차 린터(결정론) | 2차 감사기(LLM 의미) |
|
|
|---|---|---|
|
|
| R1 조사 깊이 | 링크 깨짐·앵커 부재만 | **claim 이 L0(존재)인지 L1+(메커니즘)인지** |
|
|
| R2 결정 조건 | `선택 조건` 셀 *비었는지* | 선택 조건이 *말이 되는지* |
|
|
| R3 구체 detail | 섹션/라벨 *존재* | detail 이 *충분한지* |
|
|
| R4 엣지·실패·의존 | 섹션 *존재* | 실패 경로가 *적절한지*, *암시된* 의존 포착 |
|
|
|
|
→ 2차 감사기는 **의미만** 본다(구조 존재는 1차가 이미 확인).
|
|
|
|
## 4축 (R1~R4)
|
|
|
|
> 축 라벨은 `R1~R4`. branch-note 의 Decision Evidence Map 이 `D1`,`D2` 를 *Decision ID* 로 쓰므로 `D*` 와 구분.
|
|
|
|
| 축 | Pass 조건 | Blocking(Not ready) 트리거 |
|
|
|---|---|---|
|
|
| **R1. 조사 깊이** | 각 Decision 의 Supporting Claim 이 깊이 사다리 충족 — 의존 메커니즘 L1+, 분기 조건 L2+ | 결정 근거 claim 이 순수 L0(존재만)뿐 |
|
|
| **R2. 결정 조건** | 각 Decision 이 "어떤 조건일 때 A, 아니면 B"의 선택 기준 명시 | `검토한 대안`은 있는데 *언제 그 대안을 고르는지* 기준 부재 |
|
|
| **R3. 구체 detail** | `## 구현 가이드` 의 각 in-scope 항목이 명명·경로·메커니즘·API/테스트명 구체화 **또는** `UNSUPPORTED_IMPL_DECISION` 라벨 + trade-off 한 줄 | in-scope 항목인데 구현 detail 도 UNSUPPORTED 라벨도 없음 |
|
|
| **R4. 엣지·실패·의존** | 실패/엣지 경로 열거 + 다른 contract 의존을 *대상 브랜치 + 그 Decision ID* 로 링크 | 정상 경로만 / 다른 계약 의존이 암시되는데 링크 안 됨 |
|
|
|
|
## R1 클레임 깊이 사다리
|
|
|
|
깊이의 단위는 **문서 개수가 아니라 결정별 종결**. 얕은 문서 10개 < 결정을 닫는 문서 1개.
|
|
|
|
| 레벨 | 클레임이 답하는 것 | 판정 |
|
|
|---|---|---|
|
|
| **L0 존재** | "X 가 있다 / 권장한다" | 단독 불충분 |
|
|
| **L1 메커니즘** | 어떻게 동작 / 언제 발생 | 메커니즘 의존 결정의 최소선 |
|
|
| **L2 조건·경계** | 언제 적용/제외, 실패 시 어떻게 | 분기 조건 있는 결정의 최소선 |
|
|
| **L3 검증** | 확인 방법·수치·반례 | 가산점 |
|
|
|
|
**출처 타입 적정성** (개수 기준 대체):
|
|
- 스펙/표준이 정의한 동작 → `official-standard`/`official-vendor-doc` 1개로 충분.
|
|
- "대기업은 보통 이렇게 한다" 운영 패턴 추론 → 회사 블로그 1개는 "공식" 불가. 독립 사례 2개+ 또는 official 1개 병행.
|
|
|
|
조사는 **결정-주도(top-down)**: 내려야 할 결정·미지수를 먼저 나열하고 각각을 닫을 때까지 조사. 조사 완료 = 모든 결정 종결 = 착수 가능.
|
|
|
|
## 판정 규칙
|
|
|
|
- 심각도 3단계: `Blocking`(Not ready) · `Should-fix`(권고) · `Advisory`(참고).
|
|
- **Ready = Blocking 0건.** Should-fix 가 남아도 사용자가 "감수" 선언 시 착수 가능(리포트에 기록).
|
|
- 모든 finding 은 4종 세트로 근거화: `심각도 · 위치(섹션/행) · 예상 의구심("구현 중 여기서 ___를 되묻게 됨") · 채울 방법`. 근거 없는 지적 금지.
|
|
|
|
## 명명된 실패 모드
|
|
|
|
- `EXISTENCE_ONLY` (R1): 결정 근거가 L0 뿐.
|
|
- `NO_SELECTION_CRITERION` (R2): 대안은 있으나 선택 조건 없음/무의미.
|
|
- `IMPL_UNDERSPECIFIED` (R3): in-scope 항목에 구현 detail·UNSUPPORTED 라벨 둘 다 없거나 불충분.
|
|
- `HAPPY_PATH_ONLY` (R4): 실패/엣지 경로 미열거.
|
|
- `IMPLICIT_DEPENDENCY` (R4): 다른 계약 의존이 암시되나 대상 브랜치/Decision ID 링크 없음.
|