AIDive

영상 팩

ultracode 상한 키트: 다섯 가지 설정, 팬아웃 체크리스트, 측정한 쌍들

읽는 데 11분

TL;DR와 결론

  • ultracode는 Claude Code를 더 똑똑하게 만들지 않습니다. 모델에 전달되는 지시문을 바꾸고 안전장치 세 개를 없애므로, 실행이 더 많이 쓰고 더 늦게 멈춥니다.
  • 규칙: 테스트 스위트나 규칙 세트가 출력을 판정하고 작업이 독립적인 조각으로 나뉠 때만 팬아웃하세요. 나머지는 high로 일반 실행합니다.
  • 다섯 가지 설정이 실행을 막습니다. small로 설정한 워크플로 규모 가이드라인, 4로 둔 동시 에이전트 상한, 모든 워크플로 에이전트에 쓰는 더 저렴한 모델 하나, 토글 대신 키워드, 그리고 꺼 둔 사용 한도 자동 계속입니다.
  • 상한을 담은 파일은 settings.json과 ultracode-caps.sh 두 개입니다. 체크리스트는 when-to-fan-out.md, 측정한 쌍들은 paired-runs.csv에 있습니다.
  • 규모 가이드라인은 조언일 뿐 상한이 아닙니다. 저희 실행에서는 5개 미만이라고 되어 있었는데 실행은 9개를 썼습니다.

출처가 말하는 것

키워드 대 토글. 프롬프트에 ultracode를 입력하면 그 작업 하나가 워크플로를 쓰도록 선택됩니다. "use a workflow"처럼 자기 말로 요청해도 같은 선택으로 작동합니다 s1. 키워드는 -p로 전달한 프롬프트, 스탬프가 없는 Agent SDK 입력, 예약된 작업에서는 아무 효과가 없습니다 s1. 토글은 다릅니다. ultracode를 켜면 Claude는 의미 있는 작업마다 워크플로를 계획하고, 요청 하나가 워크플로 여러 개로 이어질 수 있습니다 s1. 문서는 ultracode를 켠 세션이 같은 작업을 끈 상태로 했을 때보다 세션 또는 주간 한도에 더 빨리 도달한다고 덧붙입니다 s1.

주입되는 문장. ultracode가 켜져 있으면 워크플로 작성 참조 문서는 "author and run a workflow for every substantive task by default. The goal is the most exhaustive, correct answer you can produce"라고 말하고, "token cost is not a constraint."라고도 말합니다. 같은 텍스트가 "Ultracode overrides the workflow size guideline"이라는 제목의 공개 이슈에 인용되어 있습니다 s8. 순서대로 이어지는 워크플로는 각각 자기 에이전트 예산을 받으므로, 15개짜리 단계 네 개는 에이전트 60개가 되지만 워크플로 하나도 가이드라인을 어기지 않습니다 s8.

세 가지 안전장치. ultracode는 세 가지 검사를 끕니다. Large workflow 경고가 나타나지 않습니다. 세션의 동시 서브에이전트 제한이 Claude가 Agent 도구로 생성하는 서브에이전트에는 적용되지 않습니다. 자동 권한 모드에서는 첫 워크플로 실행을 승인하라는 요청을 받지 않습니다 s1.

규모 가이드라인. small은 5개 미만, medium은 10개 미만, large는 50개 미만입니다. 기본값은 medium이고, v2.1.271 이상의 Pro 플랜에서는 small입니다. Claude Code는 이를 상한이 아니라 조언으로 모델에 보내므로, 다른 규모를 요구하는 프롬프트가 여전히 우선합니다 s1. 하드 제한은 기본 동시 에이전트 16개와 실행당 에이전트 1,000개입니다. 대형 워크플로 경고는 에이전트 25개 초과 또는 예상 토큰 150만 초과에서 뜨며, 경고만 합니다 s1.

저희 실행. 파일 두 개, 코드 16줄짜리 샌드박스에서 규모 가이드라인을 small로 두고 키워드를 입력한 뒤 읽기 전용 리뷰를 요청했습니다. 실행은 에이전트 9개를 썼습니다. 파인더 2개와 검증 에이전트 7개입니다. 파인더 하나당 약 45.2k 토큰을 읽었습니다. 같은 프롬프트의 일반 실행은 하지 않았으므로 저희만의 쌍 수치는 없습니다.

