b3os-harness-playbook

b3os-harness-playbook — harness 플레이북 (트리거 우선)

harness(한 팀원이 sub agent를 병렬로 띄워 일을 나눔)는 단순작업을 제외한 기본 실행 방법이다. 단 "무조건 병렬"이 아니라 — "병렬 실소스 커버" 모양이면 limited harness가 기본, 그 외엔 솔로다. 트리거 모양을 보면 아래 레시피를 집되, Q1~Q4 중 하나라도 NO면 솔로로 간다. 실행 자체는 네이티브 Workflow/Agent 툴이 한다.

한 줄: 맞는 모양엔 자동으로 harness, 잘 쓰게 8패턴으로 검증. (옛 버전은 '켜기 전 통과' 게이트 우선이라 거의 안 쓰였다 — 이제 트리거 우선.)

---

① 트리거 — 이 모양이면 기본 harness (보면 바로 레시피)

여러 군데(서로 다른 실제 소스)를 동시에 봐야 하는 일 = 기본 harness:

• 코드 audit/다영역 점검 · 다PR 리뷰 · 마이그레이션(N곳 호출부)
• 멀티소스 리서치 · N후보 비교(모델·라이브러리·설계안)
• 로그·DB·코드 3면 교차검증 · 릴리즈 전 검증(테스트·문서·구현 분리)

솔로 유지 (harness 금지 — 노이즈·환각만 늘림):

• 전략·개념 합성 · 단발 추론 · 단일 파일 섬세 수정
• 한 사람의 긴 맥락을 따라야 하는 판단 · 단일 소스 리서치 · 요구 모호
• Q1 독립 분해, Q2 다른 실제 소스, Q3 비용 대비 이득, Q4 N·budget·verify 중 하나라도 NO인 작업

판정 한 줄: "각 조각이 서로 다른 실제 소스를 읽나?" YES → harness. NO(한 소스·개념합성·단일맥락) → 솔로가 더 정확·저렴.

---

② ready-run 레시피 (모양별 — 골라서 바로 실행)

핵심은 sub agent 수가 아니라 "각자 읽을 소스 + 반환 schema"를 먼저 박는 것. 각 레시피는 owner가 마지막에 종합·검증(⑤).

• audit: A=라우팅/엔트리 코드 · B=DB/스키마 · C=테스트/로그 → owner: dedup + 재현 + 최종 판단.
• migration: A=호출부 검색 · B=타입/스키마 영향 · C=테스트 갭 → owner: 영향범위 합성 + 순서 결정.
• N후보 비교: 후보당 1 에이전트(같은 평가 기준표) → owner: 동일 rubric으로 비교 + 추천.
• release-verify: A=회귀 테스트 · B=문서 정합 · C=구현 diff → owner: gate 통과/blocker 판정.

→ 작업 카드/지시에 명시: harness: limited|full · subagents: N · budget · scope · return-schema · verify (templates/harness-task-card.md).

---

③ 구조 — 제대로 짜는 모양 (팀원이 하네스 짤 때 필독)

하네스는 "sub agent 여러 개"가 아니라 ★역할 분리 + 오케스트레이터 + 파일 산출★이다. 아래 6가지를 지켜야 '제대로 된' 하네스다:

1. 역할별 에이전트 분리 — 에이전트 1개 = 역할 1개(찾기·검증·종합처럼). 한 에이전트에 여러 역할을 몰지 않는다. 예: deck = 설계/작성/디자인/검증 4역할, humanize = 탐지/윤문/감사/리뷰.
   • ★한 역할인지 두 역할인지 가르는 시험 4축★: 전문성(영역이 다르면 분리) · 병렬성(독립 실행 가능하면 분리) · 컨텍스트(부담이 크면 분리) · 재사용성(다른 팀에서도 쓰면 분리). 넷이 각각 겹친다/순차다/가볍다/여기서만 쓴다면 합친다.
   • ※ ④의 "각도 수가 N"이 몇 개로 나눌지를 정하고, 이 4축은 나뉘는 게 맞는지를 검사한다. 같은 축의 위아래다.
