llm-wiki/.claude/commands/project-spec.md

description, argument-hint

description	argument-hint
빈 프로젝트 노트를 깊은 조사로 ca-skeleton 수준까지 채우고 끝에 readiness 게이트로 검증	<프로젝트 slug> <프로젝트 목표 자연어> [근거 URL ...]

/project 로 만든 빈 project-note(hub)를 다음 작업의 출발점이 될 만큼 깊게 채우는 오케스트레이터입니다. 기준선은 raw/project-notes/ca-skeleton-operational-contract.md 의 caliber(엄격성)이며, 내용·섹션 구성은 프로젝트마다 다릅니다. 목표 prose 에서 문제·아키텍처·기술결정·branch 분해를 도출하고, 근거 없는 결정은 자동조사하되 사용자 소유 결정(범위/우선순위/목표)은 직접 질문으로 채우고, 끝에 readiness 게이트로 검증합니다.

프로젝트 slug + 목표: $ARGUMENTS

참조 (작업 시 정독)

• rules/project-readiness-gate.md — 끝에 적용할 4축(R1~R4) + proxy + 실패 모드.
• rules/naming-conventions.md §2.1 — Branch 분해표 slug 규칙.
• rules/diagram-standards.md — 아키텍처 .drawio / 시퀀스 Mermaid 컨퍼런스급 기준.
• templates/project-template.md — 채울 대상 구조(특히 §3 아키텍처, §4 시퀀스, §6 기술결정, §8.0 Branch 분해).
• CLAUDE.md §11, §15 — 근거 없는 결정 금지, 파생 규칙.

프로젝트 ground truth (필수 — 추측 방지, 읽기 전용)