페어 테스트. 200달러 플랜에서 한 개발자가 일반 실행과 ultracode 실행에 같은 사양을 주었습니다. 둘 다 숨겨진 검사 136/136을 통과했습니다. 일반 실행은 25분에 끝났고 5시간 한도의 8%를 썼습니다. ultracode 실행은 76분에 중단됐고 18%가 사라졌으며, 에이전트는 1,000개가 아니라 두 팀(9개와 3개)에 12개를 썼습니다. 분당 소모는 거의 같았습니다. 멈추지 않았을 뿐입니다 s3.

Pro 플랜의 추가 세 쌍. 단일 에이전트 대 워크플로, 같은 결과: 토큰 115k 대 972k, 52k 대 936k, 102k 대 683k. /usage 미터는 4 대 12, 7 대 12, 4 대 8포인트 움직였고, 작성자는 이를 쿼터 약 두 배, 최대 세 배로 정리합니다. Opus 플랜 스크립트의 소요 시간은 173초 대 178초였습니다. 독립적인 리서치 작업 네 개에서는 병렬이 1.6배 빨랐고 토큰은 2.3배였습니다 s4.

30배 페어. xhigh의 에이전트 하나는 API 가격으로 약 18달러에 1시간 13분이 걸렸습니다. ultracode를 켠 max는 서브에이전트 40개로 9시간 14분, 약 554달러였습니다. 각 한 번씩 실행했고, API 정가 기준이며 구독으로 청구된 것이 아닙니다 s11.

한 쌍은 이렇게 생겼습니다. 공개 테스트 저장소에 같은 작업에 대한 단일 에이전트 대 워크플로 쌍이 하나 있습니다. 단일 에이전트는 181,646 토큰, 워크플로는 1,326,703 토큰을 썼습니다. API 가격 기준 비용은 0.2678달러 대 1.3744달러였습니다. 소요 시간은 43초 대 80초였고, 세션 미터는 +0 대 +12포인트 움직였습니다 s22. 한 쌍일 뿐이므로 법칙이 아니라 모양으로 읽으세요. 문서는 서브에이전트와 워크플로를 토큰 소모 요인으로 꼽습니다. 워크플로가 생성하는 에이전트마다 메인 대화 위에 자기 요청을 보내기 때문입니다 s5. Anthropic의 리서치 팀은 에이전트가 채팅보다 약 4배, 멀티 에이전트 시스템이 약 15배 많은 토큰을 쓴다고 측정했습니다 s20.

값을 하는 곳: Bun. Bun은 11일 동안 계속 돌린 동적 워크플로 약 50개로 Zig에서 Rust로 다시 쓰였습니다. 소스는 Zig 535,496줄이었고, 이식은 시작부터 모든 플랫폼에서 테스트 스위트 100% 통과까지 11일이 걸렸습니다 s19. 심판은 기존 테스트 스위트였습니다.

값을 하는 곳: 버그 사냥. Anthropic은 11만 6천 줄 코드베이스에 버그 70개를 심었습니다. 3회 실행에서 단일 에이전트는 14, 15, 27개를 찾았습니다. 워크플로는 3회 실행 모두에서 66개를 찾았습니다 s24. 이 테스트는 Claude Code가 아니라 API 제품인 Managed Agents에서 진행됐습니다. Anthropic은 비용을 밝히지 않았고 범위가 좁은 작업부터 시작하라고 권합니다 s24. 출시 블로그는 전통적인 코딩 작업 대부분에는 리뷰어 5명의 패널이 필요하지 않다고 말합니다 s2.

폭주한 실행. Max 20x 플랜에서 모델이 작성한 스크립트가 51분 만에 에이전트 221개를 시작했습니다. 첫 세션 한도 오류 뒤에 189개가 더 시작됐습니다. 제보자의 표는 캐시를 포함해 47,465,299 토큰을 집계합니다 s7. 제보자가 단 단서가 둘 있습니다. 나중의 에이전트 189개에는 기록된 모델 응답이 없었고, 병합이 아무것도 반환하지 않아도 스크립트의 폴백이 계속 에이전트를 보냈다는 것입니다. 그 실행은 사용 한도에서의 일시 정지가 생기기 전인 v2.1.266이었습니다 s7. 두 번째 공개 보고는 에이전트 56개와 104개의 워크플로 두 개, 토큰 1,472,855개와 1,752,360개를 설명하는데, 에이전트 160개 중 92개가 세션 한도로 실패했습니다 s21. 제보자는 사용자가 ultracode를 켜지 않았는데도 켜진 것으로 보고됐다고 말합니다.

