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

description

description
승인된 결정에 대한 설계를 호출한다. 아키텍처/데이터/디자인/보안 설계 직무 fan-out → 큰 설계문서. cascade 3단계(DESIGN).

당신은 Orchestrator다. DESIGN phase (workflow-stage = design) — 수렴된 결정을 실제 설계로 전개한다. 입력: /decide 산출 ExecutiveDecisionPacket(인자, --workflow <wf>) + (있으면) /ground grounding-evidence. must-read. 승인 안 된 결정으로 설계 시작 금지.

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

1. guard(진입 게이트): python3 .claude/hooks/state_engine.py guard --workflow <wf> --to design.
   • 이 게이트는 decide→design의 선행조건 = decision-packet-accepted(review-state Accepted) + evidence-grade-min(tier) 을 강제한다. exit 2면 진행하지 않는다 — 승인 안 된 결정/증거등급 미달이면 /decide(및 Parent 수용)로 되돌리는 BlockedReport(미충족 사유). exit 0이면 진행.
   • exit 0이면 state_engine.py enter-stage --workflow <wf> --to design --actor OPS-ORCH로 design.running을 연다.

experience-foundation 선행 게이트(공개 웹·신규 제품·대규모 리디자인)

typed workload가 surface-archetype: public-website 또는 experience-change: new-product|major-redesign인 UI 작업이면 visual direction보다 먼저 /experience-foundation을 완주한다.

1. state_engine.py find-child-experience --parent-workflow <wf> --product-decision <PD>로 dedup한다.
2. 없으면 /experience-foundation --parent-workflow <wf> --product-decision <PD>를 실행하고, 있으면 현재 stage부터 재개한다.
3. state_engine.py check-experience-foundation --workflow <wf>가 YES가 될 때까지 direction-input-brief 작성과 /design-direction init을 시작하지 않는다. 엔진도 design-direction init/intake와 design→spec에서 다시 강제한다.
4. direction-input-brief는 accepted benchmark/blueprint/wireframe exact ref+SHA를 포함한다. 이 IA·콘텐츠·screen contract는 이후 3개 시각 방향에서 동일하다.

design-direction 선행 게이트(UI-bearing standard/heavy, Task 13 — Blocker 10: /design-system 직행 우회 차단)

DESIGN stage 진입 직후 intake의 typed workload-profile.surfaces.ui를 확인한다. 이것만이 UI-bearing의 정본이며 deliverable-kind나 build-family fallback은 없다. UI=true이고 tier가 standard/heavy면 승인된 design-direction 없이 /spec으로 갈 수 없다.

1. dedup 조회(중복 cycle 금지): product-decision report-id <PD>(/decide가 accepted한 것)와 direction-input-brief 경로·sha256을 정하고, python3 .claude/hooks/state_engine.py find-child-direction --parent-workflow <wf> --product-decision <PD> --direction-input-brief-sha256 <sha>로 조회한다(JSON 또는 null stdout, 항상 exit 0):
   • null(없음) → 신규: experience-foundation 게이트를 확인한 뒤 새 child workflow-id로 /design-direction --parent-workflow <wf> --product-decision <PD> --direction-input-brief <path>를 spawn한다.
   • 있고 stage != design-direction-approved이며 stale=false → running: 같은 child workflow-id로 /design-direction을 resume(처음부터 다시 밟지 않는다).
   • 있고 stage == design-direction-approved이며 stale=false → approved 재사용: 이미 승인된 방향이 있다. 새로 발산하지 않고(멱등) 바로 다음(3b/스펙)으로 진행한다.
   • 있고 stale=true(그 사이 brief가 바뀜) → 기존 child는 건드리지 않는다(불변 이력 보존). 새 child workflow-id로 신규 cycle을 연다.
2. child가 design-direction-approved에 도달할 때까지 — check-direction-approved --workflow <wf>가 YES를 반환할 때까지 — 부모의 design complete-stage가 design-direction-gate-satisfied 미충족으로 차단된다.

절차

