Harness

---
name: harness
description: "서브에이전트 팀(하네스)을 만들지 말지 정하고, 만들기로 했으면 구성·확장·정리하는 메타 스킬. (1) '팀 만들어줘'·'하네스 구성/구축/확장/점검' 요청 시, (2) 한 작업이 서로 **독립·비중첩**인 하위작업 3개 이상으로 갈리고 각각 상당한 시간이 걸릴 때, (3) 기존 팀에 에이전트·스킬을 추가하거나 역할이 겹쳐 정리가 필요할 때. ★팀은 공짜가 아니다 — 에이전트마다 컨텍스트를 새로 싣고, 비싸지는 건 **N**이다. **하위작업이 3개 미만이거나 서로 얽혀 있으면 이 스킬을 쓰지 말고 직접 하거나 1명에게 위임하라.** 서브에이전트 정의(.md)와 오케스트레이션 스킬(SKILL.md)을 `Write` 로 만들고 `spawn_agent` 으로 기동한다."
---

# Harness — 팀을 만들지 **말지**부터 정한다

이 스킬의 첫 번째 일은 팀을 만드는 것이 아니라 **팀이 필요한지 판정하는 것**이다.
아래 게이트를 통과하지 못하면 여기서 멈추고 직접 하거나 1명에게 위임한다. 그게 정답인
경우가 대부분이다.

