auto-dev — 이슈를 구현하고 병합하는 지속적인 워커 팩토리
기능 설명
implement-issue는 계획된 하나의 이슈를 준비된 PR로 만들고, merge-pr는 하나의 PR을 병합합니다. auto-dev는 이를 대규모로 감독합니다: N개의 백그라운드 워커가 각각 하나의 이슈를 처음부터 끝까지 담당합니다(implement-issue <N> → merge-pr <PR>). 워커의 PR이 병합되는 즉시 해당 워커는 종료되고, 큐의 다음 이슈에 새 워커가 투입됩니다. 따라서 사용자가 일일이 관리하지 않아도 N개의 이슈가 동시에 진행됩니다.
이것이 단순한 "루프로 실행"과 다른 점은 오케스트레이션에서 비롯되는 가치입니다:
- 충돌 회피 — 각 동시 워커는 서로 다른 코드 영역의 이슈를 할당받으므로 브랜치 충돌이 드뭅니다.
- 순서 지정 — 작고 독립적인 이슈를 먼저 처리합니다(빠른 성과, 충돌 감소), 그다음 중간 크기. 대형/초대형 및 수동 QA는 기본적으로 제외됩니다.
- 강제 병합 — 워커는 "PR 준비 완료"에서 멈추는 경향이 있습니다(반쪽짜리 작업). auto-dev는 모든 신호에서 GitHub의 실제 병합 상태를 확인하고, 지연된 워커를 다시 구동합니다.
- 범위 외 캡처 — 워커가 관련 없는 버그를 발견하면
implement-issue의 예외 규칙에 따라 인라인으로 수정합니다(해당 PR이 이미 수정하는 파일 내에 국한되고, 작으며, 자체 커밋으로). 그 외의 경우에는 버그를 무시하지 않고create-issue를 통해 새 이슈로 등록하며, 이때 공유 이슈 등록 기준(../_shared/filing-bar.md)을 따르므로 N개의 워커가 각자 다른 기준으로 이슈를 등록하는 일이 없습니다. 백로그는 정확성과 처리 가능성을 유지합니다(#410). - 수명주기 정리 — 완료된 에이전트는 종료됩니다. 상태 파일은 재시작 후에도 유지되므로 워커 팩토리를 재개할 수 있습니다.
자율성 계약
사용자는 이 스킬을 시작한 후 자리를 비웁니다. 사용자는 백로그가 소진되는 것을 지켜보며, 각 단계를 승인하지 않습니다. 수동 개입 없이 실행합니다: 합리적인 기본값을 선택하고, 명시하고, 계속 진행합니다. 진정한 차단 요인에서만 멈춥니다:
gh가 인증되지 않았거나, 푸시/병합 권한이 없는 경우.- 처리 가능한 이슈가 없음(필터링 후 큐가 비어 있음) — 백로그가 소진되었다고 보고합니다.
- 워커의 진정한 하드 블로커(통과할 수 없는 테스트, 양측이 동일한 로직을 재작성한 충돌, 스스로 부여할 수 없는 필수 승인). 이를 표면화하고, 병합을 강제하지 않습니다.
진행 상황을 허위로 만들지 마십시오: 체크박스, "준비" 플립, 또는 병합은 작업이 완료되었음을 주장합니다. 각각을 하위 스킬이 요구하는 대로 증거로 뒷받침하십시오. 스쿼시 병합은 되돌릴 수 없는 유일한 행위입니다 — 이는 merge-pr를 통해 초록색이고 병합 가능한 PR에서만 발생하며, 여기서 --admin 재정의를 통해 절대 발생하지 않습니다.
입력
- 동시성
N— 동시 워커 수. 기본값 3(3~4가 최적 범위입니다. 더 많으면 경합이 심해지고 영역을 분리하기 어려워집니다). - 순서 지정 — 기본적으로 작은 이슈→중간 이슈 순으로 처리합니다. 사용자가 지정한 순서를 존중합니다.
- 처리 가능 이슈 집합 — 기본값: (a) 구현 계획이 있는 열린 이슈, (b) 코드 작업(수동 "QA"/"수동 확인" 제외), (c) 노력 상한선 이하(기본값 ≤ 중간). 범위 축소를 존중합니다("
studio이슈만", "priority: high레이블"). - 하트비트 — 일반적으로 동적 모드에서
loop를 통해 실행되므로, 루프의 자체 조정 웨이크업이 하트비트 역할을 합니다. 직접 호출하는 경우 자체 웨이크업을 설정하십시오. - 모델 티어 — 기본값 계층형, 전부 Opus 아님(토큰 경제 참조): 기계적/문서 작업에는 가장 저렴한 모델, 일반 버그에는 중간 모델, 교차 영역/어려운 작업 및 실패 에스컬레이션에는 최상위 모델을 사용합니다. 단일 비용 레버 중 가장 큽니다. 재정의를 존중합니다("모든 것을 Opus로", "모든 것을 Sonnet으로").
토큰 경제 — 워커 팩토리를 저렴하게 운영
장기 실행의 비용은 ~83% 턴당 컨텍스트 캐시 읽기, ~16% 출력입니다. 사고 비용이 아니라 컨텍스트 볼륨 × 턴 수에 대한 비용을 지불합니다. 다음 규칙을 적용하십시오. 전체 근거와 측정은 references/token-economics.md에 있습니다.
실제 19회 병합 실행(.NET/Blazor 리포지토리, N=3, 21개 워커 세션, 8억 6300만 토큰)에서 측정: 세션당 224턴 · 컨텍스트 30K → 350K · 턴당 평균 컨텍스트 181K · 턴당 0.55 도구 호출. 캐시 읽기는 토큰의 98.3%였습니다. 비용 = 턴 수에 따른 컨텍스트 크기의 합계이므로, 후반 턴은 초반 턴보다 약 10배 비싸고 턴 수는 초선형입니다. 두 요소를 동시에 증가시킵니다. 직관이 아닌 이 기준으로 레버의 순위를 매기십시오.
해당 헤드라인은 워커 세션만 집계합니다 — 오케스트레이터는 청구서의 1/3을 차지했습니다. 감독자 자신의 트랜스크립트를 동일한 롤업에 통합한 결과: 한 세션, 551개의 어시스턴트 메시지, 메시지당 평균 컨텍스트 ~210K, 실행 목록 등가 비용의 33% — 최상위 워커 세션을 모두 합친 것보다 많으며, 19회 병합 전체를 거치며 한 번도 압축되지 않았습니다. 워커 비용도 같은 방식으로 왜곡됩니다: 37개 워커 세션 중 상위 3개가 모든 워커 비용의 32%를 차지했으며, 최악의 경우 중간 티어의
effort: medium이슈였으므로 레이블이나 티어가 이를 예측하지 못했습니다. 두 측정값과 이를 제한하는 두 개의 계산된 예산은 references/token-economics.md § 세션 길이에 있습니다.
1. 각 워커를 두 개의 하위 에이전트로 분할: 구현, 그다음 병합 — 측정 가능하게 효과가 있었던 유일한 레버입니다. A/B 검증됨, 모든 워커 토큰의 약 11%. 1단계(/auto-dev-worker <N>)는 준비된 PR에서 멈춥니다. 2단계(/auto-dev-merge <PR>)는 새로운 컨텍스트에서 병합합니다.
| 병합 단계 | 턴 수 | 평균 컨텍스트/턴 | 캐시 읽기 |
|---|---|---|---|
| 이전 (18개 워커, 구현 세션 내) | 평균 27 | 247K | 워커당 6.6M |
| 이후 (v2 2단계, 새 세션) | 24 | 71K | 1.7M |
거의 동일한 턴 수이므로 턴당 컨텍스트가 전체 차이입니다: 병합 단계에서 -74%, 총 워커 비용의 약 11%. PR 번호는 1단계 프롬프트가 지정한 파일을 통해 단계 간에 전달합니다(보고서 줄을 구문 분석한 다음 gh pr list --head로 대체). 보너스: 기준 실행에서 관찰된 두 가지 게시 완료 웨지는 모두 긴 세션의 후반 턴에서 발생했습니다. 더 짧은 세션은 웨지가 적습니다.
2. 도구 호출 배치 — 시도했지만 효과가 없었습니다. 여기서 이득을 기대하지 마십시오. 예제와 함께 강력한 배치 규칙을 워커 프롬프트에 추가하고 A/B 측정했습니다: 밀도가 0.556 → 0.537 호출/턴(1단계) — 즉 변화 없음. 규칙을 유지하십시오(비용이 들지 않음) 하지만 비용 절감을 예산에 반영하지 마십시오. 진단: 1.0 미만의 밀도는 배치될 수 있는 호출이 없다는 의미가 아닙니다. 턴의 약 45%는 도구 호출을 전혀 하지 않습니다 — 추론/설명 턴이며, 나머지 대부분은 진정으로 순차적입니다(편집 → 빌드 → 오류 읽기 → 수정). 회수 가능한 낭비는 도구 호출을 생성하지 않는 턴이며, 이는 배치 문제가 아니라 출력 장황성 문제입니다. 이를 해결하려면 장황성(사고 길이, 단계 간 설명)을 공격하고, 호출/턴을 측정하여 개선 여부를 확인하십시오.
3. 큰 명령 출력을 컨텍스트 밖으로 유지 — 4,262토큰 → 전체 테스트 실행당 ~2토큰으로 측정됨. 전체 dotnet test 출력은 약 17K자이며 이후 모든 턴에서 다시 읽힙니다. 지침: 파일에 로그하고, EXIT + 개수만 컨텍스트에 넣고, 실패 시에만 파일을 grep하십시오. 명시적으로 tail/head를 통해 명령을 파이핑하는 것을 금지합니다. 이는 증거를 자르면서 여전히 턴 비용을 발생시킵니다.
정직한 범위: 실행당 감소는 정확하고 검증되었지만, 총체적 이득은 워커가 테스트 스위트를 실행하는 빈도에 따라 달라집니다. A/B에서 단일 가장 큰 Bash 결과는 25.2K → 10.5K자로 감소한 반면, 턴당 총 도구 결과 볼륨은 거의 변하지 않았습니다(722 → 710자). A/B 이슈가 테스트를 거의 실행하지 않는 문서 작업이었기 때문입니다. 테스트가 많은 이슈에서 실제 효과를 기대하십시오.
4. 모델을 작업에 계층화 — 실제로 티어에 따라 다름, token-economics.md 참조: 중간과 소형 간 차이 ($0.419/Mtok 대 $0.168/Mtok ≈ 2.5배); 최상위와 중간 간 차이 ($2.376/Mtok 대 $0.419/Mtok ≈ 5.7배). 교차 영역 작업에서 우선 순위를 둘 가치가 있습니다. 일상적인 버그에서는 덜 영향력이 있습니다. 이슈 레이블별로 라우팅합니다(런타임의 small/mid/top 트리오에 맞게 이름을 조정, 예: Haiku/Sonnet/Opus):
| 이슈 형태 (레이블별) | 티어 |
|---|---|
문서/템플릿/매니페스트, 형식 및 스냅샷 재생성, priority:low+effort:S 한 줄 가드 | 소형 (예: Haiku) |
대부분의 버그: 이미터/검증기/파서 가드, studio TS, CLI, LSP — effort:S/M; 기본적으로 대형 이슈 | 중간 (예: Sonnet) |
| 낮은 티어가 이 이슈를 초록색으로 만들지 못함 | 최상위 (예: Opus), 반응형 에스컬레이션 (한 번) |
| 교차 영역(여러 영역/이미터), 모호함/설계 — 유지보수자가 어렵다고 알고 있는 작업 | 최상위 (예: Opus), 예측적 최후 수단 |
오케스트레이터(당신)는 최상위 모델을 유지하지만, 턴당 컨텍스트는 작게 유지하십시오(레버 2).
5. 모든 턴에서 다시 읽히는 것을 줄이십시오.
- 고정 프리앰블을 다듬으십시오 — 모든 워커의 모든 턴에서 비용이 지불됩니다. 44KB(~11K 토큰)의
CLAUDE.md는 단일 파일로 한 번 실행에서 5,200만 토큰의 비용이 발생했습니다. 배포/시크릿/kubectl 참조 자료를 연결된 문서로 이동하고 포인터를 남겨 두십시오. - 이슈별 작업 목록 없음 — 무제한으로 성장하며 모든 턴에 다시 주입됩니다. 상태 파일이 유일한 작업 메모리입니다.
- 의도적으로, 계산된 주기로 압축하십시오 — 느낌이 아니라. 주기 정수는 한 곳, references/token-economics.md § 두 예산에 있습니다. 4단계는 상태 파일의 병합 카운터에서 이를 실행하며, 재조사 주기가 이미 사용하는 동일한 계산된 필드입니다. 여기서 숫자를 다시 명시하지 마십시오.
tests/auto-dev-cost-budgets/test.sh가 그렇게 하면 빌드에 실패합니다. 왜 계산되었는가: 비용은 Σ(컨텍스트 × 턴)이므로 실행의 꼬리는 초선형이며, 이 규칙이 대체하는 것 —/context백분율 또는 19회 병합 실행 내에서 절대 실행되지 않을 만큼 느슨한 주기 — 은 아무것도 제한하지 않았으며 단일 세션에서 213달러의 비용이 발생했습니다. 항상 집중 지시와 함께 압축하십시오. 예:/compact keep the slot→issue/PR map, merge counter, queue order, filed follow-ups. 압축 //clear/loop재실행 후 첫 번째 작업: 상태 파일을 다시 읽으십시오. - 워커 최종 보고서를 간결하게 유지 — 이후의 모든 조정 턴에서 다시 읽힙니다.
- 무거운 읽기를 일회용
Explore하위 에이전트에 위임 — 파일 덤프는 하위 에이전트와 함께 소멸되어 컨텍스트에 남지 않습니다. - SUPERVISOR 세션을 가볍게 시작 — 하위 에이전트는 감독자의 MCP 세트를 상속받으므로, 당신의 세션에 연결된 모든 서버가 모든 워커의 모든 턴을 탑니다. 워커별 MCP 제거는 더 이상 사용할 수 없습니다(Agent 도구에 스폰별 MCP 구성이 없음). 실행을 시작할 때 한 번만 다듬으십시오.
6. 더 적은 턴을 사용하십시오 (각 왕복이 전체 컨텍스트를 다시 읽습니다).
- 독립적인 도구 호출을 하나의 턴으로 배치 (병렬 읽기/grep/
gh). - 스크립트가 쿼리+분류를 축소 —
scripts/survey.sh,scripts/reconcile.sh. - 짧은 주기로 폴링하지 마십시오 (병합이 임박하지 않은 한) — 불필요한 웨이크업이 모든 것을 다시 읽으며, 약 5분 캐시 TTL을 지나면 전체 캐시 쓰기(1.25배) 비용이 발생하고 읽기(0.1배)가 아닙니다.
- 턴뿐만 아니라 세션도 제한하십시오. 배치는 A/B 테스트되었지만 움직이지 않았으므로(레버 2), 턴당 최적화는 거의 소진되었으며 세션 길이가 남은 변수입니다 — 37개 워커 세션 중 상위 3개가 모든 워커 비용의 32%를 차지했으며, 노력 레이블이나 티어 모두 어떤 세션인지 예측하지 못했습니다. 따라서 1단계 워커는 턴 예산(정수는 references/token-economics.md § 두 예산에 있으며, 여기에 없음)을 가지고
STATUS: PARTIAL로 넘깁니다. 4단계는 이를 새로운 하위 에이전트에서 다시 시작하며, 이것이 절감의 원천입니다 —SendMessage재개는 예산이 폐기하려는 컨텍스트를 유지합니다. 이는 레버 1의 메커니즘, 섹션의 검증된 하나의 이득이며, 단계 경계 대신 길이 경계에 적용됩니다.
측정하십시오 — A/B 없이 레버가 효과가 있다고 주장하지 마십시오. 세 개의 스크립트, 모두 세션 .jsonl 트랜스크립트 디렉토리를 입력으로 받습니다:
scripts/usage_report.py— 모델별 토큰 + 달러 등가. 병합당 토큰 및 **병합당 $**를 추적합니다. ⚠️ 과거 실행을 포함하여 전체 프로젝트 디렉토리를 집계합니다 — 먼저 하나의 실행을 임시 디렉토리에 심볼릭 링크하고, 레이아웃을 유지하십시오: 감독자 세션의<sid>.jsonl과 그<sid>/subagents/디렉토리(<proj>/<sid>/subagents/agent-*.jsonl은 모든 워커 트랜스크립트가 있는 곳이므로, 한 실행의 워커 팩토리는 하나의 id 아래에 있습니다. 상태 파일에서 id를 선택하거나gh타임스탬프를 사용하십시오. mtime은 신뢰할 수 없습니다.).agent-*.jsonl파일을 평평하게 쌓아 올리면하위 에이전트 0으로 읽혀 아무것도 짝지어지지 않습니다.scripts/analyze_cache.py— 세션당 턴 수, 시작 시 컨텍스트 vs 최고점, 턴당 평균 컨텍스트, 도구별 도구 결과 볼륨. 여기서 세션이 왜 비싼지 이유를 볼 수 있습니다.scripts/measure_phase2.py— 각 이슈의 1단계 및 2단계 하위 에이전트 트랜스크립트(보고서 줄의ISSUE:기준)를 짝짓고 비용을 구현 단계와 병합 단계로 분할합니다. 2.0 이전 트랜스크립트에서는 대신 세션 내 병합 핸드오프 턴을 찾습니다. 이것이 레버 1을 증명한 것입니다.
두 가지 메트릭이 대부분의 신호를 전달합니다: 턴당 평균 컨텍스트(후반 턴이 부풀려졌는가?) 및 턴당 도구 호출 수(턴이 실제로 작업을 수행하는가? 기준선 ~0.55 — 레버 2 참조).
작동 방식
┌─────────────────────── auto-dev (당신, 감독자) ───────────────────────┐
│ 상태 파일: 큐 (작은→중간), 진행 중인 슬롯, 완료됨, 등록됨 │
│ 모든 신호 → GitHub과 조정 → 종료된 병합 처리 + 재충전 → N개 유지 │
└───────────────────────────────────────────────────────────────────────────┘
│ 에이전트 할당 (영역 분리) ▲ 구조화된 보고서 / 유휴 알림
▼ │
워커 A ─ implement-issue → [준비] ⇢ 새로운 하위 에이전트 ─ merge-pr ─ 보고 ┐
워커 B ─ implement-issue → merge-pr ─ 보고 ─┤ N개의 백그라운드 에이전트, 각각 하나의 이슈,
워커 C ─ implement-issue → merge-pr ─ 보고 ─┘ 병합 시 종료, 큐에서 교체
워커는 Agent 도구로 생성된 백그라운드 하위 에이전트입니다. 구조화된 보고서(하위 에이전트의 최종 메시지 자체가 보고서이며, 반환될 때 전달됨), 유휴 알림, 그리고 실행 중인 워커에 대한 SendMessage를 통해 통신합니다. 원시 트랜스크립트 파일(<proj>/<your-session>/subagents/agent-*.jsonl)을 절대 읽지 마십시오 — 워커의 출력은 컨텍스트를 폭파시킬 거대한 로그입니다. 보고서
…
[번역을 위해 잘림]