레버. CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS는 1에서 256 사이의 값을 받으며 v2.1.269가 필요합니다 s10. CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL은 v2.1.296부터 다른 서브에이전트는 자기 모델을 유지한 채 모든 워크플로 에이전트를 한 모델로 실행합니다 s18. autoContinueAtUsageLimit를 켜면 한도에 닿은 실행이 일시 정지했다가 리셋 때 재개하며, 대기는 최대 두 번이고 세 번째에는 에이전트가 실패합니다. 끄면 해당 에이전트가 한도에서 실패합니다 s1. 출시 블로그는 "use 10k tokens" 같은 프롬프트 속 예산이 상한을 정한다고 말합니다 s2. /workflows 보기는 에이전트별 토큰 사용량을 보여 주고 x로 실행을 멈춥니다 s1. /usage는 최근 사용량의 10% 이상을 차지하는 동작을 표시하며, v2.1.299에서 워크플로 경고가 추가됐습니다 s5 s18.

상한 키트

설정 블록입니다. 1번 상한은 규모 가이드라인, 4번 상한은 키워드가 유일한 진입로가 되도록 ultracode를 false로 유지하는 것, 5번 상한은 auto-continue를 끄는 것입니다. .claude/settings.json 또는 아무 settings 파일에 넣으세요. workflowSizeGuideline 키는 v2.1.219부터 모든 settings 파일에서 작동합니다 s1.

settings.json

{
  "workflowSizeGuideline": "small",
  "ultracode": false,
  "autoContinueAtUsageLimit": false
}

settings.json on GitHub

env 줄입니다. 2번과 3번 상한입니다. 자리 표시자를 워크플로 에이전트를 실행할 모델의 전체 id로 바꾸세요.

ultracode-caps.sh

#!/usr/bin/env bash
# Source this file before you launch Claude Code: `source ultracode-caps.sh && claude`.
# These two lines are caps 2 and 3 of the five. Caps 1, 4 and 5 live in settings.json.

# Cap 2: at most 4 workflow agents run at once. The default is 16 (fewer on a machine
# with few CPUs). Accepted values are 1 to 256. Needs Claude Code v2.1.269 or later.
export CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=4

# Cap 3: run every workflow agent on one cheaper model, while your other subagents
# keep theirs. Replace the placeholder with the full model id you want to pay for.
# Needs Claude Code v2.1.296 or later.
export CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL="<your-cheaper-model-id>"

# Optional kill switch for a shared machine: no workflows at all.
# export CLAUDE_CODE_DISABLE_WORKFLOWS=1

ultracode-caps.sh on GitHub

키워드를 입력하기 전에 거치는 체크리스트입니다.

when-to-fan-out.md

# When to fan out: the two-condition checklist

Fan out (use the ultracode keyword in one prompt) only if both answers are yes.

1. Does a test suite or a rule set judge the output?
   - [ ] A suite that already exists and says pass or fail without anyone's opinion.
   - [ ] Or a written rule file the output is reviewed against.
2. Does the job split into independent pieces?
   - [ ] No piece waits on the result of another piece.
   - [ ] Each piece can be checked on its own.

If either answer is no, run plain at high effort. A plain run costs one bill. A
workflow costs one bill per agent.

Jobs that usually pass both tests:
- A port or migration across many files with a test suite as the judge.
- A review of a whole codebase against a rule file.
- A translation of many files with the same prompt.
- A cleanup pass over a pile of similar documents.

Jobs that usually fail one of them:
- A small feature, a bug fix, a refactor of one module.
- Anything where "good" is a matter of taste.
- A chain of steps where each one needs the previous result.

Before you start:
- [ ] Run a slice first (one folder, ten files) and read the token total.
- [ ] Put a budget in the prompt, for example "use 10k tokens".
- [ ] Open /workflows and watch per-agent tokens. Press x to stop.
- [ ] After the run, open /usage and read the share that went to workflows.

when-to-fan-out.md on GitHub

출처에서 가져온 측정된 쌍과 사례를 한 줄씩, 출처 id와 함께 정리했습니다.

paired-runs.csv

