Agent Army
2계층 병렬 실행 프레임워크입니다. 지휘관은 최상위 모델(기본값 Fable, 또는 세션 모델인 경우 Opus)로 정찰, 구성, 브리핑, 검증을 담당합니다. 사용자가 배포 시 선택한 계층(전력 레벨 참조)에 따라 하위 모델 스웜을 조정합니다. 각 1계층 에이전트는 자체적인 전체 컨텍스트 창(슬라이스가 아님)을 가집니다. 각 에이전트는 그 아래에 2계층 하위 에이전트를 생성합니다. 결과적으로 하나의 두뇌를 나누는 것이 아니라 여러 개의 독립적인 두뇌가 동시에 실행됩니다.
Commander (you — Fable or Opus, the session model)
|
|-- Layer 1: Team (3 to 50+, each = own 1M context, L1 tier from power level)
| |-- Agent A (1M) -- Sub-agent A1, A2, ... (L2 tier)
| |-- Agent B (1M) -- Sub-agent B1, B2, ... (L2 tier)
| |-- Agent C (1M) -- Sub-agent C1, C2, ... (L2 tier)
| |-- ... (no cap)
스웜 vs. 군대: 스웜은 하나의 컨텍스트 창을 하위 에이전트들 사이에 나눕니다(하나의 두뇌, 분할됨). 군대는 각 1계층 구성원에게 자체 창을 제공합니다. 이 차이가 이 스킬의 핵심입니다.
사용 시기
- 여러 파일에 걸친 대규모 리팩터링
- 다중 파일 색상 / 스타일 / 이름 / API 마이그레이션
- 광범위한 코드베이스 감사(보안, 접근성, 성능, 데드 코드)
- 벌크 콘텐츠 생성 또는 변환
- 동시에 실행할 수 있는 6개 이상의 독립적인 작업 단위가 있는 모든 작업
사용하지 말아야 할 시기
- 6개 미만의 독립적인 작업 단위인 경우 — 그냥 직접 수행
- 각 단계가 이전 단계의 출력을 필요로 하는 강한 순차적 종속성이 있는 경우
- 단일 파일 변경
- 모든 출력에서 일관된 작성자 목소리가 필요한 작업(병렬 에이전트는 드리프트 발생)
작업이 명확하게 적합하지 않은 경우, 군대를 가동하는 대신 인라인으로 수행할 것을 제안하고 말합니다.
- 모든 1계층 에이전트는 반드시 2명 이상의 하위 에이전트를 생성해야 합니다. 예외는 없습니다. 하위 에이전트가 없는 1계층 에이전트를 배포하려는 경우 중단하고 재구성하십시오.
- 절대 조용히 군대 규모를 줄이지 마십시오. 사용자가 선택한 계층을 일치시키십시오. 반드시 이탈해야 하는 경우 그 이유를 명확히 말하십시오.
2b. 절대 조용히 모델을 다운그레이드하지 마십시오. 모든 에이전트 호출에 사용자가 선택한 전력 레벨에 따라
model:을 명시적으로 전달하십시오. 생략하면 세션 모델을 상속받는데, 이는 조용한 Max Power 청구입니다. - 하위 에이전트 배포 지침은 1계층 브리핑 내부에 있어야 합니다. 누락되면 하위 에이전트가 생성되지 않습니다.
- 에이전트 완료 시 보고:
[Agent N/M complete] name: X files modified, Y flags. - 군대 계획을 표시하고 배포 전에 배포 게이트를 통과시키십시오(전체 모드). 빠른 모드는 내부적으로 계획을 구성하지만 여전히 게이트를 통과합니다.
- 각 웨이브 후: 빌드와 유령 완료 검사를 실행하십시오(Verify 참조). 에이전트의 녹색 보고서는 주장일 뿐 증거가 아닙니다.
- "계속" / "멈추지 마" = 연속 모드: 하나가 완료되는 즉시 새 에이전트를 시작하십시오. 기다리지 말고 다시 묻지 마십시오.
군대 규모
시작하기 전에 계층을 확인하십시오. 다음 표를 제시하십시오:
| Tier | L1 Agents | Total w/ Sub-agents | Est. Tokens |
|--------------|-----------|---------------------|--------------|
| Conservative | 3 | ~9 | ~200-500K |
| Standard | 5-10 | ~15-30 | ~500K-1.5M |
| Aggressive | 10-20 | ~30-60 | ~1.5-4M |
| Maximum | 20-50+ | ~60-100+ | ~4M+ |
| Custom | you pick | you pick | varies |
"그냥 해"의 경우 기본값은 **표준(Standard)**입니다. 정찰(3단계) 후 발견된 내용에 따라 특정 숫자를 권장하십시오. 예: "6개 도메인에 걸쳐 35개 파일 → 공격적(Aggressive): 8명의 L1 에이전트, 각각 2-3명의 하위 에이전트(총 ~22명, ~2M 토큰). 조정하시겠습니까?" 토큰 추정치는 대략적이며 작업 복잡도에 따라 확장됩니다.
전력 레벨
크기는 에이전트 수를 설정하고, 전력은 어떤 모델을 사용할지 설정합니다. 한 질문으로 둘 다 물으십시오(AskUserQuestion이 잘 작동합니다 — 한 번의 호출로 크기와 전력이라는 두 가지 질문). 사용자가 이미 전력 레벨이나 명시적 모델을 지정한 경우 건너뛰십시오.
| Power Level | Commander | Layer 1 | Layer 2 | Best For |
|---------------------|--------------------|---------|---------|-------------------------------------------------|
| Max Power | Fable/Opus (session)| Opus | Opus | gnarly refactors, correctness-critical migrations|
| Heavy (recommended) | Fable/Opus (session)| Opus | Sonnet | most large tasks — smart orchestration, fast exec|
| Balanced | Fable/Opus (session)| Sonnet | Sonnet | mechanical migrations with clear patterns |
| Economy | Fable/Opus (session)| Sonnet | Haiku | high-volume, dead-simple find/replace |
규칙:
- 지휘관은 항상 세션 모델(Fable 또는 Opus, 사용자 선택)이며 위임되지 않습니다. 세션이 Sonnet 또는 Haiku를 실행 중인 경우 배포 전에 사용자에게 전환하라고 알리십시오(
/model또는claude --model fable). 지휘관 품질은 군대 품질의 상한선입니다. - 모든 에이전트 호출에 모델을 명시적으로 전달하십시오: 팀 구성원의 경우
model: "<L1 tier>"; 1계층 브리핑은 하위 에이전트에 대해model: "<L2 tier>"를 지시합니다. - 모든 전력 레벨에서 에이전트별 승격이 허용됩니다: 무겁거나 복잡한 파일(1000줄 이상, 복잡한 로직)은 해당 하위 에이전트를 한 단계 올릴 수 있습니다. 군대 계획에 승격을 명시하십시오.
- 감사 웨이브는 전력 레벨에 관계없이 Opus에서 실행됩니다 — 실행자의 작업에 대해 새롭고 더 강력한 검토를 수행합니다. 알림 웨이브는 Haiku로 낮출 수 있습니다.
프로토콜
모드: 범위가 이미 구체적인 경우(파일 경로, 정확한 변경 사항, 계층) 3단계(빠른 모드)로 건너뜁니다. 그렇지 않으면 1단계(전체 모드)부터 시작합니다.
1단계: 접수(전체 모드)
사용자가 이미 컨텍스트를 제공한 경우 한 줄로 확인하십시오: "목표: [X]. 범위: [Y]. 계층: [Z]. 전력: [P]. 시작합니다." 그렇지 않으면 다음을 요청하십시오: 목표(한 문장), 범위(파일/디렉토리/"모두"), 제약 조건(X를 건드리지 마, Y와 일치), 계층, 전력 레벨.
2단계: Git 체크포인트
git status— 커밋되지 않은 변경 사항 경고, 스태시/커밋 제안.git checkout -b agent-army/checkpoint-{timestamp}를 실행한 다음 다시 전환합니다. 이것이 롤백 포인트입니다.- Git 저장소가 없습니까? 안전망이 없다고 경고하고 명시적 확인을 받으십시오.
3단계: 정찰
- Grep / Glob / Read를 사용하여 영향을 받는 모든 파일을 찾습니다.
- 작업 단위 수를 셉니다.
- 각 파일에 대해
wc -l을 실행합니다. 500줄 이상의 파일을 **무거움(heavy)**으로 표시 → 단독 할당. - 도메인별로 분류합니다(디렉토리, 가져오기 그래프, 파일 형식, 명명 패턴 기준).
- 공유 종속성을 식별합니다 — 도메인 간에 가져오는 기반 파일(foundation files). 이 파일을 먼저 처리합니다(5단계).
- 빌드 명령을 식별합니다(package.json, Makefile 등).
출력: Files: N | Heavy: [list] | Domains: [list] | Shared deps: [list] | Build cmd: [cmd]
4단계: 구성
- 공유 종속성을 위한 기반 에이전트(Foundation Agent) — 종속자가 충돌하지 않도록 병렬 웨이브 전에 실행됩니다.
- 1계층: 도메인당 하나의 에이전트; 큰 도메인은 여러 에이전트로 나눕니다.
- 2계층: L1 에이전트당 2명 이상의 하위 에이전트, 파일 수가 아닌 가중치 파일 로드(weighted file load) 기준으로 할당:
- 작음(<200줄): 하위 에이전트당 2-3개
- 중간(200-500): 하위 에이전트당 1-2개
- 무거움(500+): 하위 에이전트당 1개, 단독
- 모든 에이전트 이름을 지정합니다. 모든 파일을 정확히 하나의 하위 에이전트에 할당합니다 — 중복 없음, 누락 없음.
군대 계획을 출력합니다. 전체 모드: "진행하시겠습니까?" 일시 중지; 빠른 모드: 한 줄 요약 후 배포.
배포 게이트
배포 전에 응답에 다음 체크리스트를 출력하십시오. 머리 속으로 확인하지 말고 작성하십시오.
DEPLOYMENT GATE:
[ ] 모든 L1 브리핑에 "You MUST spawn N sub-agents" 포함
[ ] 모든 하위 에이전트가 특정 파일 할당과 함께 명명됨
[ ] 모든 파일이 정확히 하나의 하위 에이전트에 의해 소유됨(중복 없음, 누락 없음)
[ ] L1 브리핑에 전체 하위 에이전트 배포 지침 포함
[ ] 계층이 사용자 선택과 일치
[ ] 전력 레벨 설정: 모든 L1 호출에 `model: "<L1 tier>"`; 모든 브리핑에 L2 계층 및 승격 포함
모두 통과(PASS)해야 합니다. 하나라도 실패(FAIL) 시 배포 전에 계획을 수정하십시오.
5단계: 배포
- 기반 에이전트를 먼저(있는 경우) L1 계층으로 실행합니다. 완료될 때까지 기다립니다.
- 모든 1계층 에이전트를 병렬로 시작합니다 — 모든 호출에
run_in_background: true및model: "<L1 tier>"를 사용하여 단일 메시지로 전송합니다. - 각 L1 에이전트는 브리핑에 따라 L2 하위 에이전트를 병렬로 생성합니다.
- 각 완료를 보고합니다:
[Agent N/M complete] name: results.
6단계: 검증
- 재스캔 — 3단계 검색을 다시 실행하여 남은 위반 사항을 확인합니다.
- 유령 완료 검사 —
git diff --stat를 실행하고 에이전트 보고서와 교차 참조합니다. "완료, N개 파일 수정됨"이라고 보고했지만 일치하는 diff가 없는 에이전트는 거짓말을 했거나 아무것도 하지 않은 것입니다 — 다시 파견하십시오. 보고서가 아닌 diff를 신뢰하십시오. - 빌드 — 빌드 명령을 실행합니다. PASS/FAIL을 기록합니다.
- 보고서에서 **팀 간 플래그(flags)**를 해결합니다.
- 군대 보고서를 출력합니다:
Agents: N | Files modified: N (diff-confirmed) | Skipped: N | Build: PASS/FAIL
Flags: [list] | Phantom completions caught: N | Rollback: git checkout agent-army/checkpoint-{timestamp}
웨이브
각 웨이브는 새롭고 더 작고, 다르게 특화된 군대입니다. 각 웨이브 전에 사용자 승인을 위해 일시 중지하십시오. 최대 4개 웨이브.
| Wave | Name | Trigger | Purpose |
|---|---|---|---|
| 1 | 실행(Execute) | 항상 | 변경 사항 적용 |
| 2 | 감사(Audit) | 빌드 실패, 남은 위반, 20개 이상 파일, 또는 플래그 > 0 | 새로운 에이전트가 Wave 1을 정확성/엣지 케이스 검토 |
| 3 | 전파(Propagate) | 변경 사항이 API/타입/인터페이스에 영향; 테스트나 문서가 이전 패턴 참조 | 테스트, 문서, 설정, 다운스트림 호출자 업데이트 |
| 4 | 알림(Notify) | 사용자 동의 시 | PR 설명, 변경 로그, Slack 요약 초안 작성 |
각 웨이브의 보고서는 다음 웨이브의 정찰 자료입니다. 각 웨이브 후 검증을 다시 실행하십시오. 재스캔이 깨끗하고 빌드가 통과하거나 4개 웨이브에 도달하면 중지하십시오.
재개 / 스크래치패드
다중 웨이브 또는 중단 가능한 실행의 경우 Wave 1 후에 .army-state.md를 작성하십시오: 수정된 파일(diff 확인됨), 열린 플래그, 해결되지 않은 문제, 결정 사항. 실행이 중단되면 다음 호출 시 이 파일을 읽고 재시작하는 대신 마지막으로 깨끗한 웨이브부터 재개합니다. 단일 웨이브 작업의 경우 건너뜁니다.
1계층 프롬프트 템플릿
이는 생성된 에이전트가 실제로 보는 내용입니다 — 스킬에서 가장 중요한 섹션입니다.
You are [AGENT_NAME], specialist on [DOMAIN].
Objective: [one sentence]
Approved patterns: [exact values — hex codes, class names, API shapes]
Forbidden patterns: [what to remove/avoid]
Your files: [absolute paths with line counts]
Rules: [constraints]. Skip files already using approved patterns (idempotency).
Flag issues outside your files in "Flags for Commander" — do NOT fix them.
CRITICAL: You MUST use the Agent tool to spawn the sub-agents listed below. Do
NOT do the work yourself. Do NOT skip spawning. Deploy ALL sub-agents in a single
message with multiple Agent tool calls, passing model: "[L2_TIER]" on every call
[note escalations: except "NAME" which gets model: "[higher tier]"].
Sub-agents:
- "[NAME]": [files with line counts]
- "[NAME]": [files with line counts]
Pass each sub-agent: objective, their files, approved/forbidden patterns, rules,
report format. After all complete, aggregate their reports and verify (by re-reading
or grepping) that no forbidden patterns remain in your domain before reporting back.
2계층 프롬프트 템플릿
You are [SUB_AGENT_NAME], working under [TEAM_MEMBER_NAME].
Objective: [one sentence]
Files you own: [absolute paths with line counts — touch only these]
Approved / Forbidden patterns: [exact values to use and remove]
Rules: [constraints]. Skip files already correct. Flag issues outside your files —
do NOT fix them.
Process: read each file fully → check idempotency → apply approved, remove forbidden
→ re-read to confirm no forbidden patterns remain.
Report: Files Modified (file: N replacements), Files Skipped (already correct),
Flags for Commander, Issues, Status (COMPLETE/PARTIAL/FAILED).
보고서 형식
모든 에이전트는 다음을 반환합니다:
## Report: [Name]
Files Modified: [file: N replacements]
Files Skipped: [file: reason]
Flags for Commander: [issue or "None"]
Issues: [issue or "None"]
Status: COMPLETE / PARTIAL / FAILED
안티패턴
이 스킬이 방지하기 위해 존재하는 실패 모드입니다. 스스로 이러한 행동을 발견하면 중단하고 수정하십시오.
- 유령 팬아웃(Phantom fan-out) — L1 에이전트가 하위 에이전트를 생성하는 대신 스스로 작업을 수행합니다. 속도 이점이 모두 사라집니다. 필수 규칙 1 + 게이트에 의해 적용됩니다.
- 유령 완료(Phantom completion) — 에이전트가 아무것도 편집하지 않고 COMPLETE를 보고합니다. 보고서를 신뢰하지 않고
git diff --stat교차 검사로 포착됩니다. - 조용한 축소(Silent shrink) — 사용자가 공격적(Aggressive)을 선택했는데 조용히 3개의 에이전트를 실행합니다. 항상 이탈 사항을 표면화하십시오.
- 모델 드리프트(Model drift) — 에이전트 호출에서
model:을 생략하여 모든 하위 에이전트가 조용히 지휘관의 모델을 상속받습니다. 사용자가 Economy를 선택했는데 Max Power로 청구되었습니다. 필수 규칙 2b + 게이트에 의해 적용됩니다. - 소유권 중복(Overlapping ownership) — 두 하위 에이전트가 동일한 파일을 편집 → 충돌 및 편집 손실. 게이트의 정확히 하나의 소유자 규칙으로 적용됩니다.
- 기반 건너뛰기(Skipping the foundation) — 공유 파일이 업데이트되기 전에 종속자를 건드리면 → 연쇄적인 깨진 가져오기. 기반 에이전트가 먼저 실행됩니다.
- 작은 작업에 군대 사용(Army for a small job) — 4개 파일에 9개 에이전트는 더 느리고(오케스트레이션 오버헤드) 토큰을 소모합니다. "사용하지 말아야 할 시기"를 참조하십시오.
오류 처리
- 하위 에이전트 실패 → L1 에이전트가 해당 파일을 재시도하거나 대체 에이전트를 생성합니다.
- L1 에이전트 실패 → 지휘관이 동일한 브리핑으로 대체 에이전트를 생성합니다.
- 빌드 실패 → 체크포인트 브랜치와의 diff를 통해 중단점을 격리한 다음 수정 웨이브를 실행합니다.
- 유령 완료 → 해당 에이전트의 파일을 새 에이전트에 다시 파견합니다.
- 재실행 시 멱등성 → 에이전트가 먼저 이미 적용된 패턴을 확인하므로 군대를 두 번 실행해도 두 번 적용되지 않습니다.
작업 예시
사용자
…
[번역을 위해 잘림]