67 lines
9.4 KiB
Markdown
67 lines
9.4 KiB
Markdown
---
|
|
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가 확인).
|