b3os-harness-playbook

Files (6)

• SKILL.md
• decision-gate.md · references/
• model-selection.md · references/
• verify-checklist.md · references/
• harness-task-card.md · templates/
• recipes.md · templates/

SKILL.md (first lines)

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

harness(한 팀원이 sub agent를 띄워 일을 나눔)는 **단순작업을 제외한 기본 실행 방법**이다. 모양은 둘이다 — ① **역할 분리**: 중요한 프로젝트(`rules/STATE.local.md` 목록, 없거나 비면 사용자에게 나가는 제품 전부 — TEAM-OS §10)의 구현·버그 수정·리팩토링은 구현과 독립 리뷰·검증을 다른 역할이 맡는 것이 기본이고, 순차 작업이어도 독립 리뷰를 생략하지 않는다. ② **병렬 분할**: "병렬 실소스 커버" 모양이면 limited harness를 더한다. 병렬이 안 된다는 것은 ①을 건너뛸 이유가 아니다. 트리거 모양을 보면 아래 레시피를 집되, Q1~Q4 중 하나라도 NO면 병렬로 나누지 않는다(①역할 분리는 그대로 한다). 실행 자체는 네이티브 Workflow/Agent 툴이 한다.

> 한 줄: **맞는 모양엔 자동으로 harness, 잘 쓰게 8패턴으로 검증.** 켜기 전 통과 게이트가 아니라 트리거가 먼저다.

---

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

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

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

**중요한 프로젝트의 구현·버그 수정·리팩토링** = 기본 역할 분리(구현 1 + 독립 리뷰·검증 1, 다른 팀원 리뷰로 대신할 수 있다). 아래 솔로 목록은 ②병렬 분할에 대한 것이다.

**솔로 유지 (병렬 분할 금지 — 노이즈·환각만 늘림):**

- 전략·개념 합성 · 단발 추론 · **단일 파일 섬세 수정**
- 한 사람의 긴 맥락을 따라야 하는 판단 · **단일 소스 리서치** · 요구 모호
- 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. **작업별 모델·추론강도 — 일반 개발은 중간급 프론티어 모델 기본.** 모델 등급과 추론강도(effort)는 별도 축이다. 회사 간 같은 effort 이름은 동일 성능·비용을 뜻하지 않는다.
   - **단순 작업:** 확정된 규칙의 포맷 변환·파일 탐색·로그 수집·판정 없는 명령 실행. 일반 모델 + 낮은 추론(`low`)을 쓴다. 시험·실앱 검사를 돌리고 결과를 읽어 통과를 판정하는 Check 는 일반 모델 + 중간 추론(`medium`)이다. 결정적 작업은 모델보다 스크립트를 우선한다.
   - **일반 개발(기본):** 명확한 요구사항의 기능 구현·재현 가능한 버그 수정·기존 구조의 다중 파일 변경·테스트 작성·일반 리뷰. 일반 모델 + 중간 추론(`medium`)을 기본으로 한다. 일반 문서·요약도 `medium`이다.
   - **복잡·고위험:** 설계 불확실성, 동시성·데이터 정합성, 인증·권한·결제·삭제, 대규모 마이그레이션, 원인 불명 장애, 핵심 최종 검증(= 출고 묶음마다 1회 하는 아키텍처 리뷰)은 상위 모델 + 높은 추론(`xhigh`). 규모가 작아도 실패 피해가 크면 승격한다.
   - **진행 중 승격:** 동일 원인 수정의 반복 실패·증거 충돌·모듈 간 요구 충돌이면 상위 모델로 올리고 이유를 기록한다. 단순한 로그인·도구 실패는 모델 승격으로 해결하지 않는다. `max`는 근거 있는 예외이며 기본값이 아니다.
   - **품질:** 테스트·타입 검사·실제 동작 확인을 모델 등급으로 대체하지 않는다. 고위험 변경은 구현자와 독립된 리뷰를 받는다. 전체 하네스를 고가 모델로 바꾸지 말고 진단·설계·검증 역할만 승격한다.
   - **지정 방법:** 역할마다 [model-selection.md](references/model-selection.md) 표를 보고 프론트매터 `model` 또는 Workflow `agent(…, {model, effort})` 로 지정한다. 지정하지 않으면 세션 모델을 상속하므로, 상속을 고른 경우에만 비워 두고 그렇게 적는다.
   - **실행 확인:** 역할별 `task_class`, 모델 식별자, provider, 요청 effort, 실제 모델, 검증 결과를 남긴다. 모델 별칭(짧은 이름)으로 지정했으면 실제 모델 ID 를 실행 기록에서 확인한다 — 별칭이 가리키는 버전은 CLI 버전마다 다를 수 있다. 실행 도구가 작업별 모델 지정에 미지원이면 지정했다고 주장하지 않는다. 부모 모델 상속을 명시하고, 지원되는 별도 실행 경로나 담당자에게 배정한다. 공유 설정을 작업마다 바꿔 병렬 호출을 오염시키지 않는다.
   - **모델 매핑·갱신:** [model-selection.md](references/model-selection.md)를 따른다. 프론티어 출시·가격/지원 변경 시 공식 자료와 실제 개발 과제로 재평가한다. 새 이름만 보고 자동 교체하거나 구형을 무조건 저렴하다고 가정하지 않는다.

따라 짤 구조 3형 — 새 하네스는 이 셋 중 가장 가까운 걸 골라 그 모양을 베낀다.

