167 lines
12 KiB
Markdown
167 lines
12 KiB
Markdown
# project-note 작성 파이프라인 — 설계 (Design Spec)
|
||
|
||
> 날짜: 2026-06-05
|
||
> 상태: 설계 승인 대기 → 구현 계획(writing-plans)
|
||
> 작성 맥락: branch-note 에는 `/branch`(스캐폴딩) + `/branch-spec`(깊은 채움) 2단 파이프라인이 있으나, project-note 에는 *깊은 작성* 커맨드가 없다. `wiki-doc-author`(mode=create) 가 생성만 가능. 이 갭을 메운다.
|
||
|
||
---
|
||
|
||
## 1. 문제 / Problem
|
||
|
||
- `raw/project-notes/` 는 프로젝트의 **최상위 hub** (문제정의 · 시스템 아키텍처 · 핵심 시퀀스 · 기술결정 · branch 분해). 모든 branch/error/source 가 여기로 upward link.
|
||
- 현재 project-note 를 **ca-skeleton-operational-contract.md 수준(caliber)** 으로 끌어올리는 자동화가 없다. 그 노트는 project-note 작성의 모든 시행착오가 누적된 reference 이며, 다른 프로젝트도 그 *엄격성 수준*으로 작성되어야 한다.
|
||
- 강조: **내용을 복제하라는 게 아니다.** ca-skeleton 의 §21 Contract Registry, §22 Sample-portfolio Matrix 등은 *그 프로젝트(contract-skeleton/platform)* 에 특화된 내용이다. 게이트가 강제하는 것은 *깊이·근거·분해 수준* 이고, 내용은 프로젝트마다 다르다.
|
||
|
||
### 성공 기준 (측정 가능)
|
||
|
||
- `/project <slug>` 로 빈 project-note 스캐폴딩 생성 (추측 채움 0).
|
||
- `/project-spec <slug> <목표>` 로 hub 를 채우면, 끝의 readiness 게이트가 4축(R1~R4) 모두 L2+ 일 때만 `Ready` 를 낸다.
|
||
- project-spec 산출물의 **Branch 분해표** 가 그대로 `/branch <slug>` 입력이 되고, 이어 `/branch-spec` 이 그 branch 를 깊게 채운다 (핸드오프 무손실).
|
||
|
||
---
|
||
|
||
## 2. 아키텍처 / 신규 산출물
|
||
|
||
> **플랫폼 범위: Claude Code 전용** (사용자 결정 2026-06-05). 기존 9개 agent·13개 command 는 Claude+Codex+Antigravity 3-플랫폼 패리티지만, 본 파이프라인은 Codex/Antigravity 포팅을 하지 않는다. 따라서 `scripts/sync_automation.py`(최신 커밋에서 삭제됨) 복원·포팅 artifact 생성은 **범위 밖**. CLAUDE.md 의 3-플랫폼 서술에서 이 기능만 명시적 예외로 표기한다.
|
||
|
||
| 산출물 | 역할 | 대응(parallel) |
|
||
|---|---|---|
|
||
| `.claude/commands/project.md` | 얇은 스캐폴딩 커맨드. `wiki-doc-author`(mode=create, category=project-note) 위임. 추측 채움 없음 | `branch.md` |
|
||
| `.claude/commands/project-spec.md` | 깊은 조사 오케스트레이터 (인자: slug + 프로젝트 목표 prose). 내부에 readiness 게이트 단계 포함 | `branch-spec.md` |
|
||
| `rules/project-readiness-gate.md` | 품질 4축(R1~R4) + 깊이 사다리(L0~L3) + 명명된 실패 모드 + **구조-불가지 proxy** 정의 | `branch-depth-gate.md` |
|
||
| `.claude/agents/project-readiness-auditor.md` | hub 깊이 *의미* 판정 (read-only). L0 존재 vs L1+ 메커니즘 깊이 구분 | `branch-depth-auditor.md` |
|
||
| `.claude/hooks/wiki_structure_lint.py` (확장) | **project 모드** — `raw/project-notes/*.md` 를 C1 섹션명 매칭에서 면제하고 구조-불가지 proxy + C2 링크만 검사 | 기존 branch/full/links 모드 |
|
||
| `templates/project-template.md` (편집) | **Branch 분해/실행계획 섹션 추가** — `/branch`·`/branch-spec` 핸드오프용 {slug \| 목표조건 \| 우선순위} 표 | — |
|
||
|
||
### 결정론 계층이 *섹션명 매칭*이 아닌 이유 (DISCOVERED 2026-06-05)
|
||
|
||
- exemplar `ca-skeleton-operational-contract.md` 를 기존 린터로 검사하면 **13건 `MISSING_SECTION` FAIL**. 그 노트는 project-template §1~14 가 아니라 *계약 특화* 자기 구조(§1 목표 … §30 아키텍처 … §33 checklist)를 쓴다.
|
||
- 즉 *내용*뿐 아니라 *섹션 구성*도 프로젝트마다 다르다. 따라서 게이트가 "project-template §1~14 섹션 존재"를 강제하면 **exemplar 자신이 탈락**한다.
|
||
- 결론: 결정론 계층은 **구조-불가지 proxy** 만 본다 — 임베디드 다이어그램(`![[...drawio` 또는 ```` ```mermaid ````) 존재, Branch 분해표 존재, frontmatter 필수 키, 링크 실재(C2). caliber(R1~R4 깊이)는 전적으로 LLM auditor 가 판정.
|
||
|
||
> **독립 `/project-readiness` 커맨드는 만들지 않는다.** 게이트는 `/project-spec` 내부 마지막 단계 (branch-spec §8 방식). `/depth` 와 달리 단독 호출 수요가 낮다.
|
||
|
||
---
|
||
|
||
## 3. `/project` — 스캐폴딩 커맨드 (얇음)
|
||
|
||
`branch.md` 와 동형:
|
||
|
||
1. **인자 검증** — slug 비면 요청. kebab-case. project-note 는 prefix 4종 규칙 비적용 (branch 전용). 슬러그는 프로젝트 이름.
|
||
2. **파일 존재 확인** — `raw/project-notes/<slug>.md` 있으면 덮어쓰지 말고 경로만 안내(종료).
|
||
3. **스캐폴딩** — `wiki-doc-author`(mode=create, category=project-note) 위임 또는 `templates/project-template.md` 복사. frontmatter `title`/`status_label: active`/`last_reviewed`(오늘) 치환. 본문 placeholder 보존.
|
||
4. **사용자 안내** — "이제 `/project-spec <slug> <프로젝트 목표>` 로 채우세요."
|
||
5. `wiki/log.md` 기록 안 함 (branch 와 동일 정책).
|
||
|
||
> project-note 는 cluster 의 root 이므로 Parent upward link 불요 (자기 자신이 hub). `wiki-doc-author` 가 daily-note·project-note 를 Parent 예외로 이미 처리.
|
||
|
||
---
|
||
|
||
## 4. `/project-spec` — 깊은 조사 오케스트레이터
|
||
|
||
**인자:** `<slug> <프로젝트 목표 자연어>` (목표 prose 는 구체화의 시드).
|
||
|
||
### 4.1 작업 흐름
|
||
|
||
```text
|
||
1. 전제 확인 — 노트 없으면 /project 먼저 안내(종료). §1 비면 사용자에게 목표 질문.
|
||
2. 프로젝트 ground truth 확인 (읽기전용) — 대상 repo 코드/기존 raw/관련 노트.
|
||
ca-tmpl류면 그 repo(/home/donghyeon/workspace/ca-tmpl)가 SSOT.
|
||
3. 문제정의·성공기준 구체화 — 추상 표현 거부, 측정가능 기준 도출.
|
||
★ 명확화 질문 — 정해야 하는데 근거·기본값 없는 '사용자 소유 결정'(범위/우선순위/목표)은
|
||
추측·UNSUPPORTED 라벨 대신 AskUserQuestion 으로 직접 묻는다.
|
||
4. 아키텍처 + 시퀀스 —
|
||
- Mermaid 시퀀스 자동 작성 (happy + error path, autonumber).
|
||
- .drawio 아키텍처는 자동생성 불가 → 스캐폴딩 + 'needs-diagram' 표시 →
|
||
사용자가 작성/요청 후 wiki-diagram-reviewer 로 ≥95 검수 (게이트가 확인).
|
||
5. 기술결정 대안조사 — 주요 결정마다 wiki-decision-researcher dispatch (bounded ≤6).
|
||
조사 후에도 근거 없으면 UNSUPPORTED_DECISION 라벨 + trade-off 한 줄.
|
||
6. Branch 분해표 — {branch slug(naming-conventions 준수) | 달성 목표 조건(측정가능) | 우선순위} 만.
|
||
결정 내용·메커니즘은 hub에 적지 않음 (SSOT 이중화 방지).
|
||
이 표가 /branch·/branch-spec 핸드오프.
|
||
7. 프로젝트 레벨 고정 결정 — Stack commitment / SSOT owner 등 branch 충돌 방지 결정(내용은 프로젝트별).
|
||
8. 검증등급 + 면접·외부공개 경계 (project-template §9·§10).
|
||
9. [내부 게이트] project-readiness —
|
||
python3 .claude/hooks/wiki_structure_lint.py --mode project --file <path> (1차 구조)
|
||
→ 통과 시 project-readiness-auditor dispatch (2차 의미, R1~R4).
|
||
판정 Ready(Blocking 0) / Not-ready. Not-ready면 §3~§8로 루프백.
|
||
10. 요약 보고 — 짧게: 채운 결정 N / UNSUPPORTED K / 조사 M / branch 분해 B / needs-diagram D /
|
||
readiness: Ready|Not-ready (Blocking 축 인용).
|
||
```
|
||
|
||
### 4.2 branch-spec 과의 차이 (핵심)
|
||
|
||
| 측면 | `/branch-spec` | `/project-spec` |
|
||
|---|---|---|
|
||
| 대상 | 단일 branch (결정+claim 단위) | 프로젝트 hub (root) |
|
||
| 근거 없는 결정 처리 | 자동조사 → 실패 시 `UNSUPPORTED_DECISION` 라벨 | 자동조사 + **사용자 소유 결정은 AskUserQuestion 으로 직접 질의** |
|
||
| 핸드오프 출력 | 구현 가이드(코드 착수 명세) | Branch 분해표(자식 branch 네이밍+목표조건) → `/branch` 입력 |
|
||
| 게이트 | depth(R1~R4) + coverage | project-readiness(R1~R4, 내부 단계) |
|
||
| 다이어그램 | 보통 불요 | 아키텍처 .drawio + 시퀀스 필수 |
|
||
|
||
### 4.3 규칙 (branch-spec 에서 계승)
|
||
|
||
- 추측해서 FACT 로 채우지 않는다. 자동조사 → 실패 시 `UNSUPPORTED_*` 또는 **사용자 질의**.
|
||
- `actually-implemented` 는 `src/` grep 으로만 확정. note→note 자기보고 전이 금지.
|
||
- 기존 사용자 작성 본문 보존. 채움은 빈 셀/skeleton 에만.
|
||
- 자동조사 bounded (≤6). 초과는 `deferred` 명시.
|
||
- 새 agent 만들지 않음 — `wiki-source-summarizer`/`wiki-decision-researcher`/`wiki-doc-author`/`project-readiness-auditor`(신규)만 dispatch.
|
||
- `wiki/log.md` 기록 안 함.
|
||
|
||
---
|
||
|
||
## 5. project-readiness 게이트 (v1, 사용하며 보강)
|
||
|
||
`rules/project-readiness-gate.md` 가 정의. **v1 으로 구현 후 실사용하며 부족분 보강** (over-engineering 금지).
|
||
|
||
### 5.1 4축 × 깊이 사다리
|
||
|
||
| 축 | 판정 질문 | L0(부족) | L3(충분) |
|
||
|---|---|---|---|
|
||
| **R1. 문제·성공 구체성** | 측정가능 기준이 있나, 추상 표현인가 | "잘 동작한다" | 수치/구체 시나리오 |
|
||
| **R2. 아키텍처·시퀀스 깊이** | 다이어그램 존재 + 컨퍼런스급인가, happy+error 시퀀스인가 | 다이어그램 없음 | `.drawio` ≥95 + error path 시퀀스 |
|
||
| **R3. 결정 근거성** | 기술결정이 대안+외부근거로 뒷받침되나, 맨주장인가 | 근거 0 | 대안조사 + 출처 wikilink |
|
||
| **R4. Branch 분해 실행가능성** | 각 branch 가 valid slug + 측정가능 목표조건을 갖나 | 목록 없음 | 전부 slug+측정가능 조건 |
|
||
|
||
- **Ready 조건**: 4축 모두 **L2+** (Blocking 0). 이것이 "ca-skeleton caliber" 의 조작적 정의.
|
||
- L1 이하 축은 Blocking finding → §3~§8 루프백.
|
||
|
||
### 5.2 1차 결정론 린터 (wiki_structure_lint.py project 모드 — 구조-불가지 proxy)
|
||
|
||
- `classify()` 가 `raw/project-notes/*.md` 를 새 모드 `"project"` 로 분기 (C1 섹션명 매칭 면제 — exemplar 비순응 때문, §2 DISCOVERED 참조).
|
||
- proxy 검사 (구조-불가지, 섹션명에 의존 안 함):
|
||
- `PROJECT_NO_DIAGRAM` — 임베디드 다이어그램 0개 (`![[....drawio` 임베드도, ```` ```mermaid ```` 블록도 없음). R2 proxy.
|
||
- `PROJECT_NO_BRANCH_TABLE` — Branch 분해표 부재 (heading 토큰에 `branch`/`브랜치` 포함 + 그 아래 `|---|` 표 행). R4 proxy.
|
||
- `MISSING_FRONTMATTER` — project-template frontmatter 필수 키 누락 (기존 check 재사용).
|
||
- C2 링크 검사는 그대로 (BROKEN_LINK / BROKEN_MD_LINK / DANGLING_ANCHOR).
|
||
- 통과해야 2차 auditor 로 진행. proxy 는 *존재* 만 본다 — *깊이/caliber* 는 auditor.
|
||
|
||
### 5.3 2차 의미 게이트 (project-readiness-auditor agent)
|
||
|
||
- read-only. `branch-depth-auditor` 와 동형 KPI: *위반(L0/L1)을 찾는 것이 목표*, 승인이 아님.
|
||
- "섹션이 존재한다(L0)" 와 "메커니즘·근거까지 구체화됐다(L2+)" 를 구분.
|
||
- 출력: 축별 L 등급 + file:line 근거 + Ready/Not-ready verdict.
|
||
|
||
---
|
||
|
||
## 6. 범위 밖 (YAGNI)
|
||
|
||
- **Codex/Antigravity 포팅 + sync_automation.py 복원** — 범위 밖 (Claude Code 전용, 사용자 결정).
|
||
- 독립 `/project-readiness` 커맨드 — 만들지 않음 (내부 단계로 충분).
|
||
- ca-skeleton 의 도메인 특화 섹션(Contract Registry/Sample-portfolio Matrix 등) 강제 — 안 함 (프로젝트별 내용).
|
||
- `.drawio` 자동 생성 — 불가능, 사용자/`wiki-diagram-reviewer` 협업으로 처리.
|
||
- coverage 게이트 별도 분리 — project 단계에선 readiness 1개로 시작 (보강 시 재검토).
|
||
- 결정론 proxy 의 *깊이* 판정 — 안 함 (존재만; 깊이는 auditor).
|
||
|
||
---
|
||
|
||
## 7. 구현 순서 (writing-plans 에서 상세화)
|
||
|
||
1. `rules/project-readiness-gate.md` 작성 (branch-depth-gate.md 구조 차용, proxy 정의 포함).
|
||
2. `templates/project-template.md` 에 Branch 분해/실행계획 섹션 추가 (기존 §8.1 Branches 는 *완성된* branch 등재용, 신규 섹션은 *계획* 분해표).
|
||
3. `wiki_structure_lint.py` project 모드 + proxy 검사 + `test_wiki_structure_lint.py` 테스트.
|
||
4. `.claude/agents/project-readiness-auditor.md` (Claude 전용).
|
||
5. `.claude/commands/project.md`, `.claude/commands/project-spec.md` (Claude 전용).
|
||
6. `CLAUDE.md` agent 목록 +1(Claude 전용 명시) / 커맨드 목록 +2 / 파이프라인 서술.
|
||
7. dogfooding — `/project` 로 신규 노트 스캐폴딩 → `/project-spec` → 게이트 통과 확인. 보강.
|