12 KiB
12 KiB
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 |
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_SECTIONFAIL. 그 노트는 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 와 동형:
- 인자 검증 — slug 비면 요청. kebab-case. project-note 는 prefix 4종 규칙 비적용 (branch 전용). 슬러그는 프로젝트 이름.
- 파일 존재 확인 —
raw/project-notes/<slug>.md있으면 덮어쓰지 말고 경로만 안내(종료). - 스캐폴딩 —
wiki-doc-author(mode=create, category=project-note) 위임 또는templates/project-template.md복사. frontmattertitle/status_label: active/last_reviewed(오늘) 치환. 본문 placeholder 보존. - 사용자 안내 — "이제
/project-spec <slug> <프로젝트 목표>로 채우세요." 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 작업 흐름
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 에서 상세화)
rules/project-readiness-gate.md작성 (branch-depth-gate.md 구조 차용, proxy 정의 포함).templates/project-template.md에 Branch 분해/실행계획 섹션 추가 (기존 §8.1 Branches 는 완성된 branch 등재용, 신규 섹션은 계획 분해표).wiki_structure_lint.pyproject 모드 + proxy 검사 +test_wiki_structure_lint.py테스트..claude/agents/project-readiness-auditor.md(Claude 전용)..claude/commands/project.md,.claude/commands/project-spec.md(Claude 전용).CLAUDE.mdagent 목록 +1(Claude 전용 명시) / 커맨드 목록 +2 / 파이프라인 서술.- dogfooding —
/project로 신규 노트 스캐폴딩 →/project-spec→ 게이트 통과 확인. 보강.