**실행 모델**: 서브에이전트 위임 + 파일(`_workspace/`) 데이터 전달. 어느 어댑터로 전환해도
동일하게 동작한다(핵심원칙 #2).

지금 쓸 수 있는 협업 수단은 이만큼이다 — **금지 목록이 아니라 현재 런타임의 서술**이다:

| 하려는 것 | 지금 |
|---|---|
| 에이전트 사이 데이터 전달 | `_workspace/` 파일 |
| **여럿을 동시에 돌리기** | `spawn_agent(wait:false)` — 즉시 jobId. 기본(`wait:true`)은 그 자리에서 기다린다 |
| **결과 회수** | 자동이다. 소환자는 **거두기 전엔 못 끝난다**(런타임 보장) — 매니저면 이어지는 턴으로, 메인이면 새 답변으로 |
| 도는 중인 에이전트에 지시 얹기 | `steer_worker`(단방향, 다음 model-call 경계에 반영). 백그라운드 서브에도 된다 |
| 도는 중인 에이전트 멈추기 | `cancel_worker`·대시보드 카드·`/stop`. 멈추면 그 아래도 함께 멈춘다 |
| 진행 상황 관측 | 데몬 `EventBus` → 대시보드 잡 패널 |
| 에이전트 → 메인 실시간 알림(역방향) | **없다.** 결과는 완료 시 돌아온다(위 "결과 회수") |
| 서브에이전트가 다시 서브를 띄우기 | **불가** — `subagentDepth: 1`, 런타임이 막는다(깊이는 곱셈으로 커지고 안 보인다) |

깊이 제약만 하드다. 나머지는 **닫힌 문이 아니다** — 위 수단으로 안 되는 실제 사례를 만나면
프리미티브를 넓히자고 **사용자에게 제안하라**(능력 도입은 사용자 승인 사안 — SYSTEM.md).
다만 짓기 전에 위 수단의 조합으로 되는지 먼저 확인한다 — 대개 된다. 없는 사례를 상상해
인프라를 먼저 짓지 않는다.

---

## ① 게이트 — 어디로 갈 것인가

**팀을 만들지 말지가 팀 크기보다 앞선 결정이다.** ★비싸지는 건 위임이 아니라 **N** 이다 —
에이전트 하나는 대화 이력·메모리를 안 물려받아 메인 턴보다 **작게** 싣지만, 팀은 그게 N번이다.
그래서 아래 갈래는 **N을 정하는 판정**이지 아끼는 요령이 아니다. 세 갈래 중 하나를 고른다:

| 갈래 | 조건 | 행동 |
|------|------|------|
| **직접** | 단일 파일·단일 모듈, 읽고 답하는 질의, 감사·조회, 정답이 자명한 수정 | 비서가 그냥 한다. **파일도 팀도 만들지 않는다** |
| **1명 위임** | 일이 길지만(수 분+) 하나의 흐름이다. 또는 격리가 필요하다(대량 출력·긴 탐색) | `spawn_agent` 1명. **에이전트 파일 없이** 프롬프트에 역할을 실어도 된다(→③) |
| **팀** | 서로 **독립·비중첩**인 하위작업이 **3개 이상**이고 각각 상당한 시간이 걸린다 | 아래 ②부터 진행 |

**막히면 아래로 내려간다**(팀 → 1명 → 직접). 위로 올리지 않는다. 애매하다는 것은
"아직 쪼갤 만큼 알지 못한다"는 뜻이고, 그때 팀을 만들면 잘못 쪼갠 팀이 나온다.

> Anthropic 도 같은 원칙: *"단순 해법이 부족할 때만 멀티스텝 에이전트를 추가하라."*
> 낭비 없는 오케스트레이션의 첫 규칙은 **"필요 없으면 오케스트레이트하지 않는다"** 이다.

**중간에 접어도 된다.** 팀으로 갔는데 하위작업이 서로 물린다는 게 드러나면 팀을 유지하지
말고 접고 직접으로 내려와라. 만들어 둔 파일이 아깝다는 이유로 잘못된 구조를 끌고 가지 않는다.

---

## ② 규모 — **면적**으로 정한다, 개수로 정하지 않는다

> ★**먼저: 이 팬아웃을 누가 하는가.** 팀 갈래는 정의상 서브에이전트 2명 이상이고, 그건
> **매니저 몫**이다(SYSTEM.md §1 이 정본 — "2명 이상 필요하면 매니저에게 통째로 넘겨라").
> 그러니 아래 인원·역할 설계는 **매니저가 쓰는 것**이다.
> - **메인 턴이라면**: 여기서 직접 뿌리지 말고 `run_in_background` 로 매니저에게 통째로
>   넘겨라. 전경에서 여러 명을 지휘하지 않는다 — 그게 오늘 사고가 났던 자리다.
> - **이미 매니저 안이라면**: 그대로 `spawn_agent` 로 팬아웃한다. 여기부터가 당신 일이다.
>
> (자기가 어느 쪽인지는 작동 컨텍스트의 「지금 당신의 자리」가 말해 준다. 없으면 메인이다.)

에이전트 수를 정하는 기준은 "할 일이 몇 개인가"가 아니라 **"서로 다른 것을 읽는가"** 다.

- **각자 읽어야 할 파일·계층이 겹치면 합쳐라.** 겹치는 만큼 같은 컨텍스트를 두 번 싣는다
  (에이전트 1명이 도메인 하나를 읽는 데만도 상당한 토큰이 든다).
- **읽기 팬아웃은 싸고 안전하다** — 조사·감사·검토는 여럿이 병렬로 읽어도 충돌이 없다.
- **쓰기 팬아웃은 비싸고 위험하다** — 같은 파일을 두 에이전트가 고치면 서로 덮어쓴다.
  쓰기는 **파일 영역이 확실히 갈릴 때만** 병렬로 두고, 아니면 순차로 한다.

| 상황 | 인원 |
|------|------|
| 면적이 2~3 갈래(예: 서버 / UI / 검증) | 2~3명 |
| 면적이 뚜렷이 더 갈리고 각 갈래가 큼 | 3~5명 |
| 그 이상 | **근거를 대라.** 7명을 넘으면 조율 비용이 이점을 넘는다 |

> 3명의 집중된 팀원이 5명의 산만한 팀원보다 낫다.

**깊이는 1이다** — 서브에이전트는 `subagentDepth: 1` 로 실행되어 스스로 다시 서브에이전트를
띄울 수 없다(런타임 보장). ★단 **매니저는 지휘자다**: `run_in_background` 로 띄운 매니저는
`subagentDepth 0` 이라 자기 밑에 서브를 여럿 띄울 수 있다(그 서브들이 잎이다). 즉 층은
`비서 → 매니저 → 서브` 까지고, 서브 밑은 없다. 매니저가 또 매니저를 띄우는 것도 막혀 있다.

**동시에 돌릴 때**(`wait:false`)도 위 "면적" 기준은 그대로다 — 동시에 돌 수 있다는 게 많이
돌려도 된다는 뜻이 아니다. 병렬은 **벽시계**를 줄이지 **토큰**을 줄이지 않는다. 5명을 동시에
띄우면 5명분 토큰을 5분 만에 쓴다(순차면 25분에 쓸 뿐 총액은 같다). 면적이 갈리지 않는데 병렬로 나누면
같은 컨텍스트를 N번 싣고 결과를 합치는 값만 더 든다.

---

## ③ 영속화 — **반복되는 역할만** 파일로 만든다

에이전트 정의 `.md` 는 "다음에도 이 역할을 부른다"는 선언이다. 그러니 판정은 하나:

- **반복된다** → `<TIGUCLAW_HOME>/agents/<name>.md` 로 만든다. 파일로 있어야 다음 세션
  재사용 + 자동 발견 인덱스 등록이 된다.
- **이번 한 번이다** → 파일을 만들지 마라. 위임 프롬프트에 역할을 실어 보내는 게 더 싸고
  정확하다. 쓰지 않을 파일이 쌓이면 다음 사람이 "이건 뭐지"에 시간을 쓴다.

**자산 경로**(SYSTEM.md §5 — 명시 없으면 **홈이 기본**):
- 서브에이전트: `<TIGUCLAW_HOME>/agents/<name>.md`
- 오케스트레이션 스킬: `<TIGUCLAW_HOME>/skills/<도메인-목적>/SKILL.md`
- 프로젝트 전용(cwd 가 그 폴더일 때만 발견): `<TIGUCLAW_HOME>/workspace/<project>/.tiguclaw/{agents,skills}`

---

## ④ 구성 — 에이전트 정의 + 오케스트레이션 스킬

tiguclaw 의 단위는 **에이전트 + 스킬**(별도 "team" 파일 개념 없음). 팀 = 여러 서브에이전트
정의 + 1개의 오케스트레이션 스킬(누가 언제 어떤 순서로 협업하는가).

**에이전트를 가르는 4축**: 전문성(다른 도메인 지식?) · 병렬성(독립 수행 가능?) ·
컨텍스트(다른 파일을 읽나?) · 재사용성(다른 팀에서도?). ②의 면적 기준과 같은 방향이다.

**모델은 등급으로**(핵심원칙 #2 — 모델명 하드코딩 금지):
`high` 추론 품질이 결과를 좌우(설계·통합·검증) / `mid` 일반 구현·분석 / `low` 단순·대량.
등급은 어댑터가 자기 풀로 해석한다. `model: "opus"` 처럼 박으면 어댑터마다 갈려 #2 위반이다.

**도구는 최소한만** — 설계자에게 `Write`/`Edit` 를 주지 않는다.

**오케스트레이션 스킬**은 그 팀의 실행 컨텍스트(에이전트 이름·산출물 경로·빌드 명령·작업
유형별 위임 순서)를 담는다. **개별 스킬을 쓰는 방법의 진실 소스는 `skill-creator`** 다 —
SKILL.md 규격·description 원칙·progressive disclosure 는 거기를 따르고 여기 중복하지 않는다.

**변경 이력은 `git log` 다.** 스킬 본문에 이력 테이블을 두지 마라(같은 이력이 두 곳이 된다).

> 상세 패턴·정의 구조·재사용 설계: `references/agent-design-patterns.md`
> 오케스트레이션 템플릿·데이터 전달·에러 핸들링: `references/orchestrator-template.md`
> QA 에이전트(경계면 교차 비교·incremental QA): `references/qa-agent-guide.md`

---

## ⑤ 검증 — **규모에 비례**해서

모든 팀에 같은 검증을 걸지 않는다. 검증이 구축보다 비싸지면 아무도 안 한다.

**항상**(싸고, 틀리면 바로 아픔):
- 에이전트 파일이 실제로 그 경로에 있고, 오케스트레이션 스킬이 부르는 이름과 **일치**하는가
- frontmatter 의 `model` 이 등급(high/mid/low)인가, 도구가 역할에 맞게 최소인가
- 산출물 경로가 절대 경로로 명시됐는가(`_workspace/` 기준)
- 데이터 전달에 빈 구간이 없는가 — 각 에이전트의 입력이 앞 단계의 출력과 맞물리는가

**널리 재사용될 스킬일 때만**: 트리거 검증(should-trigger / should-NOT-trigger 각 8~10개,
경계가 모호한 near-miss 가 좋은 케이스) + 실제 프롬프트로 드라이런. 팀 내부 전용 스킬에는
과하다.

검증 후 사용자에게 **구성 결과를 보고**한다(팀 이름 · 파이프라인 · 에이전트 표[이름/역할/
도구] · 산출물 경로 · 다음 단계).

---

## ⑥ 유지 — 새로 만들기 전에 **기존을 넓힌다**

확장 요청이 오면 새 에이전트를 만들기 전에 **역할이 겹치는 기존 에이전트가 있는지 먼저
본다**(「## 사용 가능 서브에이전트」 인덱스 + `<TIGUCLAW_HOME>/agents/`).

- **역할이 같고 범위만 좁다** → 새로 만들지 말고 **기존 정의의 범위를 넓혀라.**
  `planner` 가 있는데 `lab-planner` 를 또 만들면, 이후 위임할 때마다 둘 중 무엇을 부를지
  고르게 되고 결국 잘못 고른다.
- **역할이 실제로 다르다**(설계 ↔ 구현처럼) → 새로 만든다.
- **오케스트레이션 스킬은 새로 만들지 말고 기존 것을 수정한다** — 새 에이전트를 구성·데이터
  흐름에 반영하고, description 에 트리거 키워드를 추가한다.

정리도 유지의 일부다. 안 불리는 에이전트, 서로 포함 관계인 에이전트는 **합치거나 지운다**
(사용자 승인 후). 팀은 커지기만 하면 느려진다.

---

## 원칙

- 에이전트는 **역할이 명확**해야 한다(하나의 역할 = 재사용성↑)
- 도구는 **최소한만**, model 은 **등급**으로(모델명 하드코딩 금지 = #2)
- 파이프라인은 **단방향**이 기본. 복잡한 루프는 비서가 오케스트레이션에서 판단
- 오케스트레이션은 **시스템이 아닌 `.md`** 로 정의한다
- 중간 산출물은 `_workspace/` 에 **보존**(삭제하지 않음 — 사후 검증·감사 추적)
- 새 자산은 **홈이 기본**(SYSTEM.md §5). "이 프로젝트에" 명시 시에만 워크스페이스

### 팀이 도는 동안 — 지휘자의 역할

팀을 **이미 구성해 그 팀으로 도는 작업**에서는 **그 팀을 띄운 쪽**(=매니저)이
오케스트레이션(위임·수신·판단·보고)에 집중한다 — 설계는 designer 에게, 구현은
implementer 에게, 검증은 qa 에게. 팀을 만들어 놓고 지휘자가 같은 일을 또 하면 그 팀은
있으나 마나다.

메인 비서는 그동안 **대화를 막지 않는다** — 매니저가 끝나면 결과가 후속 메시지로 오고,
그때 맥락을 입혀 자기 인격으로 정리해 보고한다(SYSTEM.md §2). 진행 중 사용자가 다른 걸
물으면 정상 응대한다.

★단, 이것은 **팀으로 가기로 판정된 작업에 한한다.** ①에서 "직접"·"1명 위임"으로 갈린 일을
비서가 직접 처리하는 것은 정상이며 권장된다 — 짧은 편집·단일 파일 수정에 팀을 태우는 것이
낭비다(SYSTEM.md 의 과잉 위임 금지와 같은 방향).

---

## 참고

- 서브에이전트 설계 패턴(실행 모델·아키텍처·정의 구조·모델 등급): `references/agent-design-patterns.md`
- 오케스트레이션 템플릿(컨텍스트 확인·데이터 전달·에러 핸들링): `references/orchestrator-template.md`
- QA 에이전트 가이드(경계면 교차 비교·incremental QA·정의 템플릿): `references/qa-agent-guide.md`
- 개별 스킬 작성 규격: `skill-creator` 스킬 — 규격 본문은 그 스킬의 `references/skill-format.md`

## 출처 / Attribution

이 스킬(SKILL.md + references/)은 **[revfactory/harness](https://github.com/revfactory/harness)**
(Apache License 2.0, © robin)를 적응·이식한 파생물입니다 — tiguclaw 의 홈/스킬 모델(`<TIGUCLAW_HOME>`,
SYSTEM.md §5), 서브에이전트 전용 위임, 멀티 LLM(모델 등급화) 런타임에 맞게 **수정**했습니다.
Apache-2.0 §4 에 따라 원저작자 귀속·라이선스 고지를 유지합니다. 원문 라이선스: 위 저장소 `LICENSE`.