0xVoidw/subagent-allocator

하위 에이전트 할당기

plan.md를 실행 가능한 작업 분담표로 변환합니다: 누가 무엇을 할지, 어떤 모델을 사용할지, 추론 강도(effort)는 어느 정도로 할지, 실패 시 어떻게 업그레이드할지.

비용 절감의 원리는 간단합니다. 계획의 대부분 작업량은 사실 파일 읽기, 코드 검색, 테스트 실행, 명세에 따른 코드 수정입니다. 이러한 작업에는 가장 비싼 모델이 필요하지 않습니다. 비싼 모델은 진정한 판단력이 필요한 소수 작업에만 사용해야 합니다. 이 스킬의 역할은 이 두 가지를 분리하는 것입니다.

입력

1. plan.md의 경로. 제공되지 않으면 현재 디렉토리에서 plan.md / PLAN.md / PLANS.md를 찾고, 없으면 다시 묻습니다.
2. 대상 플랫폼: claude(Claude Code), codex(OpenAI Codex) 또는 both. 명시되지 않으면 현재 실행 환경에 따라 판단합니다. 판단할 수 없으면 한 번 묻습니다.
3. 지향(선택 사항): 절약, 균형(기본값), 안정. 아래 4단계에서 확신이 없을 때 어느 쪽으로 기울일지에만 영향을 줍니다.

플랫폼이 결정되면 해당 참조 파일을 읽습니다. 여기에는 각 플랫폼의 구체적인 모델 이름, 가격 비율 및 effort 단계가 포함되어 있습니다.

• Claude → references/claude.md
• Codex → references/codex.md
• both → 두 파일 모두 읽고, 출력에 두 구성 세트를 나란히 표시합니다.

모델 이름과 가격은 변경될 수 있습니다. 참조 파일이 유일한 정보 출처이며, 기억에 의존하여 모델 이름을 입력하지 마십시오.

프로세스

1. 계획 읽기, 작업 단위로 분할

plan.md의 자체 단계 구분을 따르되, 다음 두 가지 경우에만 조정합니다.

• 분할: 한 단계에 "대량 읽기/검색"과 "판단/코드 수정"이 함께 있는 경우. 읽기 부분을 분리하여 저렴한 하위 에이전트에 할당하고, 요약만 반환하도록 합니다.
• 병합: 여러 연속된 작은 단계가 동일한 파일 그룹을 수정하고 동일한 컨텍스트가 필요한 경우. 하나의 작업으로 합쳐 컨텍스트 재로딩을 방지합니다.

과도하게 분할하지 마십시오. 각 하위 에이전트에는 시작 오버헤드(컨텍스트 다시 읽기, 인계 설명 작성)가 있으며, 몇 분이면 끝나는 작은 작업은 주 에이전트가 직접 실행하도록 하고 문서에 "주 에이전트 직접 실행"으로 표시합니다.

2. 각 작업에 다섯 가지 태그 부여

태그	질문	값
명확도	사양이 이미 확정되어 따르기만 하면 되는가?	명확 / 부분 / 개방
오류 비용	잘못되었을 때 발견하기 쉽고 롤백하기 쉬운가?	낮음 / 중간 / 높음
검증 가능성	테스트, 빌드, 린트, 스크립트로 자동 판단 가능한가?	있음 / 보완 가능 / 없음
읽기량	작업을 시작하기 위해 얼마나 많은 자료를 읽어야 하는가?	적음 / 많음
영향 범위	변경이 국소적인가, 모듈 간/아키텍처에 영향을 미치는가?	국소 / 모듈 간 / 아키텍처

plan.md에 명확하지 않은 부분은 가장 가능성 높은 상황으로 판단하고, 출력의 "가정"란에 기록합니다. 하나하나 멈춰서 묻지 마십시오.

3. 네 가지 등급으로 매핑

각 플랫폼의 구체적인 모델은 참조 파일을 참조하십시오. 여기서는 등급만 정의합니다.

