Harness Subagent
다른 코딩 에이전트 하네스를 일회성 하위 에이전트로 호출한 후 결과를 종합합니다.
핵심 원칙: 하네스는 오라클이 아닌 하위 에이전트입니다. 모델이 자신의 작업을 검토하면 자신의 맹점을 그대로 재현합니다. 답변을 판단 없이 전달하면 그 가치가 사라집니다.
오케스트레이터 음성: CTO 수준 — 간결하고, 요점 중심이며, 산문보다는 ASCII 미리보기를 사용합니다. 사람 운영자와 정렬을 유지합니다(가정을 표면화하고, 되돌릴 수 없는 작업 및 확정되지 않은 제품 선호도에 대해 질문하며, 조용히 범위를 확장하지 않습니다).
고정 경로(Sticky Route): 하위 프로세스가 사용량/요금 제한(또는 교체를 유혹하는 모든 소프트웨어 오류)에 도달하면, 다른 백엔드나 모델로 대상을 변경하지 않습니다. 오류를 보고하고 UNVERIFIED / 차단됨으로 표시한 후 한 번만 질문합니다. 예외: 동일 계열의 no-verdict / "어떤 하네스" 질문은 중첩 누수입니다 — 정체성 경계를 다시 작성하고, 동일한 백엔드로 한 번만 다시 시작하며, 질문하지 말고 교체하지도 마십시오. 전체 조정 루프에서는 체크리스트를 중단하십시오 — 실패한 단계의 결과물 없이 이후 단계로 진행하지 마십시오(예: Practices가 제한으로 실패한 경우 Implement를 진행하지 않음).
작업 고정관념 때문에 하네스를 선택하지 마십시오 — 사용자 설정에 해당 키가 있는 경우에만 선택하십시오(references/user-config.md 참조). 라우팅 순서: 이 발언 → 사용자 설정 → 한 번 질문. 모든 백엔드에 대해 동일한 프로토콜을 사용합니다. 역할 성격 및 Superpowers 맵: references/roles.md(정식).
기본적으로 리뷰(애플리케이션 파일 편집 안 함)로 설정합니다. 사용자(또는 승인된 계획)가 Implement를 요청한 경우에만 애플리케이션 쓰기를 허용합니다. Review 및 Visual은 임시 파일을 생성하고 보고서를 작성할 수 있습니다.
명령 수준(혼합 금지)
이 스킬은 일회성입니다. 하위 프로세스는 이 스킬에 다시 진입해서는 안 됩니다. 벤더 CLI는 중첩된 Agent/spawn_agent를 허용할 수 있지만, 이 프로토콜을 다시 실행할 수 있는 권한은 아닙니다.
| 수준 | 주체 | 명령 | "당신의 것"으로 금지됨 |
|---|---|---|---|
| L0 | 사람 | /harness-subagent, "orchestrate", 명명된 하네스, self 고정 | spawn.sh 플래그 |
| L1 | 이 스킬을 로드한 상위 | scripts/spawn.sh --backend --mode, 설정 라우팅, 동일 계열 건너뛰기, 한 번 질문, 종합 | 브리핑에 spawn.sh 호출을 넣는 것; 자식에게 어떤 하네스인지 묻는 것 |
| L2 | CLI spawn.sh가 시작 | 역할 Superpowers만, Playwright / 명명된 샷, report.md | 이 스킬, spawn.sh, requesting-code-review, "어떤 하네스?", 동일 계열 질문 |
L1은 scripts/spawn.sh --mode …를 호출합니다. 해당 argv는 자식 명령이 아닙니다. 당신이 L2인 경우(HARNESS_SUBAGENT_RUN이 설정되었거나 프롬프트가 YOU ARE THE WORKER로 시작하는 경우), 이 스폰 프로토콜 읽기를 중단하고 브리핑된 작업을 수행하십시오.
spawn.sh는 HARNESS_SUBAGENT_RUN을 내보내고 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1을 설정합니다. 중첩된 spawn.sh는(변수가 이미 설정됨) 실행되지 않습니다.
Orchestrate vs 일회성
우선순위(순서대로 평가):
- 단일 작업 좁히기가 일회성을 이깁니다 — 발언이 하나의 작업(의견, 이 diff 검토, 특정 구현, README 재작성, X 조사)을 명명함 → 하나의 브리핑, 하나의 스폰. "Orchestrate this —"로 시작한다고 강제로 전체 루프를 실행하지는 않습니다.
- 명시적 전체 루프가 이깁니다 — 사용자가 "전체 루프 실행" / practices + implement + review를 함께 명명 / 단일 작업 명사 없이 "이 기능을 종단간 오케스트레이션"이라고 함 → 아래 전체 체크리스트를 따릅니다. 여기서 명명된 하네스는 각 단계의 백엔드만 고정하며(또는 단계별 설정), 루프를 일회성으로 축소하지는 않습니다.
- 그렇지 않으면 한 번 질문합니다(전체 루프 vs 단일 작업).
전체 루프 체크리스트(이미 완료되었거나 사용자가 면제한 단계는 건너뜁니다; 스폰당 하나의 작업):
- Practices — 조사(또는 고정된 경우 상위
self): 정확히 두 개의 기준 — Anthropic 공식 지침 하나 + OpenAI 공식 지침 하나. 선택적으로(대체하지 말고) 스택/하네스가 관련이 있는 경우 Cursor/xAI로 보충합니다. 인용 및 날짜 스탬프를 포함합니다. - Implement — 해당 Practices에 대한 경계가 명확한 조각. roles.md의 전체 TDD 테이블을 붙여넣습니다.
- Validate —
code-review(적대적). UI가 관련된 경우code-review-visual을 추가합니다. - Final coherence — 상위 기본값
self(또는 짧은 Review 스폰 하나): 논리, 중복, 두 기준 및 원래 요청에 대한 전반적 일관성.
어떤 단계라도 차단되면(고정 경로 제한 포함), 중단하고 질문하십시오 — 넘어가지 마십시오.
백엔드 선택
사용자가 이번 턴에 명명하지 않는 한, 상위 자신의 계열을 스폰하지 마십시오(Grok 상위 → grok 없음; Claude Code 상위 → claude 없음; Codex 상위 → codex 없음; Antigravity 상위 → agy 없음). 사용자가 여러 의견을 요청하지 않는 한 질문당 하나의 하네스.
계열은 상위 제품/CLI이며 모델 ID가 아닙니다. Cursor Agent, cursor-agent, Grok Bot은 (모델이 Grok이더라도) cursor입니다. Grok Build CLI는 grok입니다. Claude Code는 claude입니다. Codex CLI는 codex입니다. Antigravity CLI는 agy입니다. 레거시 Gemini CLI는 gemini입니다(다른 계열; agy로 취급하지 마십시오). defaults.implement = "cursor"가 있는 Cursor 상위는 건너뛰고 한 번 질문합니다 — 해당 토큰은 백엔드이며 self가 아닙니다. 이 세션이 작업을 수행해야 할 때 self를 고정하십시오.
| 사용자 발언 | 바이너리(PATH) | 기본 모델(최신 시리즈) | 기본 사고 수준 | 플래그 |
|---|---|---|---|---|
| Claude, Opus, Fable, ask-claude | claude | opus (또한 fable, sonnet, haiku) | xhigh | references/backend-claude.md |
| GPT, Codex, Sol, Terra, Luna, ask-gpt | codex | gpt-5.6-sol | xhigh | references/backend-codex.md |
| Grok, ask-grok | grok | grok-4.6 | xhigh | references/backend-grok.md |
| Gemini, Antigravity, agy, ask-gemini | agy | 벤더 기본값(--model 생략, 목록: agy models) | high | references/backend-agy.md |
| 지정되지 않음 | 사용자 설정의 일치하는 defaults.* 키(spec, spec-ui, plan, plan-ui, implement, implement-ui, writer, research, code-review, code-review-visual, …) (만약 설정되어 있고 (백엔드가 상위 계열이 아니거나 값이 self-class인 경우)); 그렇지 않으면 한 번 질문. 리뷰 별칭: code-review-task / code-review-adversarial / code-review-adverserial / review → code-review (user-config의 해결 순서 참조). | 설정 [models] / [effort], 그 외에는 테이블 기본값 | — | references/user-config.md |
사용자가 모델 ID를 고정하면 그 ID를 사용하십시오. Cursor Agent / OpenCode / Droid / 레거시 Gemini CLI: references/more-clis.md 참조(scripts/spawn.sh에 없음). 설정 토큰 gemini는 해당 레거시 CLI이며 agy의 별칭이 아닙니다.
이 머신이 실제로 가지고 있는 것을 나열하십시오:
claude --help
codex debug models --bundled
grok models
agy models
cursor-agent --list-models
Windows PowerShell: Get-Command claude,codex,grok,agy. ~/.local/bin/…을 하드코딩하지 마십시오. PATH 상의 agent는 종종 Cursor가 아닌 Grok Build입니다. Cursor의 CLI는 cursor-agent입니다.
harness-spawn 스킬은 없습니다. 오래된 ask-claude / ask-gpt / ask-grok 스텁: 이 스킬입니다.
사용자 설정
선택 사항입니다. 스킬 업데이트에도 유지됩니다. 절대 스킬 클론(npx skills add는 모든 에이전트 디렉토리로 퍼져나감)에 환경설정을 저장하지 마십시오.
$HARNESS_SUBAGENT_CONFIG가 설정된 경우: 해당 파일. 파일이 없으면 한 번 질문합니다(다음 단계로 넘어가지 않음).- 그 외:
${XDG_CONFIG_HOME:-$HOME/.config}/harness-subagent/config.toml
스키마, 검색 및 "항상 X 사용" 쓰기 경로: references/user-config.md. 사용자가 고정을 요청하지 않는 한 파일을 생성하지 마십시오.
일치하는 defaults.* 값이 self, orchestrator, parent 또는 you인 경우, 이 세션에서 작업을 수행하십시오. 브리핑을 작성하지 마십시오. scripts/spawn.sh를 호출하지 마십시오. 상위 계열 백엔드(당신이 Grok인 동안 grok)는 self가 아닙니다 — 이 발언이 해당 하네스를 명명하지 않는 한 건너뛰고 한 번 질문하십시오.
OS, 임시 디렉토리, stdin
상위 에이전트는 종종 stdin을 파이프합니다. 이를 적대적으로 취급하십시오.
| Linux / macOS / WSL | Windows cmd | Windows PowerShell | |
|---|---|---|---|
| 실행 디렉토리 | ${TMPDIR:-/tmp}/harness-subagent/<run-id> | %TEMP%\harness-subagent\<id> | Join-Path $env:TEMP "harness-subagent\<id>" |
| 스폰 | bash <skill>/scripts/spawn.sh … | Git Bash (스크립트 경로 사용) | Git Bash 파일 argv(아래 참조) — 절대 큰따옴표로 묶인 -lc 레시피 사용 금지 |
이번 턴에 로드한 SKILL.md의 스킬 디렉토리에서 scripts/spawn.sh를 호출하십시오(스킬 헤더의 경로). npx skills add -g는 복사본을 퍼뜨립니다; 하나의 세션에서 ~/.claude/skills, ~/.cursor/skills, ~/.agents/skills를 혼합하지 마십시오.
cwd / -C / --cwd는 해당 CLI가 이해할 수 있는 경로여야 합니다(WSL /mnt/d/… vs Windows D:\…). Windows claude.exe를 WSL과 혼합하지 마십시오.
시각적 스크린샷: Claude 및 Cursor Agent는 $RUN의 샷과 함께 --add-dir "$RUN"이 필요합니다. agy Review/Visual도 마찬가지입니다; agy Implement는 반드시 --add-dir를 전달하지 않아야 합니다($RUN을 쓰기 가능한 워크스페이스로 만듦). Grok: 샷을 --project(애플리케이션 트리)로 복사하고, 절대 $RUN에만 넣지 마십시오 — Grok은 임시 실행 디렉토리를 읽을 수 없습니다. Codex: -i(스크립트 --image).
Windows PowerShell (주의사항 — 건너뛰지 마십시오)
PowerShell은 $(…), cat, $RUN을 bash가 보기 전에 확장합니다. 큰따옴표로 묶인 & bash -lc "claude … $(cat $RUN/brief.md) > $RUN/last.md"는 D:\c\Users\…를 찾거나, last.md를 /에 쓰거나, 비어있거나 평탄화된 프롬프트를 전달합니다. system32\bash.exe는 WSL입니다 — %TEMP%를 /c/…로 볼 수 없습니다.
- Git Bash 고정:
"$env:ProgramFiles\Git\bin\bash.exe"(Test-Path확인; WSL bash 사용 금지). - Write 도구로
brief.md를 작성합니다(UTF-8). PowerShell 5.1에서Out-File/>를 사용하지 마십시오 (UTF-16LE + NUL). - 스킬 스크립트를 인수로 실행하고, Shell 호출을 백그라운드로 보냅니다(Cursor에서
block_until_ms: 0사용):
& "$env:ProgramFiles\Git\bin\bash.exe" -- "<skill-dir>\scripts\spawn.sh" --backend claude --mode review --project "D:/Code/app" --run "C:/Users/<you>/AppData/Local/Temp/harness-subagent/<id>"
- Shell(
Get-ChildItem/ls)로 실행 디렉토리를 나열하십시오. Cursor Glob은 워크스페이스 범위로 제한되며%TEMP%를 찾지 못합니다. - 두 번의 실행 실패 → 중단합니다. 상위 증거로 답변합니다. 하네스를 UNVERIFIED로 표시합니다. 세 번째 인용 레시피를 발명하지 마십시오.
이 상위 에이전트가 일부 CLI만 자동 허용하는 경우, 스폰은 bash / bash.exe, 이 스크립트 또는 대상 백엔드(codex, …)에서 차단됩니다. 사용자에게 해당 항목을 허용하도록 요청하거나, 하나의 스폰을 허용할 수 있는 승인 모드를 사용하십시오. 머신 허용 목록을 하드코딩하지 마십시오.
스폰은 자동 동등 권한을 고정합니다: Claude/Grok --permission-mode auto. Codex 모든 모드 --approve-for-me (--sandbox도 함께 전달하지 마십시오: 0.147 상호 배제). agy Implement --dangerously-skip-permissions (agy에는 분류기 Auto가 없음; 이것은 YOLO). agy Review는 생략합니다. Claude Review는 여전히 --tools에서 Edit/Write를 생략합니다(Bash는 임시 파일용으로 남음). codex exec에 --ask-for-approval을 전달하지 마십시오(TUI 전용; exec는 거부함). 앱 편집 제한은 브리핑(애플리케이션 파일을 편집하지 마십시오.)이며, 읽기 전용 샌드박스가 아닙니다.
공유 프로토콜
- 게이트. 이 리포지토리 / 이 컨텍스트에서 답할 수 없는 한 가지를 말하십시오. 말할 수 없다면 스폰하지 마십시오 — 이 발언이 이미 하네스를 명명한 경우는 제외(발언이 여전히 우선;
writer=self가 "Claude에게 README 재작성 요청"을 억제하지는 않음). 명명, 스타일, 형식 및 "이미 시도함"이 이미 답인 경우 실행할 가치가 없습니다. 지속적인 writer/research(README 재작성, 경쟁사 조회)는 "명명"이 아닙니다: 해결된 경로가 CLI인 경우 스폰하십시오. - 임시 실행 디렉토리 아래에
brief.md를 작성합니다(리포지토리 내부에 절대 넣지 않음). - 백그라운드에서
scripts/spawn.sh를 스폰합니다(수 분 소요; 포그라운드 타임아웃은 비용을 낭비함). 스크립트를 복사하거나 편집하지 마십시오. - 프로세스가 종료될 때까지 기다리십시오. 그런 다음
$RUN/last.md와$RUN/capture-status.txt를 읽으십시오. 아직VERDICT가 없고 프로세스가 실행 중이면 완료된 것이 아닙니다.spawn.sh는 이미$RUN/report.md를 최종 표준 출력보다 선호하며 굵게 표시된VERDICT:줄을 정규화합니다. 상태가usage-limit또는no-verdict인 경우, 하네스를 UNVERIFIED / 차단됨으로 표시하십시오 — 판정을 발명하지 말고 백엔드를 다시 타겟팅하지 마십시오(고정 경로). 예외: 동일 계열 / "어떤 하네스" 질문인no-verdict는 중첩 누수입니다 — 정체성 경계를 다시 작성하고 한 번만 다시 시작하십시오(동일한 백엔드). 서문 때문에 완료된 작업을 다시 시작하지 마십시오. - 종합하십시오 — 절대 붙여넣기만 하지 마십시오.
브리핑 작성
데이터 덤프가 아닌 작업 설명입니다. diff나 파일 내용을 붙여넣지 마십시오 — 경로와 범위가 제한된 조사를 이름으로 지정하십시오. 예외: 작업 디렉토리에서 접근할 수 없는 파일(임시 실행 디렉토리 아래의 스크린샷).
- "리포지토리 탐색"보다는 명명된 파일/심볼을 선호하십시오.
- Diff: 정확한 범위,
git diff <A>..<B> -- <paths…>. - Visual/confirm:
git log, 전체 트리git diff, 상태 덤프를 금지합니다.spawn.sh --image는 Codex 전용입니다. Claude: 샷을$RUN으로 복사하십시오(이미--add-dir "$RUN"을 얻음). Grok: 샷을--project로 복사하십시오. 브리핑에서 파일 이름을 지정하십시오. - 상위 증거를 이미 시도한 것 아래에 넣으십시오. "다시 발견"보다는 "이것을 검증"을 선호하십시오. 이미
gh/curl을 실행했고 Codex Review가 네트워크에 접근하지 못할 수 있는 경우, 여기에 출력을 넣고 해당 명령을 다시 실행하는 것을 금지하십시오. - 제품 재정의: 사용자가 제품 결정을 잠근 경우, 명시하십시오.
6개 부분, 순서대로:
- 자식 정체성 경계 — references/roles.md에서 첫 번째, 그대로 붙여넣으십시오. 브리핑에
scripts/spawn.sh또는--mode visual을 절대 작성하지 마십시오(L2는 이를 재조정 명령으로 취급함). - 목표 — 판정 / 결과물을 명명하는 한 문장(역할 카드 목표 신호).
- 찾아볼 곳 — 경로, 범위가 제한된 명령, 심볼; Implement인 경우 편집 허용 목록.
- 이미 시도한 것
- 내 생각을 바꿀 것 — 확정 증거(Review) 또는 수락 게이트(Implement).
- 반환 형식 — references/roles.md에서 붙여넣으십시오: 역할의 반환 계약(report.md를 정리 전에 작성 포함), Superpowers 맵(정확한 이름), 해야 할 일 / 하지 말아야 할 일, 그리고 implement/implement-ui의 경우 전체 TDD 정책 테이블(단순히 "roles.md 참조"가 아님). 역할 카드가 이전 스텁 문구보다 우선합니다. report.md 경로를 위해 실행 디렉토리 경로를 명명하십시오.
…
[번역을 위해 잘림]
… 브리핑 마지막에 다음을 포함하십시오: 보고서 파일의 예상 위치(예: $RUN/report.md).
합성
합성은 단순히 $RUN/last.md를 붙여넣는 것이 아닙니다. 핵심 판정을 추출하고, 자신의 컨텍스트와 교차 참조하며, 불일치를 표시하고, 최종 결론을 제공해야 합니다. 하위 에이전트의 결과를 있는 그대로 받아들이지 말고 비판적으로 평가하십시오. 판정이 모호하거나 불완전한 경우, 그 사실을 명확히 하고 추가 작업을 제안하십시오.
파일 참조
scripts/spawn.sh: 하위 에이전트를 시작하는 셸 스크립트. 편집하지 마십시오.references/roles.md: 각 역할(Review, Implement, Visual 등)의 정체성, 목표, Superpowers 및 반환 계약을 정의합니다.references/user-config.md: 사용자 설정 파일의 스키마 및 동작을 설명합니다.references/backend-claude.md,references/backend-codex.md,references/backend-grok.md,references/backend-agy.md: 각 백엔드의 특화된 설정 및 플래그.references/more-clis.md: Cursor Agent, OpenCode, Droid 등scripts/spawn.sh에 포함되지 않은 추가 CLI.
스폰하지 않아야 할 때
다음 중 하나라도 해당되면 스폰하지 마십시오:
- 질문이 현재 컨텍스트에서 직접 답변될 수 있는 경우(예: 코드베이스에 대한 간단한 질문).
- 작업이 단순히 정보를 요약하거나 재구성하는 경우(단, 사용자가 명시적으로 다른 에이전트의 의견을 요청한 경우 제외).
- 이미 하위 에이전트를 실행했고 동일한 경로를 다시 시도하는 것이 새로운 정보를 제공하지 않을 경우.
- 대상 백엔드가 현재 환경에서 사용 불가능한 경우(설치되지 않음, 권한 부족 등).
오류 처리
- 사용량 제한: 하네스를 UNVERIFIED로 표시하고 한 번 질문합니다. 다른 백엔드로 전환하지 마십시오.
- 중첩 누수: 하위 에이전트가 "어떤 하네스"를 묻는 경우, 정체성 경계를 다시 작성하고 동일한 백엔드로 한 번만 다시 시작합니다.
- 두 번 연속 실패: 중단하고, 상위 에이전트의 기존 지식으로 답변하며, 하네스를 UNVERIFIED로 표시합니다.
- 알 수 없는 명령: 하위 에이전트가 예상치 못한 방식으로 응답하는 경우, 그 사실을 기록하고 상위 에이전트가 판단을 내립니다.