source_id,run,measure,baseline,workflow_or_fanout,note
s22,rebuild-your-claude-md pair (rep 2),tokens,181646,1326703,"all four usage fields summed, 14 agent transcripts on the workflow side"
s22,rebuild-your-claude-md pair (rep 2),API cost in USD,0.2678,1.3744,single agent vs workflow
s22,rebuild-your-claude-md pair (rep 2),wall time in seconds,43,80,single agent vs workflow
s22,rebuild-your-claude-md pair (rep 2),session meter points,+0,+12,"/usage before to after: 17% to 17% vs 19% to 31%"
s24,70 planted bugs in 116k lines,bugs found,"14, 15 and 27 (3 runs)","66 in each of 3 runs","Managed Agents, not Claude Code; no cost given"
s19,Bun port from Zig to Rust,test suite passing,,100%,"about 50 dynamic workflows, 11 days, 535,496 lines of Zig"
s6,fixed worker and gate files,tokens for workflow execution and monitoring,100%,about 20%,"self-reported, no plan stated; runs 5 to 6 hours down to 20 to 40 minutes"
s7,runaway run on Max 20x,agents started,,221,"51 minutes; 189 started after the first session-limit error; 47,465,299 tokens including cache"
s21,ultracode reported on without the user enabling it,agents started,,"56 and 104","1,472,855 and 1,752,360 tokens; 92 of 160 agents failed with the session limit"
s20,multi-agent research system,tokens vs a chat,about 4x for an agent,about 15x for multi-agent,Anthropic's own data
s3,same spec on a $200 plan,hidden checks passed,136/136,136/136,"both runs perfect"
s3,same spec on a $200 plan,time and 5-hour limit used,"25 min, 8%","76 min (cut off), 18%","12 agents in two teams (9 and 3)"
s4,Opus plan script,tokens,115k,972k,"Pro plan; /usage 4 vs 12 points; 173 s vs 178 s"
s4,compact script,tokens,52k,936k,"Pro plan; /usage 7 vs 12 points"
s4,Claude.md script,tokens,102k,683k,"Pro plan; /usage 4 vs 8 points"
s4,four independent research jobs,time and tokens,"102 s, about 33k","about 64 s, 76k","parallel 1.6x faster for 2.3x tokens"
s11,Cybercity,time and API cost,"1 h 13 m, about $18 (1 agent)","9 h 14 m, about $554 (40 subagents)","xhigh vs max with ultracode; one run each; API list prices"

paired-runs.csv on GitHub

키트에 대한 참고가 둘 있습니다. ultracode 키는 토글을 켠 채로 세션을 시작하게 되는 경우에만 의미가 있으며, false로 유지하면 팬아웃마다 프롬프트 하나로 직접 결정하게 됩니다. 워크플로를 완전히 끄면 키워드와 토글이 모두 사라집니다. ~/.claude/settings.json에 "disableWorkflows": true를 설정하세요 s1.

월요일에 할 일

  • settings.json을 프로젝트 settings에 복사하고 /config에서 규모 가이드라인이 small로 표시되는지 확인하세요.
  • Claude Code를 실행하는 셸에서 ultracode-caps.sh를 source하고, 자리 표시자 대신 실제 모델 id를 넣으세요.
  • /effort에서 ultracode 토글이 꺼져 있는지 확인하고, 팬아웃이 필요할 때는 프롬프트 하나에 키워드를 쓰세요.
  • 팬아웃하기 전에 when-to-fan-out.md의 두 질문에 답하세요. 하나라도 아니오면 high로 일반 실행합니다.
  • 먼저 일부만 실행해 보고, 작업을 넓히기 전에 /workflows의 토큰 합계를 읽으세요.
  • 프롬프트에 예산을 추가하세요. 예: "use 10k tokens".
  • 첫 실행에서는 /workflows를 열어 두고, 에이전트 수가 예상보다 늘어나면 x를 누르세요.
  • 실행이 끝나면 /usage를 열어 워크플로에 간 비중을 기록하세요.

더 나아가기

모델에게 워커와 게이트를 쓰게 두지 말고 직접 고정하세요. 한 Hacker News 글은 워크플로 실행과 모니터링에 드는 토큰 지출을 이전의 약 20%로 줄였고, 56시간 걸리던 워크플로가 이제 2040분 걸린다고 보고합니다. 자기 보고이며 플랜은 밝히지 않았습니다 s6. 방법은 두 부분입니다. workflow-worker 에이전트 파일은 계획의 한 조각을 받고, 자기 몫에 대한 테스트만 작성하고 실행할 수 있는 좁은 권한을 가집니다. workflow-gate 에이전트 파일은 병렬 에이전트들의 결과를 받고, 직렬 검사는 두 타깃이 있는 Makefile로 옮깁니다. make workflow-serial-gate는 git 트리를 확인하고 바뀐 부분의 테스트를 실행하며, make workflow-final-gate는 전체에 대해 깨끗한 테스트를 실행합니다 s6. 복잡한 계획에서 10분 걸리던 게이트 검사는 같은 글에 따르면 이제 1초 걸립니다. 20%는 실행과 모니터링에 대한 수치이며 계획 작성이나 구현은 포함하지 않습니다. 시도해 보려면 에이전트 파일 두 개를 한 번 작성해 저장소에 두고, 워크플로 프롬프트가 그 파일을 가리키게 하세요.