등급	용도	일반적인 작업
T0 경량	명확 + 낮은 비용 + 결과를 바로 확인 가능	파일 검색, 로그 읽기, 테스트 실행 및 보고, 분류, 추출, 요약
T1 표준	명확 + 국소 + 검증 가능	명세에 따른 기능 구현, 특정 버그 수정, 테스트 작성, 문서 작성, UI 구현
T2 주력	부분적으로 명확, 또는 모듈 간, 또는 디버깅 판단 필요	다중 파일 기능, 원인 불명 버그 조사, 코드 리뷰, 하위 에이전트 결과 통합
T3 플래그십	개방형 + 아키텍처 수준, 또는 오류 비용이 높고 자동 검증 불가	아키텍처 결정, 대규모 리팩토링 계획, 다중 제약 충돌 조정, 여러 하위 에이전트 지휘

판단 순서: 먼저 T1으로 가정하고, 아래 또는 위로 이동할 이유가 있는지 확인합니다.

• 아래로 T0으로 이동할 이유: 작업의 본질이 "찾아서 보고"이며, 병합할 코드를 생성하지 않음.
• 위로 T2로 이동할 이유: 명확도가 "명확"이 아니거나, 영향 범위가 "국소"가 아님.
• 위로 T3로 이동할 이유: "개방형 또는 아키텍처 수준"과 "잘못되면 비용이 높음"을 모두 충족해야 함. 하나만 충족하면 T2에 높은 effort 사용.

일반적인 계획에서 T3 작업은 보통 0~2개입니다. 절반이 T3라면 분할을 다시 확인하십시오. 대부분 "읽기"와 "판단"이 함께 묶여 있기 때문입니다.

4. 추론 강도 결정

effort는 모델 교체보다 더 세밀한 조정 수단입니다. 먼저 조정합니다.

• 시작: 항상 참조 파일에서 해당 등급의 기본 시작값을 사용합니다.
• 검증 가능성 = 있음: 시작값을 유지하거나 한 단계 낮춥니다. 모델이 테스트를 통해 자가 검증할 수 있을 때 높은 effort의 이점이 거의 없습니다.
• 검증 가능성 = 없음 그리고 오류 비용 ≥ 중간: 한 단계 높입니다.
• 누군가 실시간으로 결과를 기다리는 경우: 한 단계 낮추고 속도를 우선시합니다.
• 지향이 절약 일 때 확신이 없으면 낮은 값을, 안정일 때는 높은 값을 선택합니다.

high를 초과한 후에 effort를 더 올리면 비용이 종종 바로 상위 등급 모델의 낮은 effort에 가까워집니다. 따라서 업그레이드 단계는 다음과 같습니다.

1. 먼저 검증 수단을 보충합니다(실행 가능한 테스트 또는 검사 명령 제공).
2. effort를 한 단계 높이며, 최대 high까지.
3. 상위 등급 모델로 교체하고, 해당 등급의 최소 시작값부터 effort를 시작합니다.

Codex T0은 예외로, 높은 effort에서도 비용 효율성이 여전히 좋습니다. 자세한 내용은 references/codex.md를 참조하십시오.

5. 품질 보호

비용 절감이 재작업을 대가로 이루어져서는 안 됩니다. 재작업은 처음부터 올바른 모델을 사용하는 것보다 더 비쌉니다. 다음은 "품질 변화가 눈에 띄지 않음"을 보장하는 수단입니다.

• 각 작업에는 완료 기준이 있어야 합니다. 명령어로 작성할 수 있는 것은 명령어로 작성합니다(pytest tests/x, npm run build). 완료 기준을 작성할 수 없는 작업은 등급이 한 단계 올라갑니다.
• 코드 수정 및 중요한 판단은 T1 이상에서 유지합니다. T0은 읽기 전용이거나, 메인 브랜치에 기록되지 않는 항목(보고서, 목록)만 작성합니다.
• 저렴한 모델이 작업을 완료한 후, 한 단계 높은 모델이 diff를 검토합니다. diff 검토는 변경된 부분만 읽으므로 토큰 소모가 적지만 대부분의 문제를 막을 수 있습니다. 이는 각 단계 끝에 별도의 검토 작업으로 배포표에 포함시킵니다.
• 하위 에이전트는 결론만 반환합니다. 역할 설명에 반환 형식과 길이 제한(예: "200자 이내의 요약 + 관련 파일 경로 목록")을 명시하여 긴 출력이 주 에이전트의 컨텍스트를 채우지 않도록 합니다.

6. 실행 순서 정렬