| 형 | 구조 | 언제 쓰나 |
|---|---|---|
| 단계 파이프라인 + 단위별 게이트 | 설계 → 작성 → 조립, 그리고 단위마다 검증→재생성 | 산출물이 여러 조각이고 조각별 품질 편차를 막아야 할 때 |
| 역할 분리 다단계 | 탐지 → 처리 → 감사 → 리뷰를 각각 다른 에이전트가 | 한 에이전트가 자기 작업을 자기가 검수하면 안 될 때 |
| 팬아웃 → 수집 → 적대검증 → 종합 | 여러 각도로 동시에 찾고, 찾은 걸 반증하고, 살아남은 것만 종합 | 무엇이 있는지 모르는 탐색(감사·리서치·버그 찾기) |

※ ②는 '무엇을 나눠 돌리나'(fan-out 모양), ③은 '그걸 어떤 구조로 짜나'다.

> 주의: 따라 짤 실물 템플릿 파일은 이 저장소에 없다. 구조는 위 표가 전부다.

---

## ④ 하드 캡 + 런타임별 실행

### N 은 각도 수 로 정한다

**N 을 먼저 정하지 마라. 서로 다른 것을 시킬 각도가 몇 개인지 를 세고, 그 수가 N 이다.**

각도 = **그 에이전트에게 무엇을 찾으라고 시키는가.** 같은 대상이라도 지시가 다르면 다른 것이 나온다.

> 예: ①*"막으면 안 되는데 막는 것"* ②*"막아야 하는데 통과시키는 것"*
> ③*"이걸 켜면 지금 돌던 게 망가지나"* 는 서로 다른 각도라 서로 다른 것을 찾아온다.
>
> **같은 각도로 여럿 붙이면 배수로 비싸지고 새로 재는 것은 없다.**

**각도가 겹치면 수를 늘리지 않는다.** 각도가 3개면 3, 2개면 2다.

**단, 각도를 세되 확신이 없으면 2~3 에서 시작해 늘린다.** 각도는 머리로 세는 것이라
**처음부터 8개로 세면 8로 시작하게 된다.** 최소로 시작해 검증하며 확장하는 쪽이 먼저다.
(harness 2.1 도 *"기본 규모는 절제하고, 사용자가 '철저히·전수' 를 요청했을 때만 확장"* 이다.)

- **cap(상한)은 목표 수가 아니라 천장**이다. 각도 수가 cap 보다 적으면 **적은 쪽이 N 이다.**
- **limited harness = 보통 6 이하, 필요시 8까지.** **full harness = 12**(절대 상한 16).
  - 정책 상한은 기계와 무관하게 12 로 고정이다. `min(16, 코어−2)` 같은 코어 기반 식은 정책에 쓰지 않는다 — CPU 는 막히는 축이 아니고, 실제 천장은 **각도 수 · 토큰 예산**이다.
  - 단, 정책 N 과 런타임 동시 실행 캡은 다른 축이다. 12를 띄워도 작은 기계에선 순차로 돌아 비용은 같고 시간만 길어진다.
    Workflow 계약은 여전히 동시 실행을 `min(16, 코어−2)`로 캡한다(초과분은 큐잉) — 정책에서 CPU를 뺀 것이 런타임에서도 빠졌다는 뜻이 아니다. 작은 기계에서 큰 N을 잡으면 **시간만 늘어난다.**
  - 이 상한은 CPU 여유가 아니라 '더 늘려도 각도가 안 늘어난다' 는 경험치다.
    하네스는 대부분 **응답 대기**라 CPU 를 거의 안 쓴다.
    harness 2.1(revfactory)도 CPU 기반 상한 없이 런타임 동시성 캡 + 총 에이전트 상한만 둔다.
    **실제로 먼저 막히는 것은 ① 토큰 비용 ② 사람이 읽을 양** 이다
    (하네스 5개 ≈ 55만 토큰, 개당 ~10만. 보고 하나가 1000줄을 넘기기도 한다).
- **budget 상한**을 반드시 명시한다(예: 각 ~50k 토큰, 전체 시간). **각도 수 × 개당 예산**으로 먼저 계산하고 시작한다.
- **Claude Code 계열 에이전트 = 네이티브 Workflow 툴 우선**: `budget` 하드캡 + `schema` 강제 + `/workflows` 관측이 자동. 레시피를 Workflow 스크립트로 돌린다.
- **OpenClaw/Hermes 계열 에이전트 = subagent/session spawn**: workflow 표준 UX·자동 캡이 약하다 → 작업에 `scope · max_agents · budget · stop_rule · return_schema · owner synthesis`를 **직접 명시**해야 같은 품질·비용제어가 된다. 하나라도 없으면 harness 금지. `max_agents` 미기재 기존/모호 지시는 fallback 6으로 해석하고 무캡 실행하지 않는다. (같은 레시피, 수동 캡.)
- OpenClaw 수동 spawn 명시 cap은 6이다. 더 필요하면 full harness 또는 다른 runtime 배정을 검토하고 the team lead에게 고지한다.
- 가벼우면 인라인 Agent 2~4개도 OK. 수동 직접 spawn은 캡·스키마가 없어 토큰 폭주 위험(50k 캡을 2배 넘길 수 있다) — 가능하면 Workflow/명시 캡으로.

---

## ⑤ 검증 — 8 품질패턴 (병렬은 겹침·환각을 낸다, 안 하면 채택 금지)

From b3rys/b3rys-team-os, Apache-2.0.

More from b3rys/b3rys-team-os