대상 프로젝트에 코드 레포가 있으면 그 레포가 SSOT. 예: ca-tmpl 류는 /home/donghyeon/workspace/ca-tmpl 의 CLAUDE.md/AGENTS.md/src/<module>/docs/registries/*.yaml 를 읽어 명세를 실제 구현·계약에 정합시킨다(ground-truth repo 기억 참조). actually-implemented 주장은 src/ grep 으로만 확정.

작업 절차

1. 전제 확인

   • slug 가 비면 slug 를 요청(종료 — 대상 파일을 모름). 목표 prose 가 비면 종료하지 말고 AskUserQuestion 으로 목표를 물어 답을 받아 진행(되묻고 종료가 아니라 묻고 이어감).
   • slug 노트가 없으면 채우지 말고 /project <slug> 먼저 실행하도록 안내(종료). 채움은 본 명령, 생성은 /project.
   • 노트의 §1 개요가 비고 목표도 못 받으면 NEEDS_CONTEXT 로 표기하고 그 부분만 보류한 채 가능한 범위 진행.

2. 프로젝트 ground truth 확인 (읽기 전용) — 대상 repo 코드/기존 raw/관련 노트를 읽어 현황 파악. 코드 미확인 항목은 documented-only/planned 로 표기. 레포 부재 시 NO_GROUND_TRUTH 라벨 + 한계 보고.

3. 문제정의·성공기준 구체화 (R1)

   • 추상 표현 거부. 구체 시나리오·수치로.
   • ★ 명확화 질문 — 정해야 하는데 근거·기본값이 없는 사용자 소유 결정(프로젝트 범위/우선순위/성공기준 임계)은 추측·UNSUPPORTED 라벨 대신 AskUserQuestion 으로 직접 묻는다. (branch-spec 과의 차이: hub 는 사용자 in-the-loop.)

4. 아키텍처 + 시퀀스 (R2)

   • 핵심 user flow 의 Mermaid 시퀀스를 자동 작성(happy + error path, autonumber).
   • 아키텍처 .drawio 는 자동생성 불가 → §3.1 에 needs-diagram 표시를 남기고 사용자가 작성/요청하도록 안내. 임베드 경로는 백틱 코드로 표기(예: `![[raw/diagrams/<slug>/architecture-overview-YYYY-MM-DD.drawio.svg]]`) — 미작성 파일을 활성 임베드로 두면 9a 린터가 BROKEN_LINK 로 잡으므로, 백틱 코드 placeholder 로 비활성화(린터의 inline code-span 면제 활용). 사용자가 실제 파일 작성 후 백틱을 풀어 활성 임베드로 바꾼다.
   • 다이어그램 품질(≥95)은 게이트가 판정하지 못한다 — 사용자가 wiki-diagram-reviewer 를 별도로 실행해 확인(R2 ≥95 는 권고 단계, Ready 조건 아님). 게이트는 존재 + error-path 시퀀스만 본다.

5. 기술결정 소싱 (R3) — hub 레벨

   • 주요 기술결정마다 §6 표에 검토한 대안 을 적고, 채택 근거를 wiki-source-summarizer dispatch 로 외부자료(official/대기업 블로그) raw 화 → 근거 자료 칸에 [[raw/...]] 링크. (parent = [[raw/project-notes/<slug>]] — summarizer 는 project parent 를 받는다.)
   • wiki-decision-researcher 는 여기서 dispatch 하지 않는다 — 그 agent 의 입력 계약은 parent_branch(branch-note) 필수다. 결정별 깊은 대안 비교/조사는 hub 가 아니라 branch 단계(/branch-spec)로 미룬다(hub→branch 핸드오프). hub 는 프로젝트 차원 stack 결정의 근거 소싱까지만.
   • 덮어쓰기 가드: §6 행의 근거 자료 칸이 이미 채워져 있으면 그 행은 소싱 dispatch 하지 않고 기존 링크 보존(C#6).
   • bound: 회당 최대 6개 결정. 초과분은 채우지 말고 deferred 로 §6 행에 명시 표기(silent 절단 금지). deferred 행은 R3 Blocking 면제(Advisory) — auditor 가 인식하도록 행에 deferred 토큰을 남긴다.
   • 조사 후에도 근거 없으면 UNSUPPORTED_DECISION 라벨 + trade-off 한 줄.

6. Branch 분해표 (R4 — 핸드오프)

   • §8.0 표에 {branch slug(naming-conventions) | 측정가능 목표조건 | 우선순위 | 의존}만 채운다. 결정 내용·메커니즘은 적지 않음(SSOT 이중화 방지). 이 표가 /branch·/branch-spec 입력.

7. 프로젝트 레벨 고정 결정 — Stack commitment / SSOT owner 등 branch 간 충돌 방지 결정(내용은 프로젝트별). 해당 없으면 명시.

8. 검증등급 + 면접·외부공개 경계 — project-template §9·§10 채움. 코드 확인 기준 등급(actually-implemented/locally-verified/...).

9. 자동 게이트 — readiness (맨 끝, 내부 단계)

   • (9-coverage) 관심사 누락 점검 (depth 의 짝, 경량) — §2 ground truth 에서 식별한 프로젝트 관심사 목록(예: security / async / multi-tenancy / data-retention)과 §6·§7·§8.0 의 커버리지를 대조. 빠진 domain 은 §8.0 분해표의 deferred branch 또는 §7 에 명시적으로 표기(silent 누락 금지). (full coverage-auditor 포트는 v2 — 여기선 수동 대조.)
   • (9a) 1차 결정론 — python3 .claude/hooks/wiki_structure_lint.py --file raw/project-notes/<slug>.md (repo-루트 상대경로로 호출). proxy(PROJECT_NO_DIAGRAM/PROJECT_NO_BRANCH_TABLE)·frontmatter·링크 확인.
   • (9b) 2차 의미 — 통과 시 project-readiness-auditor dispatch(노트 경로 전달). R1~R4 판정.
   • (9c) 루프백 (천장 2회 + 사용자행동 탈출) — Not-ready(Blocking)면 → §3~§8 로 되돌아가 자동으로 채울 수 있는 Blocking(근거 보강·시퀀스 error path 등)을 보강 → 9a·9b 재실행. 루프 천장 2회. 단 사용자 행동으로만 해소되는 Blocking(DIAGRAM_PENDING_USER 아키텍처 작성 / 사용자 소유 결정 미입력)은 자동 루프 대상 아님 — 판정을 Ready-pending-user 로 내고 어떤 사용자 행동이 무엇을 unblock 하는지 보고한 뒤 step 10 으로 깨끗이 종료(무한루프 금지, rules/project-readiness-gate.md 판정 규칙 참조).

10. 요약 보고 (짧게, 상세는 노트에)

    • 사람이 5초에 읽을 요약만: 채운 결정 N / UNSUPPORTED K / 조사 M / deferred D' / branch 분해 B / needs-diagram D / 누락 domain X / readiness: Ready|Ready-pending-user|Not-ready (Blocking 축 인용).
    • Ready-pending-user 면 사용자가 할 행동을 한 줄씩(예: "① 아키텍처 .drawio 작성 후 백틱 해제 → wiki-diagram-reviewer ≥95").
    • 통과 못하면 무엇을 더 채워야 하는지 한 줄씩(축·finding 인용).

규칙

• 추측해서 FACT 로 채우지 않는다. 근거 없으면 자동조사 → 실패 시 UNSUPPORTED_* 라벨. 단 사용자 소유 결정은 라벨 대신 AskUserQuestion.
• actually-implemented 는 src/ grep 으로만 확정. note→note 자기보고 전이 금지.
• 기존 사용자 작성 본문 보존 — 채움은 빈 셀/skeleton 에만.
• 자동조사 bounded — §5 의 6개 한도. 초과는 deferred 명시(R3 면제).
• 새 agent 를 만들지 않는다. 본 명령이 직접 dispatch 하는 것은 wiki-source-summarizer(§5 hub 소싱) 와 project-readiness-auditor(§9 게이트) 둘뿐. wiki-diagram-reviewer(≥95)는 사용자가 별도 실행하고 본 명령은 안 부른다. wiki-decision-researcher(결정별 깊은 대안조사)는 parent_branch 계약상 branch 단계로 이관(여기서 안 부름). wiki-doc-author(노트 생성/마이그레이션)는 /project 의 일.
• 검증은 readiness 게이트에 위임 — 본 명령은 채움에 집중. 4축 판정 로직을 중복 구현하지 않는다.
• wiki/log.md 기록 안 함 (/branch·/depth 와 동일).