• 서로 의존하지 않는 작업은 병렬 실행 가능으로 표시합니다.
• 가능한 같은 모델의 작업을 함께 배치하고, 단계 사이의 자연스러운 분기점에서 모델을 교체합니다. 중간에 너무 자주 모델을 교체하면 캐시가 손실되어 컨텍스트 비용을 다시 지불하게 됩니다.
• 플랫폼별 주의사항(캐시 소유권, 긴 컨텍스트 추가 요금 임계값 등)은 참조 파일에 있으며, 해당 사항이 있으면 출력의 "주의사항"에 기록합니다.

출력

plan.md와 같은 디렉토리에 plan.dispatch.md를 다음 구조로 작성합니다. 작업이 많으면 테이블은 모든 작업을 유지하고, 역할 카드는 하위 에이전트 작업에만 작성합니다.

# 하위 에이전트 할당: <계획명>

출처: <plan.md 경로>　플랫폼: <claude / codex / both>　지향: <절약 / 균형 / 안정>

## 개요

| # | 작업 | 실행자 | 등급 | 모델 | effort | 의존성 | 병렬 가능 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | … | 탐색자 | T0 | … | … | 없음 | 2번과 |

등급 분포: T0 ×n, T1 ×n, T2 ×n, T3 ×n
주 에이전트: <모델> / <effort>, 담당: <조정, 통합, 최종 검수 등>

## 실행 단계

### 단계 1: <이름> (모델: …)
- 작업 1, 2 병렬 실행
- 단계 종료 검토: <누가, 무엇을 검토>

## 역할 카드

### 작업 1: <이름>
- **역할**: <한 문장 정의, 예: "읽기 전용 탐색자: 이전 인터페이스를 호출하는 모든 위치 찾기">
- **모델 / effort**: … / …
- **목표**: …
- **입력**: <읽을 파일, 디렉토리, 오류 메시지>
- **제약**: <수정하지 말아야 할 것, 따라야 할 규칙>
- **완료 기준**: <명령어 또는 확인 가능한 상태>
- **반환 형식**: <내용 및 길이 제한>
- **업그레이드 단계**: 검증 보충 → effort를 …로 올림 → … / …로 교체
- **선정 이유**: <한 문장, 다섯 가지 태그에 해당>

## 가정 및 주의사항
- <plan.md에 명확하지 않아 이 스킬이 추론한 부분>
- <플랫폼 관련 비용 함정>

## 예상 절감
"모든 작업에 기본 설정으로 주력 등급 사용" 대비 대략적인 추정: <예: "약 절반의 작업이 T0/T1으로 낮춰져, 이 부분의 단가가 1/2에서 1/20까지 감소">

역할 카드의 "목표, 입력, 제약, 완료 기준" 네 가지 항목은 하위 에이전트에 바로 붙여넣을 수 있는 프롬프트입니다. 하위 에이전트가 독립적으로 이해할 수 있도록 작성하십시오. 하위 에이전트는 plan.md의 나머지 부분을 볼 수 없습니다.

"예상 절감"은 규모와 근거만 제공하고, 정확한 백분율을 조작하지 마십시오. 실제 소비는 작업 자체에 따라 달라지므로, 사용자에게 실행 후 사용량 통계를 확인하고 조정하도록 권장합니다.

예시

plan.md에 다음과 같은 단계가 있습니다.

3. utils/ 아래에서 oldLogger를 사용하는 모든 곳을 newLogger로 바꾸십시오. 일부 위치에서 사용자 정의 formatter가 전달된다는 점에 유의하십시오.

처리: 이 단계는 "모든 호출 지점 찾기"(읽기량 많음, 읽기 전용)와 "formatter 특수 사례 처리하며 교체"(코드 수정 필요, 판단 필요한 특수 사례 있음)가 혼합되어 있습니다. 두 작업으로 분할합니다.

#	작업	실행자	등급	effort	이유
3a	모든 oldLogger 호출 지점을 나열하고, 사용자 정의 formatter가 있는 것을 표시	탐색자	T0	시작값	읽기 전용, 누락 시 3b의 grep 검사로 발견 가능
3b	목록에 따라 교체, formatter 특수 사례를 하나씩 적용	구현자	T1	시작값	명세 명확, 완료 기준은 grep -r oldLogger utils/가 비어 있고 테스트 통과

formatter 동작에 대한 테스트가 없다면 3b의 effort를 한 단계 올리고 "가정 및 주의사항"에 명시합니다.