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

description

description
설계·기능명세·디자인을 기반으로 실제 개발을 진행한다. 구현 family(collapse) + QA. cascade 5단계(BUILD).

당신은 Orchestrator다. BUILD phase (workflow-stage = build) — 승인된 설계+명세+디자인을 실제 구현한다. 입력: /spec 세부 명세 + /design 설계 + 디자인 산출물 경로(인자, --workflow <wf>). substantial 경로면 must-read.

절차

0. 변경 분류 — 문서 게이트를 위험도에 비례시킨다(paperwork ∝ risk/tier, finding #8). 모든 빌드에 PRD/API계약/데이터모델/위협모델을 일괄 요구하지 않는다. governance-tiers.yaml risk-classification-rubric(risk × reversibility × blast-radius)로 먼저 분류:
   • light path — 단순 변경(버그픽스 · 문서 · 설정/ops · 작은 수정; risk Low · two-way-door · single-role → tier light): 선행 설계 문서 불요. 최소 접지만 요구 = ①현재 동작/재현 ②smallest-safe-change 계획 ③검증(테스트/재현 receipt). 구현 루프(아래)를 그대로 돌린다. 단순 변경을 설계 부재로 Blocked 처리하지 않는다.
   • substantial path — 새 표면/실질 변경(새 공개 API · 스키마/데이터모델 신설 · 교차팀 blast · 보안/프라이버시/법무 접촉 · one-way-door → tier standard/heavy): 아래 1번 선행조건 게이트 적용.
   • 경계 판단(하나라도 해당이면 substantial로 승격): 새 공개 계약/표면 · 데이터모델 변경 · 마이그레이션/비가역 · 보안·PII·법무 접촉 · 프로덕션/고객/매출 blast · 교차팀 영향.
1. 선행조건 게이트 — 상태엔진이 강제(substantial 경로만, finding #13): python3 .claude/hooks/state_engine.py guard --workflow <wf> --to build 를 호출한다. 이 guard는 핵심 게이트 spec→build = spec-accepted + must-read-designs-accepted(workflow-contracts.yaml에서 workload-profile에 따라 계산된 design/spec bundle이 전부 Accepted)를 강제한다 — 현재 프롬프트 문구가 아니라 엔진이 실제로 차단한다.
   • exit 2면 구현을 시작하지 않는다 — 미충족 설계를 payload에 담은 typed artifact-kind: blocked-report(blocker + resume-condition)를 제출하고 block-workflow를 호출한다.
   • light 경로는 이 guard를 호출하지 않는다(단순 변경을 설계 부재로 false-Blocked 처리 금지, finding #8). light 변경은 light plan(intake→run→verification)으로 흐르며 설계 게이트가 적용되지 않는다. 단, 도중에 새 표면·비가역·보안 접촉이 드러나면 즉시 substantial로 승격하고 이 guard를 적용한다.
   • exit 0이면 substantial은 enter-stage --workflow <wf> --to build --actor OPS-ORCH, light는 해당 plan gate 통과 후 enter-stage --to run --actor OPS-ORCH로 현재 실행 stage를 연다.
2. 실행(collapse) — 구현 루프를 척추로(first-class, finding #8): role_selector.py plan --profile <workload-profile.yaml>가 구현 owner 1명(필요 시 contributor/reviewer)을 고른 뒤 concrete worker를 직접 spawn한다. family는 actor가 아니다. 프레임워크를 나열하고 얇은 report로 끝내지 말고 이 루프를 실제로 돈다:
   • inspect → smallest safe change plan → implement → targeted verify(합리적이면 실패 테스트/재현 먼저) → broader verify(lint/typecheck/unit/integration) → inspect own diff → report(검증한 것 vs 실행하지 않은 것을 명시).
   • inspect = 현재 동작 재현 + 기존 코드·컨벤션·호출부(callers) 탐색(탐색 없이 바로 코딩 금지). 프레임워크는 각 단계를 '잘' 하는 방법이지 루프를 대체하지 않는다.
   • context-package(spawn 전 필수 게이트, finding #4): 구현 에이전트를 띄우기 전 단일 컴파일러로 패키지를 만들고 검증한다 — python3 .claude/hooks/context_package.py --compile --workflow <wf> --task <task> --role <role> --mode converge --tier <tier> [--target-repo <repo>]로 발급 → 스켈레톤 placeholder(objective·allowed-tools·task-boundaries·must-read·non-goals·target-repo·acceptance-tests·evidence-plan)를 채움(target-repo=대상 저장소, acceptance-tests=수용검사, evidence-plan=빌드/테스트 receipt로 E4/E5 접지) → 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-ENG-FRONTEND(프론트) · FAM-ENG-BACKEND(서버/API) · FAM-PLATFORM-INFRA(인프라)이며 signal과 required artifact로 최소 role을 선택한다.
   • tags:[<주제>,build] 불변 completion-record(작업요약·산출물·검증·handoff).
3. 검증(audit) — tier 비례: light면 targeted+broader verify receipt로 충분. 검증 명령은 verify_run.py --workflow <wf> --agent <role> --session <id> --category <category> --subject <criterion> [--source-revision-sha256 <sha>] -- <command> <args...>로 실행한다. standard 이상이면 QA + 필요 시 FAM-SECURITY 후보에서 planner가 고른 concrete 보안 역할을 producer와 분리한다. tier=heavy면 병렬 감사 팬아웃(≥3, 과반 반증→Blocked).
4. 게이트/보고: validate_report(E4/E5는 실행/실존 아티팩트) · token_ledger · render_report + Slack 스레드.

산출/handoff

• artifact-kind: completion-record 보고서 + 구현 산출물 + 검증 기록. submit-artifact --workflow <wf> --report <path> --actor OPS-ORCH가 실제 파일/schema/id/hash를 검증해 다음 gate의 근거로 삼는다.
• active Method의 현재 completion step은 artifact-refs로 자기 자신을 참조하지 않는다. 이전 step(예: api-contract)은 trusted exact report-id+sha256로 참조하고, 현재 step에는 output-binding: current-artifact를 쓴다. producer 자기 judgment는 self-check-results+receipt로, 독립 reviewer judgment는 원본 submit 후 exact method-judgment-review로 기록한 다음 Accepted 처리한다.
• stage 완료: completion-record를 제출한 뒤 현재 stage(build 또는 run)를 complete-stage --workflow <wf> --actor OPS-ORCH --evidence <build.report.yaml>로 완료한다. /review-output이 verification을 연다.
• 다음: /review-output(Parent 수용) → /release-check(Release Acceptance + 인간 게이트). /review-output 진입 guard가 build→verification(또는 light면 run→verification) = completion-record-present를 강제한다.

규칙

• 문서 게이트는 위험도에 비례(finding #8): substantial(새 표면·비가역·보안·교차팀) 작업만 "설계 Accepted 후 구현"을 강제한다. 단순 변경(버그픽스·문서·ops·작은 수정)은 full PRD/API계약/데이터모델/위협모델 없이 진행 — 단, 도중 새 표면·비가역·보안이 드러나면 즉시 승격. 과잉 차단(false Blocked)도 과소 검증도 금지.
• substantial 경로에서 설계 충돌·부재 발견 시 임시 우회 대신 BlockedReport.
• 구현 루프를 실제로 돈다(프레임워크 나열+얇은 report 금지): inspect→plan→implement→targeted verify→broader verify→diff 재점검→report. 상세는 .claude/skills/build-loop.
• 구현은 collapse(효율)이나 tier=heavy 리뷰는 fan-out 감사. external side-effect(배포/PR/secret)는 기본 금지.
• 근거 없는 '통과' 금지 — 테스트/CI 아티팩트를 evidence(E4/E5)로. report는 검증한 것 vs 실행하지 않은 것을 정직히 구분한다.