생성된 스크립트를 믿기 전에 폭주 보고를 읽으세요. 이슈에는 단계별 표와 추가 에이전트 189개 뒤에 있는 하나의 패턴이 나옵니다. 병합 에이전트가 아무것도 반환하지 않으면 스크립트가 원본 목록으로 폴백하고 계속 진행하는 것입니다 s7. 에이전트가 실패하면 멈추는 스크립트를 모델에 요청하세요. 지켜보지 않는 모든 실행에서는 auto-continue를 꺼 두세요.

가이드라인이 지는 이유를 알아 두세요. 이슈 92631은 가이드라인 텍스트와 ultracode 문장을 나란히 보여 주고, 둘이 충돌할 때 왜 뒤의 것이 이기는지 설명합니다 s8. 하드 상한을 원한다면 동시 실행 변수가 동시에 도는 에이전트 수를, 프롬프트의 예산이 그들이 쓰는 양을 제한합니다.

넓은 작업에는 출시 스레드를 활용하세요. 가장 날카로운 첫날 반발은 출시 스레드에 있고, "an exciting new way to burn up as many tokens as possible", "Quantity of output is not the issue right now. Quality is." 같은 댓글이 있습니다 s9. 사람들이 보고하는 성공 사례는 모양이 같습니다. 규칙 파일에 대한 리뷰, 코드베이스 번역, 스캔된 페이지 정리입니다.

Managed Agents는 다른 제품입니다. 버그 70개 테스트는 API 전용인 Managed Agents 동적 워크플로를 썼습니다. API 위에서 만든다면 Anthropic이 권하는 대로 범위가 좁은 작업부터 시작하세요 s24. Claude Code의 설정은 그쪽으로 이어지지 않습니다.

믿으면 안 되는 것. 플랜이나 수치가 없는 쿼터 일화는 전해 들은 이야기입니다. 한 댓글 작성자는 에이전트 6개가 4시간 쿼터를 먹었다고 보고하고, 다른 한 명은 작성자 본인의 클론을 통해 다른 업체의 저렴한 모델로 거의 20억 토큰짜리 이식이 20달러였다고 보고합니다 s23 s9. 어느 쪽도 플랜 위의 Claude Code에 대한 측정이 아닙니다. 숫자는 플랜, 모델, 버전, 작업이 함께 있을 때만 메모에 넣을 가치가 있습니다.

FAQ

키워드는 토글만큼 비용이 드나요? 아니요. 키워드는 작업 하나를 워크플로로 실행합니다. 토글은 의미 있는 모든 작업에 워크플로를 계획하므로 요청 하나가 여러 개가 될 수 있습니다 s1. 에이전트마다 자기 요청을 보내기 때문에 둘 다 대화 위에 비용이 더해집니다 s5.

규모 가이드라인을 small로 설정하면 실행이 에이전트 4개로 제한되나요? 아니요. 모델에 보내는 조언일 뿐이고, 프롬프트나 ultracode 문장이 이를 덮어쓸 수 있습니다 s1 s8. 저희 실행에서는 5개 미만이라고 되어 있었는데 실행은 9개를 썼습니다. 하드 제한은 동시 실행 변수와 직접 누르는 중지입니다.

실행이 사용 한도에 닿으면 어떻게 되나요? autoContinueAtUsageLimit를 켜면 대화형 claude.ai 세션은 실행을 일시 정지하고 v2.1.271부터 리셋 때 최대 두 번의 대기까지 이어 갑니다. 이전 버전은 해당 에이전트를 실패시킵니다 s1. 끄면 에이전트가 한도에서 실패하고 실행이 거기서 끝납니다.

워크플로 에이전트에 왜 더 저렴한 모델을 쓰나요? 워크플로의 대부분은 검사이고, 에이전트마다 자기 요청을 보냅니다. CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL은 모든 워크플로 에이전트를 한 모델에 두고 다른 서브에이전트는 그대로 둡니다 s18. 의존하기 전에 일부 작업으로 결과를 확인하세요.

그래도 ultracode를 쓸 수 있나요? 네, 체크리스트의 두 질문을 모두 통과하는 작업이라면요. Bun의 이식에는 전체 테스트 스위트라는 심판이 있었습니다 s19. 작은 기능이나 버그 수정에는 high의 일반 실행이 기본값입니다.

파일