작업 분할기(Task Splitter) — 가장 저렴하면서 올바른 실행
목표: 품질을 유지하면서 총 비용을 최소화하여 주요 작업을 완료합니다. 두 가지 방법: (1) 각 작업 조각을 처리할 수 있는 가장 저렴한 등급으로 라우팅하고, (2) 동일한 등급의 작업을 하나의 스레드로 배치하여 각 하위 에이전트의 콜드 스타트 컨텍스트 비용을 한 번만 지불합니다.
점수를 매기기 전에 references/routing-rubric.md를 읽고, 배치 프롬프트를 작성하기 전에 references/batch-brief-template.md를 읽으십시오.
엄격한 규칙
- T0 작업은 절대 에이전트를 생성하지 않습니다. 결정론적 단계(설치, mkdir, mv, 설정 값, 생성기 실행)는 메인 스레드에서 인라인으로 실행됩니다. 콜드 스타트 하위 에이전트는 명령보다 더 많은 비용이 듭니다.
- 저렴한 등급에는
subagent_type: "fork"를 사용하지 마십시오. 포크는 항상 부모 모델에서 실행되며model을 무시합니다. 명시적인model과effort와 함께general-purpose(또는 읽기 전용 검색의 경우Explore)를 사용하십시오. - 이 스킬은 모든 에이전트 호출에
effort를 설정하는 것을 명시적으로 승인하며, 등급 테이블을 사용합니다. 항상model과effort를 모두 전달하십시오. - 모델이 아닌 스크립트로 검증합니다. 테스트, 린트, 타입체크 및 빌드는 메인 스레드에서 실행합니다. 스크립트로 확인할 수 있는 코드를 검토하는 데 모델 호출을 사용하지 마십시오.
- 실패한 하위 작업만 한 단계, 한 번만 에스컬레이션합니다. 한 번 에스컬레이션한 후에는 중단하고 사용자에게 질문합니다.
- 같은 파일을 편집하는 두 하위 작업을 같은 웨이브의 다른 배치에 절대 넣지 마십시오.
등급 테이블(기본값 — 라우팅 로그로 조정)
| 등급 | 점수 | 실행 방식 | 일반적인 작업 |
|---|---|---|---|
| T0 | 0 | 메인 스레드, 인라인 셸 | 의존성 설치, 디렉토리 생성, 이름 변경, 환경 변수/설정 값 설정 |
| T1 | 1–3 | model: haiku, effort: low | 기존 패턴을 따르는 상용구, 복사 편집, 간단한 CRUD 연결, 문서, 테스트 픽스처 |
| T2 | 4–6 | model: sonnet, effort: medium | 일반 기능 코드, 컴포넌트, 엔드포인트, 기존 패턴을 따르는 테스트 |
| T3 | 7–8 | model: sonnet, effort: high | 다중 파일 로직, 상태 관리, 통합, 까다로운 버그, 인증/결제/보안 |
| T4 | 9–10 | model: opus, effort: high | 아키텍처, 교차 관심사 설계, 데이터 모델, 어려운 디버깅, 성능/동시성 |
미리보기에 대한 상대적 비용 가중치: haiku = 1, sonnet = 3, opus = 5; 노력 승수 low = 1, medium = 1.5, high = 2.5. T0 = ~0.
워크플로우
단계 0 — 캡처 및 영구 저장
- 주요 작업을 10줄 이내로 다시 설명: 목표, 제약 조건, 승인 기준, 스택, 범위 밖.
- 슬러그(slug)를 파생합니다.
<project>/.claude/task-splitter/에서 기존 원장을 찾습니다(ls .claude/task-splitter/ 2>/dev/null). 이 작업과 일치하고 미완료 하위 작업이 있는 경우 → 그것을 재개(완료되지 않은 작업이 있는 첫 번째 단계로 건너뜁니다). - 그렇지 않으면
templates/split-ledger.md에서<project>/.claude/task-splitter/<YYYY-MM-DD>-<slug>.md를 생성하고 Context 섹션을 채웁니다. 각 단계 후에 업데이트합니다. 계획 모드에서 계획 파일 외부에 파일 쓰기가 허용되지 않는 경우 원장 내용을 계획 파일의## 원장(Ledger)제목 아래에 넣고 승인 후 첫 번째 T0 단계로 실제 파일을 작성합니다.
단계 1 — 가벼운 정찰
분할에 필요한 것만 읽습니다: 매니페스트(package.json, pyproject 등), 진입점, 기능이 수정하는 파일, 재사용 가능한 유틸리티. 광범위한 검색이 필요한 경우 model: haiku, effort: low로 ONE Explore 에이전트를 사용하고 경로와 한 줄 요약만 요청하십시오. 재사용 가능한 유틸리티와 정확한 파일 경로를 원장에 기록하십시오. 이들은 저렴한 에이전트가 재탐색하지 못하도록 하는 컨텍스트 패킷이 됩니다.
단계 2 — 분할
작업을 원자적 하위 작업으로 분할합니다. 각 하위 작업에는 다음이 있습니다:
id (S1, S2…), goal (한 문장), files (정확한 경로, 새 파일 또는 기존 파일),
depends_on (ID), done_check (pnpm test foo와 같은 명령 또는 정확한 기준),
type (짧은 태그: install, scaffold, component, endpoint, test, migration, refactor,
config, docs, debug, design…).
원자적 = 다른 하위 작업에 속하는 결정 없이 하나의 에이전트가 완료할 수 있습니다.
설계 결정은 자체 초기 하위 작업(종종 T4)으로 추출하여 이후 하위 작업이 기계적이고 저렴하도록 합니다.
단계 3 — 점수 및 라우팅
references/routing-rubric.md의 5차원 평가 기준(모호성, 추론 깊이, 영향 범위, 필요 컨텍스트, 참신성; 각 0–2)으로 각 하위 작업의 점수를 매기고, 재정의 규칙을 적용한 다음 점수를 등급에 매핑합니다.
그런 다음 ~/.claude/task-splitter/routing-log.md(있는 경우)를 확인합니다: 특정 type이 최근 3회 실행 중 2회 이상에서 특정 등급에서 에스컬레이션된 경우 한 등급 높여 시작하고; 선택한 등급보다 한 등급 낮은 등급에서 3회 연속 첫 번째 시도에 통과한 경우 등급을 낮추는 것을 고려합니다.
단계 4 — 배치
- 의존성 웨이브를 구축합니다: 웨이브 1 = 충족되지 않은 의존성이 없는 하위 작업; 웨이브 N = 모든 의존성이 이전 웨이브에 있는 작업.
- 각 웨이브 내에서
(model, effort)별로 그룹화한 다음 코드 영역(동일한 기능 폴더/모듈)별로 그룹화하여 하나의 에이전트가 관련 파일을 한 번 로드합니다. - 배치당 제한: ≤6개의 하위 작업 또는 하나의 일관된 영역; 같은 웨이브의 두 배치가 동일한 파일을 편집하지 않음(충돌하는 하위 작업을 같은 배치나 다음 웨이브로 이동).
- 작은 배치 병합: 고립된 T1 하위 작업이 같은 웨이브에 존재하면 다른 T1 배치에 합류; 거의 기계적인 고립된 T1 하위 작업은 대신 인라인으로 수행할 수 있습니다.
- T0 하위 작업은 웨이브 시작 시 단일 인라인 단계로 그룹화됩니다.
단계 5 — 비용 미리보기(승인 게이트)
계획 파일에 다음을 작성합니다(계획 모드 외부에서는 사용자에게 표시):
| 웨이브 | 배치 | 모델/노력 | 하위 작업 | 예상 비용 |
|------|-------|----------------|----------|-----------|
| 1 | 인라인| main / shell | S1, S2 | ~0 |
| 1 | B1 | haiku / low | S3, S4 | 2 |
| 1 | B2 | sonnet / medium| S5 | 4.5 |
| 2 | B3 | opus / high | S6 | 12.5 |
합계 ≈ 19 단위 (모두 opus/high 기준 ≈ 75 단위 → ~75% 저렴)
예상 비용 = 하위 작업 수 × 모델 가중치 × 노력 승수. 절감액을 확인할 수 있도록 모두 opus/high 기준선을 포함하십시오. 계획 모드에서는 ExitPlanMode로 종료하고, 승인 전에 실행하지 마십시오.
단계 6 — 실행
각 웨이브에 대해 순서대로:
- 웨이브의 T0 인라인 단계를 실행합니다.
- 웨이브의 모든 배치를 하나의 메시지로 실행(병렬 에이전트 호출):
Agent(subagent_type: "general-purpose", model: <등급 모델>, effort: <등급 노력>, description: "<웨이브>/<배치>: <짧은 설명>", prompt: <간략한 내용>). 모든 브리프는references/batch-brief-template.md에서 작성합니다. 공통 프리앰블은 모든 배치에서 바이트 단위로 동일해야 합니다(프롬프트 캐시에 친화적) — 가변 콘텐츠는 그 뒤에 배치합니다. - 다음 웨이브를 시작하기 전에 웨이브의 모든 배치가 보고할 때까지 기다립니다. 보류 중인 에이전트의 결과를 추측하여 기록하지 마십시오.
- 각 배치의 상태와 보고된 파일로 원장을 업데이트합니다.
단계 7 — 검증 및 에스컬레이션
- 각 웨이브 후에 메인 스레드는 하위 작업의
done_check명령과 프로젝트의 저렴한 전역 검사(타입체크 / 린트 / 영향 받은 테스트)를 실행합니다. - 실패한 하위 작업은 한 등급 높은 단독(또는 같은 새 등급의 다른 실패와 함께) 재실행되며, 실패 출력과 이전 에이전트의 보고서가 첨부됩니다.
- 하위 작업당 최대 한 번의 에스컬레이션. 여전히 실패하면 중단하고 짧은 진단과 함께 사용자에게 질문합니다. T4 실패는 바로 사용자에게 전달됩니다.
단계 8 — 기록 및 학습
- 원장을 완료로 표시: 하위 작업별 최종 등급, 통과/에스컬레이션, 변경된 파일.
- 하위 작업별로 한 줄씩
~/.claude/task-splitter/routing-log.md에 추가합니다(폴더/파일이 없으면 생성, 스킬의 git 저장소 내부에는 절대 안 됨):YYYY-MM-DD | <프로젝트> | <유형> | <시작 등급> | <최종 등급> | first-pass|escalated|failed - 사용자에게 10줄 이내로 보고: 수행된 작업, 최종 비용 단위 대 기준선, 에스컬레이션, 남은 문제.
출력 규칙
- 메인 스레드를 가볍게 유지: 에이전트는 파일 내용이 아닌 짧은 보고서를 반환합니다.
- 분할 및 비용 미리보기에는 사용자에게 산문이 아닌 표를 제공합니다.
- 전체 작업 점수가 총 3점 이하이거나 하위 작업이 2개 이하인 경우 그렇게 말하고 직접 수행하십시오 — 분할하는 것이 절약하는 것보다 더 많은 비용이 듭니다.