harness-subagent
제한된 작업을 다른 코딩 에이전트 CLI에 맡기고, 그 결과를 판단합니다.
License: MIT
Agent Skills
Claude Code
Codex
Grok Build
Cursor CLI
Muse Code
Codex를 Claude Code에서 호출하고 싶었던 적이 있습니까?
Grok Build가 Claude Code를 호출하도록 하고 싶었던 적이 있습니까?
Claude Code가 두 번째 의견을 위해 diff를 GPT로 보내고 싶었던 적이 있습니까?
이것이 바로 이 스킬입니다. 사용자가 이미 사용하고 있는 에이전트 내에 머무릅니다. 해당 에이전트는 부모(parent) 역할을 합니다: 짧은 개요를 작성하고, 백그라운드에서 다른 CLI를 시작하며, 그 CLI의 보고서를 읽고, 무엇에 동의하는지, 무엇에 동의하지 않는지, 그리고 다음에 무엇을 할 것인지 사용자에게 알려줍니다.
자식(child)은 오라클이 아닙니다. 자신의 작업을 검토하는 모델은 스스로의 맹점을 반복합니다. 다른 공급업체에서 훈련된 모델은 그렇지 않을 수 있습니다. 부모가 판단 없이 답변을 전달하면 그 가치는 손실됩니다.
지원되는 자식 CLI: Claude Code (claude), Codex (codex), Grok Build (grok), Antigravity (agy), Cursor CLI (cursor-agent), 그리고 Meta의 Muse Code (muse). CLI, 모델 또는 노력을 명시하면 그것이 승리합니다. 이들 중 어느 것도 생략되면, 부모가 자신과 다른 공급업체를 선호하는 짧은 작업표에서 빈틈을 채웁니다. 페르소나는 없습니다.
이것은 Claude skill 형식의 Agent Skills입니다. 백그라운드에서 셸 명령(shell command)을 실행할 수 있는 모든 에이전트가 이를 사용할 수 있습니다.
다음 용도로 사용하지 마십시오: 해당 CLI를 설치하는 경우, 부모가 자체 컨텍스트에서 답변할 수 있는 질문의 경우, 또는 자식이 시작한 내부에서 사용하는 경우. 자식은 다시 위임하지 않습니다.
설치
npx skills add realspqrk/harness-subagent -g
이는 skills.sh 설치 프로그램입니다. -g 플래그는 사용자 레벨에 설치하며, 예를 들어 Claude Code의 경우 ~/.claude/skills/harness-subagent 또는 Cursor의 경우 ~/.cursor/skills/harness-subagent에 설치됩니다 (paths 참고). 나중에 npx skills update -g 명령어로 업데이트할 수 있습니다.
npx를 사용하지 않는 경우, 에이전트의 스킬 폴더로 클론(clone)하세요:
git clone https://github.com/realspqrk/harness-subagent.git ~/.claude/skills/harness-subagent
요구 사항 (Requirements)
PATH 환경 변수에 claude, codex, grok, agy, cursor-agent, 또는 muse 중 최소 하나가 존재하며 로그인되어 있어야 합니다.- Python 3 (
python 또는 python3).
- Windows: Git Bash. 부모 프로세스는 Git Bash를 통해
scripts/spawn.sh를 실행합니다. SKILL.md에 정확한 호출 방법이 나와 있습니다.
상태 확인 (Health check)
설치된 스킬 폴더에서 다음 명령어를 사용하세요:
scripts/health.sh
scripts/health.sh --update
예시 출력 (탭 구분):
claude 2.1.280 (Claude Code) logged-in -
codex codex-cli 0.155.1 logged-in -
grok missing - -
...
종료 코드(exit code)가 0인 경우는 모든 CLI가 존재하고, 로그인 확인이 필요한 모든 CLI에 로그인이 되어 있으며, (--update 사용 시) 모든 업데이트가 성공했을 때뿐입니다. 사용하지 않는 CLI는 missing으로 표시되며 종료 코드를 1로 만듭니다. 각 행을 읽어보세요. agy와 muse는 로그인 상태 확인 명령이 없으므로 항상 login-unknown을 보고합니다. 개별 CLI의 로그인 및 업데이트 명령어는 SKILL.md의 Health 섹션에 있습니다.
사용하기 (Use it)
프로토콜은 SKILL.md를 따릅니다. 이는 간략한 버전입니다.
- CLI와 모델을 지정하거나 부모 에이전트(parent)가 선택하게 할 수 있습니다. Opus 5.5, Fable, Sonnet 5.5, Astra, Sol, Terra, Luna, Grok 4.7, Muse Wonder, Wonder Full, Spark와 같이 언급된 이름들은 references/models.md에 있는 정확한 ID로 매핑되며, 이곳에는 가격 및 노력 수준(effort levels)도 나열되어 있습니다. Antigravity와 Cursor의 경우, CLI가 수락하는 ID를 전달해야 합니다. 만약 CLI, 모델 또는 노력을 생략하면, 부모 에이전트가 SKILL.md의 작업 테이블에서 각 빈칸을 채우고, 자신이 무엇을 선택했는지 말한 후 작업을 시작(spawn)합니다. 부모는 스스로
max, ultra, Fable, Wonder Full, 또는 Grok 4.7 Fast를 선택하는 일은 없습니다.
- 부모가 간략한 요약본(brief)을 작성합니다. 새로운 임시 실행 디렉터리(
temp run directory)에 brief.md 파일을 생성하며, 여기에는 수행할 작업 문장 하나, 검색할 위치, 이미 시도된 내용, 그리고 완료 시점이 포함됩니다. 경로를 지정하지만, 레포지토리 전체 내용을 붙여넣지는 않습니다.
- 부모가 백그라운드에서
scripts/spawn.sh를 실행하고 종료될 때까지 기다립니다.
- 부모가 보고서를 판단합니다.
report.md (또는 last.md)와 capture-status.txt를 읽은 후, 동의하는 부분, 동의하지 않는 부분, 그리고 자신이 할 작업을 말합니다. 단순히 붙여넣어진 보고서는 답변이 아닙니다.
you ──> parent ──brief.md──> spawn.sh ──> child CLI
^ │
└──────── report.md ────────────┘
...
할 수 있는 작업의 예시:
- Astra를 사용하고 노력 수준을 높여서(effort high), 이 브랜치의 diff 검토를 요청하세요.
src/ui/settings/에 설정 페이지 레이아웃을 구축하도록 Opus 5.5가 포함된 Claude Code를 사용하세요.- Grok 4.7에게
docs/plan.md에 있는 계획을 반박해 보도록 요청하세요.
- harness-subagent: Sol을 사용하고 중간 노력 수준(medium effort)으로, 왜
tests/api가 CI에서 불안정한지(flakes) 알아내세요. 편집 없이 보고만 하도록 합니다.
- 제가 병합하기 전에 Fable 5.1에게 이 마이그레이션 검토를 받으세요.
- (부모가 모델과 노력을 선택하며) 다른 공급업체로부터 이 계획에 대한 제2의 의견을 받으세요.
스폰당 하나의 작업만 가능합니다. '구현하고 검토하기'는 두 번의 스폰이거나, 한 번의 스폰과 부모 자체의 검토가 필요합니다.
자식(child)이 24시간 이내에 초기화되는 사용량 제한에 도달하면, spawn.sh는 기다렸다가 동일한 세션을 한 번 재개합니다. 다른 모든 사용량 제한으로 인한 중단은 실행을 종료시킵니다. 부모(parent)가 이를 보고하고 사용자에게 대기하라고 알립니다. 이는 제한 때문에 CLI나 모델을 전환하지 않습니다.
Superpowers와 함께
Superpowers는 기술(skills)을 기반으로 구축된 개발 방법론입니다. 이 기술들 중 여러 개는 호스트 자체의 서브에이전트 도구를 통해 서브에이전트를 전송합니다:
requesting-code-review는 리뷰어 서브에이전트에게 베이스(base) 커밋과 헤드(head) 커밋을 보냅니다.subagent-driven-development는 계획된 작업(plan task)당 구현자(implementer)와 작업 리뷰어를 실행한 다음, 마지막에 전체 브랜치 검토를 수행합니다.dispatching-parallel-agents는 독립적인 문제마다 하나의 에이전트를 실행합니다.
Superpowers는 사용자 지침(CLAUDE.md, AGENTS.md, GEMINI.md)이 자체 기술보다 우선한다고 명시합니다. 따라서 라우팅은 호스트 지침에 포함되어야 합니다. 이 기술은 Superpowers를 로드하지 않으며, Superpowers도 이 기술에 대해 알 필요가 없습니다.
최적의 방법: 모든 서브에이전트가 아닌 검토 단계를 라우팅하세요. Superpowers는 이미 각 작업 후에 검토를 수행합니다. subagent-driven-development의 끝에서의 전체 브랜치 검토와 병합(merge) 전의 requesting-code-review는 다른 공급업체의 모델이 가장 많이 추가되는 지점입니다. 구현자 서브에이전트는 네이티브로 유지하세요. 작업당 CLI 스폰은 새로운 프로세스와 새로운 컨텍스트를 소모합니다.
예시 CLAUDE.md 라인:
## Reviews
- When a Superpowers skill asks for a whole-branch review or a pre-merge code
review, run that review with harness-subagent: Codex, model Sol, effort high.
...
부모가 작성하는 지침(brief)은 다음과 같이 보입니다:
# YOU ARE THE WORKER. DO NOT SPAWN.
Do not load harness-subagent. Do not run scripts/spawn.sh.
...
만약 자식 CLI에도 Superpowers가 설치되어 있다면, 해당 using-superpowers 부트스트랩은 전송된 서브에이전트에게 건너뛰도록 지시합니다. 지침의 첫 줄에서 이미 자식이 작업자(worker)임을 명시하고 있습니다.
pstack poteto-mode와 함께
pstack은 Cursor를 위한 poteto의 스킬 세트이며, /add-plugin pstack으로 설치합니다. /poteto-mode가 진입점입니다. 이 모드는 23개의 플레이북 중 하나에 작업을 매칭하고 필요한 단계별로 다른 스킬들을 실행합니다. 이름으로 시작하며 대화(turns) 전반에 걸쳐 유지됩니다.
이 스킬의 서브 에이전트 규칙은 이미 이 스킬의 프로토콜에 맞게 조정되어 있습니다. 이는 백그라운드에서 서브 에이전트를 실행하고, 붙여넣은 컨텍스트 대신 파일 포인터를 전달하며, 역할별로 명시적인 모델을 설정합니다. 그리고 "모든 서브 에이전트 작업은 당신의 것입니다. diff를 검토하고 자신만의 요약을 작성하세요. 그것이 말한 내용을 그대로 전달하지 마세요."라고 지시합니다. 따라서 harness-subagent는 위임(delegate)이 실행되는 장소만 변경합니다. Cursor의 'Task' 대신 다른 벤더의 CLI에서 실행됩니다.
모범 사례: 라우팅을 자체적으로 항상 적용되는 Cursor 규칙에 배치하세요. /setup-pstack은 역할별 모델을 ~/.cursor/rules/pstack-models.mdc에 작성하며 실행할 때마다 파일 전체를 덮어쓰기 때문에, 사용자가 추가한 줄은 사라집니다. pstack의 다중 모델 스킬(interrogate, arena, architect, swarm)은 교체하고 싶지 않다면 설정된 패널에 그대로 두세요.
예시 ~/.cursor/rules/harness-subagent.mdc:
---
description: Route larger poteto-mode delegates through harness-subagent
alwaysApply: true
...
이렇게 사용합니다.
이것은 저의 설정일 뿐 프로토콜은 아닙니다. 이 스킬은 이러한 모델 선택을 강제하지 않습니다.
저는 로컬에서 Cursor GUI 내에서 pstack poteto-mode를 실행합니다. 그리고 상위 에이전트에게 다음과 같이 지시합니다: 중간 정도의 난이도부터 높은 난이도의 작업을 위해 서브 에이전트를 생성해야 할 때마다, 대신 harness-subagent를 사용하세요. UI 작업에는 Opus를 사용하고, 시각적 테스트에는 Codex를 사용하세요.
Opus는 Opus 5.5의 구어적 이름입니다. 시각 테스트 라인은 Codex CLI만 이름을 지정하므로, 부모가 작업 테이블에서 모델과 노력을 채웁니다. Sol이나 Astra와 같이 references/models.md에서 모델을 지정하여 고정할 수 있습니다. 이 선택은 저의 것입니다. 이러한 규칙은 스킬의 기본 테이블을 재정의합니다. 자신의 규칙에 추가하세요.
라이선스 (License)
MIT. Gerhard Petermeir / realspqrk. 이슈는 환영합니다. PR(Pull Request)이 기본값은 아닙니다.