2. pre-work: 승인된 Packet + (있으면) ground grounding-evidence + slack_inbox.py + report_tags.py를 must-read. 공유 제약(scope/non-goals/glossary)을 shared-constraints로 동봉(발산 충돌 방지).
3. minimum-sufficient fan-out(divergent): role_selector.py plan --profile <workload-profile.yaml>로 owner/contributor/independent reviewer를 계산하고 선택된 concrete role만 spawn한다. family는 candidate metadata이며 card/actor가 아니다.
   • 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 문맥(승인 packet·ground evidence·shared-constraints 포함)으로 채움 → python3 .claude/hooks/context_package.py <pkg>가 exit 0일 때만 spawn한다. 출력된 context-package:/context-package-sha256:를 spawn 프롬프트에 포함하고 package의 model/effort를 그대로 사용한다. FAM-DESIGN 후보에서 선택된 디자인 role과 DOC-VISUAL은 design-brief도 채운다.
   • 후보 family: FAM-ARCHITECTURE-TECH(RFC/ADR·서비스 경계) · FAM-DESIGN(UX/UI·디자인시스템) · FAM-DATA(데이터) · FAM-SECURITY(위협모델). planner가 필요한 최소 role만 고른다.
   • 각자 자기 설계 산출물 → tags:[<주제>,design] 불변 보고서 → 경로+BLUF. 3b. UI-bearing 분기 — 디자인 파이프라인을 DESIGN에 통합(조건부). workload-profile.payload.surfaces.ui == true일 때만 코드 디자인 시스템 서브파이프라인을 돈다. family 선택 결과로 UI 여부를 다시 추론하지 않는다. /design-system 절차: ①승인된 experience blueprint/wireframes 확인 → ②조직 design release exact attach → ③프로젝트 discovery → ④reuse/adapt/create 판단 → ⑤design-brief → ⑥tokens/components/screens → ⑦ preview_ui 품질 gate.
   • 산출물을 artifact-kind: ui-design 또는 approved-design-direction으로 발급해 submit-artifact한다. ui-design은 product-quality-auditor, 전체 아키텍처는 architecture-auditor, API 설계는 technical-accuracy-auditor, 위협모델은 security-auditor가 exact revision을 리뷰한다.
   • 게이팅 불변식(엔진 강제): /design-system 파이프라인이 제출한 canonical artifact-kind: ui-design은 acceptance_log에 accepted여도 evidence-ledger에 통과한 preview_ui receipt(exit 0, --contrast-only 단독 아님)가 있어야 spec→build의 must-read-designs-accepted를 충족한다 — 렌더된 적 없는 산문만으로 프론트 BUILD를 여는 것을 state_engine이 차단한다. preview_ui를 실제로 돌려 receipt를 남겨라.
   • non-UI 워크플로(workload-profile.payload.surfaces.ui == false)는 ui-design을 요구하지 않는다(과설계 금지). UX/화면이 없으면 이 분기를 건너뛴다.
4. 종합(큰 설계문서): ARCH-SOLUTION이 structured projection을 먼저 읽고, standard에서는 충돌·dissent·저신뢰만 원문 확장하며 heavy에서는 전 원문을 읽어 overall-design을 작성한다. source-artifact-refs는 exact id+sha256을 담고 conflicts를 보존한다.
5. 게이트/보고: validate_report·token_ledger·render_report + Slack 스레드.

산출/handoff

• 각 산출물은 contract의 artifact-kind(overall-design, 조건부 api-design|data-model|threat-model|ui-design|approved-design-direction)로 각각 submit/review한다. 모든 payload는 승인된 최신 ExecutiveDecisionPacket의 basis-artifact-id와 basis-artifact-sha256을 동일하게 담는다. design-accepted는 required bundle 전체가 latest effective Accepted이고 같은 decision revision에 결속될 때만 참이다. 동시에 필요한 계약 쌍(overall-design↔api-design|data-model|threat-model, approved-design-direction↔ui-design)은 별도 reviewer가 양쪽 exact id+sha와 계약 dimensions를 담은 compatibility-review(verdict: Passed)를 제출해야 번들 승인이 성립한다.
• stage 완료: workload-profile에서 계산한 required design bundle 전체가 exact revision으로 Accepted된 뒤 complete-stage --workflow <wf> --actor OPS-ORCH --evidence <design.report.yaml>를 실행한다. 설계 판단자와 stage 집행자를 분리한다.
• 다음: /spec(설계 기반 세부 기능 명세). /spec 진입 guard가 design→spec(design-accepted + UI-bearing standard/heavy면 design-direction-gate-satisfied)을 강제한다 — 위 design-direction 선행 게이트를 통과하지 못했으면 여기서 다시 막힌다.

규칙

• 설계는 하나로 억지 병합하지 않는다 — 조금씩 달라도 상위가 원본 읽고 종합(synthesis-rehydration).
• workflow-contracts.yaml의 workload-profile 조건부 design/spec bundle을 갖춘다(다음 BUILD의 선행조건이며 엔진의 must-read-designs-accepted 게이트가 이를 강제한다). UI-bearing이면 ui-design이 포함되며 실제 preview_ui 렌더 receipt가 필수다 — 스크린샷 존재 ≠ 품질, 산문 ≠ UI 설계.
• 결정/구현은 공식 문서·표준·1차 자료 근거(WebFetch/WebSearch/context7).
• mid-start: 설계가 이미 Accepted면 /spec부터 시작 가능(engine guard가 확인).