donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
main
llm-wiki/docs/superpowers/specs/2026-06-05-project-note-pipeline-design.md
T

12 KiB
Raw Permalink Blame History

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축(R1R4) + 깊이 사다리(L0L3) + 명명된 실패 모드 + 구조-불가지 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 작업 흐름

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 → 게이트 통과 확인. 보강.
Reference in New Issue View Git Blame Copy Permalink