Builder Harness Manager
Builder `/harnesses`에서 draft harness를 만들고 preview, review, approval, activation까지 다루는 실제 사용 흐름을 정리합니다.
reopt designUpdated
1. 이 문서의 범위
이 문서는 `opt-shell` 개념 설명이 아니라 Builder 안에서 하네스를 실제로 운영하는 방법을 다룹니다. `/builder/harnesses`를 기준으로 draft 생성, policy 편집, preview 비교, review note 작성, approval, activation, archive까지 한 흐름으로 정리합니다.
개념과 경계는 Mission, rollout 의미는 Builder Rollout에 있고, 이 문서는 그 위에서 실제 사용자 작업 순서를 설명합니다.
2. 실제 화면으로 먼저 보기
아래 화면이 Builder Harness Manager의 핵심 surface입니다. 문서를 다 읽기 전에 이 세 화면만 보면 `목록에서 초안 관리`, `Preview에서 비교`, `Review에서 승인 후 activate`라는 흐름을 바로 이해할 수 있습니다.
Harness list
워크스페이스 아래 여러 harness를 나란히 보고, active draft와 review 상태를 한 화면에서 관리합니다.
Preview compare
`Workspace Live`와 `Demo Fixtures`를 오가며 candidate와 active 결과를 비교합니다.
Review gate
승인되지 않은 draft는 runtime으로 올리지 않고, review note와 readiness를 먼저 확인합니다.
3. 기본 사용 흐름
| 단계 | 경로 | 무엇을 하나 |
|---|---|---|
| 1. Draft 생성 | /builder/harnesses | `New Harness`로 blank draft를 만들거나 `Duplicate Active`로 현재 active harness를 복제해 시작합니다. |
| 2. Policy 편집 | /builder/harnesses/[harnessId] | Policy 탭에서 density, content width, motion, state labels, adapter chrome을 조정합니다. |
| 3. Recipe 설정 | /builder/harnesses/[harnessId] | Recipes 탭에서 dashboard, list, detail, editor, landing, fullscreen tool의 slot behavior를 조정합니다. |
| 4. Preview 비교 | /builder/harnesses/[harnessId] | Preview 탭에서 candidate vs active를 비교하고, `Workspace Live`와 `Demo Fixtures`를 오가며 실제 적용 느낌을 확인합니다. |
| 5. DESIGN.md 확인 | /builder/harnesses/[harnessId] | `Design Contract` 탭에서 repo `DESIGN.md` 요약, alignment score, candidate vs active visual diff를 함께 읽고 시각 계약을 벗어나지 않는지 먼저 확인합니다. |
| 6. Design proof 캡처 | /builder/harnesses/[harnessId] | Preview 탭에서 `Demo Fixtures` 또는 `Workspace Live`를 기준으로 candidate vs active를 확인한 뒤, 현재 저장된 draft 기준으로 fresh proof를 캡처합니다. |
| 7. Review 요청 | /builder/harnesses/[harnessId] | Review 탭에서 note를 남기고 `Request Review`를 눌러 draft를 검토 대상으로 올립니다. |
| 8. Approve 후 Activate | /builder/harnesses/[harnessId] | `Approve Draft` 이후에도 Review 탭의 design alignment와 fresh proof readiness가 닫혀 있으면 activate할 수 없습니다. 승인, DESIGN.md guardrail, PASS proof를 모두 통과해야 runtime으로 올릴 수 있습니다. |
| 9. Activity 확인 | /builder/harnesses/[harnessId] | Activity 탭에서 actor, role, target, review note, activation evidence뿐 아니라 append-only timeline과 derived learnings까지 함께 확인합니다. |
4. 각 탭을 언제 쓰는가
Overview
이 harness가 무엇을 위한 draft인지 이름과 설명을 정리할 때
Policy
density, width, motion, state label, adapter chrome을 조정할 때
Recipes
workspace recipe별 toolbar, filters, aside, footer 조합을 조정할 때
Design Contract
repo DESIGN.md 핵심 섹션, alignment score, candidate vs active visual diff를 같이 읽고 시안 방향을 점검할 때
Review
compare summary와 design alignment / design proof readiness를 읽고 review note, approval, change request를 남길 때
Preview
candidate와 active를 demo fixture 또는 workspace live data로 비교하고 fresh proof를 캡처할 때
Activity
누가 무엇을 바꿨고 어떤 상태 전이가 있었는지 audit evidence, searchable timeline/learnings, exportable intelligence snapshot을 함께 볼 때
5. review와 activation 규칙
Builder Harness Manager의 핵심은 `preview가 된다`가 아니라 `review gate가 있다`입니다. draft는 저장 후 review 대상으로 올라가고, note와 actor evidence를 남긴 뒤, APPROVED 상태가 되어야만 `Activate Reviewed Draft` 버튼이 실제 운영 정책 승격 경로가 됩니다.
- Save before review: Preview proof와 review request는 저장된 draft definition을 기준으로만 평가합니다.
- Meaningful diff required: active baseline과 의미 있는 차이가 없으면 review request와 approval이 409로 막힙니다.
- Edits reset review: review 이후 저장된 수정이 생기면 status는 다시 DRAFT로 내려가고 audit evidence가 남습니다.
- APPROVED required: activate는 APPROVED draft만 통과시키며, active runtime 반영 전 review state를 다시 확인합니다.
- Design alignment required: alignment score가 review 상태면 APPROVED여도 activate가 409 design_review_required로 막힙니다.
- Fresh design proof required: Preview에서 현재 draft hash와 일치하는 PASS proof를 다시 캡처해야 activate readiness가 닫힙니다.
6. design proof 루프
Preview proof는 screenshot 한 장이 아니라 현재 저장된 draft와 연결된 운영 evidence입니다. proof가 없거나 draft 수정 이후 stale이면 activation route가 서버에서 막히므로, 아래 순서를 review loop 안에 포함해야 합니다.
Save the current draft
proof는 unsaved local state가 아니라 저장된 candidate definition hash를 기준으로 생성됩니다.
Preview against a real context
Demo Fixtures 또는 Workspace Live에서 candidate와 active를 나란히 보고 route-specific evidence를 수집합니다.
Capture proof
saved proof는 fixture, source mode, required slots, DOM summary, alignment snapshot을 append-only audit에 남깁니다.
Re-capture after edits
draft definition이 바뀌면 기존 proof는 stale이 되며 activate는 409 design_proof_stale로 막힙니다.
Activate only with PASS proof
APPROVED, alignment pass, fresh PASS proof가 모두 닫혀야 activate가 최종 runtime 승격을 허용합니다.
7. 자주 하는 작업
현재 active를 기준으로 새 변형을 만들고 싶다
`Duplicate Active`로 복제한 뒤, Policy와 Recipes를 조정하고 review를 거쳐 activate합니다.
실제 프로젝트에 어떻게 보일지 먼저 보고 싶다
Preview 탭에서 `Workspace Live`를 선택하고 프로젝트를 고른 뒤 candidate vs active를 비교합니다.
현재 draft가 DESIGN.md 방향과 맞는지 보고 싶다
`Design Contract` 탭에서 repo `DESIGN.md` 요약, Candidate / Active alignment score, visual diff summary를 같이 보면 됩니다.
왜 activate가 안 되는지 알고 싶다
Review 탭에서 approval 상태와 `Design contract aligned`, `Design proof fresh` readiness를 함께 확인하세요. 저장되지 않았거나, meaningful diff가 없거나, review가 APPROVED가 아니거나, alignment가 review 상태이거나, latest proof가 없거나 stale이면 activation readiness가 닫혀 있습니다.
누가 승인했고 어떤 note를 남겼는지 보고 싶다
Review 탭의 latest review context와 Activity 탭의 audit evidence를 같이 보면 됩니다.
8. 권장 운영 루프
가장 안전한 루프는 이렇습니다. active harness를 직접 만지지 말고, duplicate로 새 draft를 만든 뒤, policy와 recipe를 조정하고, preview로 active baseline과 차이를 확인하고, fresh proof를 캡처하고, review note를 남겨 approval을 받은 다음 activate합니다. 이 루프가 있어야 harness가 개인 취향이 아니라 팀이 공유하는 제품 정책으로 남습니다.
Duplicate Active 또는 New Harness로 draft를 시작한다.
Policy와 Recipes를 조정해 candidate definition을 만든다.
Preview에서 active baseline과 실제 적용 차이를 읽고 fresh PASS proof를 캡처한다.
Review note를 남기고 approval을 받아 gate를 통과한다.
Activate Reviewed Draft로 workspace runtime에 승격한다.
Activity에서 actor, note, activation evidence를 추적한다.