company-haness/.claude/commands/spec.md

description

description
설계를 기반으로 개발용 기능 명세를 만든다. PM/아키텍트 fan-out → PRD·api-contract·수용기준. cascade 4단계(DETAIL/SPEC).

당신은 Orchestrator다. DETAIL/SPEC phase (workflow-stage = spec) — 설계를 구현 가능한 기능 명세로 세분화한다. 입력: /design overall-design + 도메인 설계 산출물 경로(인자, --workflow <wf>). must-read.

상태엔진 게이트(진입) — design→spec 선행조건 강제

0. guard(진입 게이트): python3 .claude/hooks/state_engine.py guard --workflow <wf> --to spec.
   • 이 게이트는 design→spec의 선행조건 = design-accepted(설계 산출물 review-state=Accepted) 를 강제한다. exit 2면 진행하지 않는다 — 설계 미승인이면 /design(및 Parent 수용)으로 되돌리는 BlockedReport(미충족 사유). exit 0이면 진행.
   • exit 0이면 state_engine.py enter-stage --workflow <wf> --to spec --actor OPS-ORCH로 spec.running을 연다.

절차

1. pre-work: 설계 산출물(RFC/ADR·data-model·UX·threat-model) + slack_inbox.py + report_tags.py를 must-read.
2. minimum-sufficient fan-out(divergent): family는 candidate metadata이며 role_selector.py plan --profile <workload-profile.yaml>가 artifact coverage와 독립 리뷰를 만족하는 concrete role만 고른다.
   • context-package(spawn 전 필수 게이트, finding #4): 각 워커를 띄우기 전 단일 컴파일러로 패키지를 만들고 검증한다 — python3 .claude/hooks/context_package.py --compile --workflow <wf> --task <task> --role <role> --mode divergent --tier <tier> [--lens <LENS>] [--target-repo <repo>]로 발급 → 스켈레톤 placeholder(objective·allowed-tools·task-boundaries·must-read·non-goals·target-repo·acceptance-tests·evidence-plan)를 이 phase 문맥으로 채움(acceptance-tests에 이 컴포넌트의 Given/When/Then 수용기준을 접지) → python3 .claude/hooks/context_package.py <pkg>가 exit 0일 때만 spawn(누락/빈 필드/위장 placeholder면 금지 — finding P0-2). 검증 통과 시 stdout으로 출력되는 context-package:/context-package-sha256: 2줄을 각 워커 spawn 프롬프트 최상단에 그대로 포함하라 — guard_tools 의 Agent/Task spawn gate 가 참조(파일 실존·해시 일치·validate 재통과)를 강제하므로 참조 없이/위장 패키지로 spawn 하면 exit 2 차단된다. spawn 시 Agent/Task 도구의 model/effort 인자는 그 워커 context-package 의 model/effort(tier 파생, finding #17)를 그대로 넘긴다 — heavy tier 는 opus/high 로 추론 강도를 올린다. 필드 정의·규칙은 org-os/06-agent-work/context-package-spec.yaml. objective/boundaries 즉석 추론 금지.
   • 후보 family는 FAM-PRODUCT-MGMT(PRD·수용기준)와 FAM-ARCHITECTURE-TECH(api-contract·인터페이스)이며 전원 호출하지 않는다.
   • 각자 컴포넌트별 세부 명세 → tags:[<주제>,spec] 불변 보고서 → 경로+BLUF.
3. 종합(세부 구현문서): PM/아키텍트 lead가 projection-first로 읽고 충돌·dissent·저신뢰만 원문 확장해 통합한다(heavy는 전 원문). conflicts 필수.
4. 게이트/보고: validate_report·token_ledger·render_report + Slack 스레드.

산출/handoff

• 각 명세는 contract의 artifact-kind(acceptance-criteria, 조건부 prd|api-contract|data-contract|migration-plan)로 submit/review한다. 모든 payload는 승인된 최신 overall-design의 basis-artifact-id와 basis-artifact-sha256을 동일하게 담는다. spec-accepted는 required bundle 전체가 latest effective Accepted이고 같은 design revision에 결속될 때만 참이다. PRD는 product-quality-auditor, API 계약은 technical-accuracy-auditor, data/migration 계약은 data-quality-auditor가 리뷰한다. 동시에 필요한 prd↔api-contract, data-contract↔migration-plan, api-contract↔data-contract 쌍은 exact id+sha compatibility-review(verdict: Passed)가 추가로 필요하다.
• stage 완료: required spec bundle 전체가 exact revision으로 Accepted된 뒤 state_engine.py complete-stage --workflow <wf> --actor OPS-ORCH --evidence <spec.report.yaml>를 실행한다.
• 다음: /build(설계+명세+디자인 기반 구현). /build 진입 guard가 핵심 게이트 spec→build(spec-accepted + must-read-designs-accepted)를 강제한다.

규칙

• 명세는 설계와 정합해야 한다(설계 없는 명세 금지). 각 기능은 검증가능한 수용기준(Given/When/Then)을 갖는다.
• api-contract·인터페이스는 구현 family가 그대로 소비할 계약이다 — 모호성 제거.
• mid-start: 명세가 이미 Accepted면 /build부터 시작 가능(engine guard가 must-read-designs까지 확인).