2. 에이전트 프론트매터로 정의 — 각 에이전트는 .claude/agents/<name>.md 프론트매터로 박는다: name · description(언제 이 에이전트를 부르나) · model · tools · isolation. 이게 있어야 오케스트레이터가 골라 부른다. (설계는 무인 금지 — 적대 리뷰 필수.)
   • ★읽기 전용이어야 하는 역할은 tools에서 Edit/Write를 뺀다.★ 프롬프트로 "고치지 마라"고 부탁하는 것과 도구가 아예 없는 것은 다르다. 빌트인 Explore·Plan이 그 형태다 — 단 ★Explore는 코드의 위치를 찾는 용도이지 리뷰·감사가 아니다★(리뷰에 쓰면 얕게 훑고 만다).
   • ★isolation: 'worktree'는 여럿이 동시에 파일을 고칠 때만★ 붙인다. 셋업 비용이 있어 읽기 작업에 붙이면 낭비다.
   • ★프론트매터만 적으면 '누가'만 정해진다.★ 본문에 입력/출력 프로토콜(어디서 받아 어디에 쓰나·형식) · 에러 핸들링(실패·입력 누락 시 행동) · 재호출 지침(이전 산출물이 있으면 읽고 개선)을 같이 적는다. 안 적으면 오케스트레이터는 무엇을 받을지 모르고 서브는 무엇을 낼지 모른다 — ★계약이 없으면 각자 상상한다.★
3. 스킬 분리 — 에이전트의 '어떻게'는 각자 스킬(SKILL.md)에 둔다. 에이전트=누가·언제, 스킬=어떻게. 새로 짤 땐 메타스킬 harness가 에이전트+그 에이전트용 스킬을 같이 찍어준다.
4. 오케스트레이터 분리 — 오케스트레이터는 ★일을 직접 안 한다.★ 단계 순서 + 각 단계 검증→재생성 게이트 + 종합만 맡고, 실제 일은 서브에이전트가. 예: deck-orchestrator = style-spec→outline→content→layout→render 순서 + 슬라이드별 validate→regenerate 게이트.
5. 파일로 산출 — 각 단계가 중간·최종 결과를 파일로 남긴다(스크래치패드/reports). 그래야 재개·감사·리뷰가 되고, 다음 단계가 앞 단계 ★파일을 입력으로★ 받는다. 결과가 대화창에만 있으면 하네스가 아니다.
   • ★서브의 최종 텍스트는 사람에게 하는 보고가 아니라 '반환 데이터'다.★ 정의에 반환 shape(schema)을 적고 그 사실을 명시한다. (실패 사례: 백그라운드 서브의 최종 반환이 자동으로 회수되지 않아 결과를 못 받았다. 서브가 사람에게 말하듯 답하면 상위가 파싱할 게 없다 — schema를 주거나 파일로 남겨야 한다.)
6. 역할별 모델·추론강도 (품질 우선 배분) — 에이전트마다 역할 난이도에 맞춰 모델을 준다. ★품질 최우선: 기본 일꾼 = Opus, 단순 작업만 Sonnet으로 내린다(GD 2026-07-20).★ 저가 티어는 당분간 미사용. 어려운 판정·반증·종합은 Opus + 높은 effort.
   • ★클로드: Opus(기본 일꾼·어려운 역할) / Sonnet(단순 작업: 포맷·1차 스캔·수집).★ Haiku 등 저가 티어 미사용.
   • ★codex·openclaw 등 다른 런타임은 각 급에 준하는 동급 모델을 고른다★ — 런타임마다 이름만 다르고 '기본(강)·단순(중)' 매핑은 같게. (특정 모델명 하드코딩 X, 급으로 지정.)
   • 지정=프론트매터 model 또는 Workflow agent(…, {model, effort}). 확신 없으면 세션 모델 상속(무분별 오버라이드 X). Workflow budget 하드캡이 이중 통제. → 기본은 Opus, 단순 반복만 Sonnet으로 절감.