Claude Code 에서 ultracode 를 켜면 결국 가리키게 되는 것은 Workflow 도구입니다. 메인 에이전트가 짧은 스크립트를 써서 여러 서브에이전트의 나누기·검증·합치기를 넘기는 이 도구가 무엇이고, Agent 도구와 무엇이 다르며, 언제 쓰면 좋은지를 정리한 글입니다.
원래는 ultrathink 와 ultracode 의 차이를 확인하던 글의 한 대목이었는데, 그 글의 주제가 깊이와 폭이라는 두 축의 구분이어서 Workflow 만 따로 떼어 적었습니다. 내용은 2026년 11월, Claude Code 2.1.322 기준이고 이 영역은 버전마다 동작이 자주 바뀝니다. 설치된 실행 파일 안의 문자열을 읽은 것과 최근 14일 세션 기록으로 맞춰 본 것이 섞여 있습니다.
Claude Code Workflow 는 무엇인가
ultracode 가 결국 가리키는 것은 Workflow 도구입니다. Workflow 는 메인 에이전트가 짧은 JavaScript 스크립트를 써서, 여러 서브에이전트의 일을 미리 정한 순서대로 돌리는 도구입니다. 메인이 일을 직접 하는 대신, 나누기·검증·합치기를 코드로 적어 넘긴다고 보면 됩니다.
Agent 도구와의 차이: 흐름을 누가 쥐는가
서브에이전트는 원래 Agent 도구로도 부를 수 있습니다(서브에이전트 자체에 대해서는 서브에이전트와 피어 대화 세션의 차이를 정리한 글에 적었습니다). 둘의 차이는 «흐름을 누가 쥐느냐»입니다. Agent 도구는 결과가 하나 돌아올 때마다 메인이 다음 행동을 다시 판단합니다. 그때마다 메인의 컨텍스트와 턴을 씁니다. Workflow 는 반복·조건·병렬을 스크립트가 쥐고, 메인은 모든 일이 끝난 뒤 반환값만 받습니다.
이 차이 덕분에 무거운 읽기는 서브에이전트의 컨텍스트 안에서 끝나고 사라지며, 메인에는 결론만 남습니다. 이 성질은 예전에 무거운 읽기를 서브에이전트에 두고 메인에는 결론만 남기는 방식을 정리하면서 얻으려던 것과 같은 방향이라는 생각이 들었습니다.
부품과 한도
스크립트에서 쓰는 부품은 많지 않습니다.
agent(프롬프트, 옵션): 서브에이전트 하나를 부릅니다. 스키마를 주면 정해진 모양의 데이터로만 답하고, 모델·노력 수준·에이전트 타입을 호출마다 정할 수 있습니다.parallel(...): 여러 일을 동시에 돌리고 전부 끝날 때까지 기다립니다.pipeline(...): 항목마다 단계를 잇되, 단계 사이에서 다른 항목을 기다리지 않습니다. 그래서 전체 시간이 가장 느린 항목 하나의 길이만큼 걸립니다.phase·log: 진행 상황을 표시합니다.
Workflow 는 백그라운드로 돌고, 끝나면 알림이 옵니다. 각 에이전트의 반환값은 기록 파일(journal)에 남고, 스크립트를 고쳐 다시 돌리면 바뀌지 않은 앞부분은 저장된 결과를 재사용합니다. 같은 스크립트가 같은 결과를 내야 이 재사용이 성립하기 때문에, 스크립트 안에서는 Date.now() 와 Math.random() 이 막혀 있습니다. 처음에는 왜 막았는지 의아했는데, 재사용 구조를 알고 나니 자연스러운 제약이었습니다.
한도는 동시 실행 min(16, CPU 수−2)개, 한 워크플로우에 에이전트 총 1000개, 한 번에 넘기는 항목 4096개입니다. 이와 별도로 /config 에 «Dynamic workflow size» 지침이 있고, 제 세션은 medium(에이전트 10개 미만 권장)이었습니다.
내장 안내가 권하는 품질 패턴
Workflow 의 내장 안내에는 결과의 품질을 높이는 패턴이 몇 가지 소개돼 있습니다.
| 패턴 | 하는 일 |
|---|---|
| 적대적 검증 | 발견마다 «반박해 보라» 에이전트 여럿 → 다수가 반박하면 폐기 |
| 관점 다양 검증 | 정확성·보안·재현 같은 렌즈를 나눠 따로 검증 |
| 완결성 비평 | «빠진 소스·검증 안 된 주장·안 읽은 문서는?» → 다음 라운드 일감 |
| 빈손까지 반복 | 연속 두 라운드에서 새 발견이 없으면 멈춤 |
| 판정단 | 관점이 다른 시안 여럿 → 채점 → 우승안에 나머지 장점 접붙이기 |
부끄럽지만 제가 직접 돌려 본 것은 parallel 과 스키마를 쓴 구조 하나뿐입니다. 아래 절의 판정에 쓴 워크플로우로, 에이전트 5개가 약 2분 동안 돌았습니다. pipeline, 반복 패턴, 재개는 아직 돌려 보지 않았습니다.
언제 쓰면 좋은가: 2주치 작업 기록으로 확인한 것
동작을 알고 나니 «그래서 나는 이걸 언제 썼어야 했나»가 궁금해졌습니다. 최근 14일 동안의 메인 세션 기록 447개 가운데, 제가 3번 이상 말을 건 세션 133개를 추렸습니다. 그중 포괄적인 조사형으로 보이는 11개를 골라, 에이전트 5개로 짠 Workflow 에게 «이 세션은 ultracode 를 썼어야 했나»를 판정하게 했습니다. 참고로 이 기간 Workflow 를 쓴 세션은 하나도 없었습니다.
결과는 «안 써서 아쉬웠다» 3개, «일부만 아쉬웠다» 3개, «해당 없음» 5개였습니다.
부족했던 것은 축 나누기가 아니라 검증이었습니다
뜻밖이었던 것은 11개 중 8개가 이미 Agent 도구로 조사 축을 나눠 병렬로 맡기고 있었다는 점입니다. 저는 Workflow 의 가치가 «일을 여러 갈래로 나누는 것»에 있다고 생각했는데, 그 부분은 이미 하고 있었습니다. 아쉬운 세션들에 공통으로 없던 것은 두 단계였습니다.
- 반증 단계: «없다», «미정이다», «결정이 필요하다» 같은 주장마다 다른 소스에서 반례를 찾는 것.
- 완결성 비평: «앞 판 보고서의 항목이 다음 판에 다 옮겨졌나, 빠진 소스는 없나»를 보는 것.
그 빈자리에서 실제로 어떤 일이 있었는지 일반화해서 적으면 이렇습니다. 출처 없는 결론이 조사 보고서의 판이 바뀔 때마다 다음 판의 전제로 그대로 옮겨져, 여러 판에 걸쳐 전파됐습니다. 제가 «이건 어디서 나온 거지?»라고 묻고서야 드러났습니다. «X 에는 Y 가 없다»는 부재 주장을 단정했다가, 제가 가져온 캡처로 정정한 일도 있었습니다.
범위를 좁혀 다시 낸 보고서에서는 앞 판의 해당 항목 대부분이 빠져 있었습니다. 한 소스에만 기대 조사하다 다른 소스의 언급을 놓쳐 답을 번복하기도 했고, 측정 없이 코드만 읽고 단언했다가 실제 화면과 달라 번복하기도 했습니다.
곰곰이 생각해 보니 이 실패들은 대부분 확증 편향의 모양을 하고 있었습니다. 결론을 낸 쪽은 그 결론을 뒷받침하는 근거는 잘 찾지만, 반례는 잘 찾지 못합니다. 같은 세션 안에서 «다시 한번 확인해 보자»고 해도 같은 눈으로 같은 곳을 보게 됩니다. 반증(falsification)이 별도 단계로, 그 결론에 지분이 없는 에이전트에게 맡겨져야 하는 이유가 여기에 있다는 생각이 들었습니다. 앞에서 본 적대적 검증과 완결성 비평 패턴이 정확히 이 빈자리를 겨냥하고 있었습니다.
Workflow 가 도울 수 없는 구간
다만 Workflow 를 썼다고 해서 이 세션들이 크게 달라졌을 거라고 단정하기는 어렵습니다. 아쉬운 세션들도 시간 대부분은 사람의 결정, 승인, 외부 상태를 기다리는 대화였습니다. 이 구간은 Workflow 의 대상이 아닙니다.
비용도 있습니다. 한 세션은 max 로 하루 가까이 돌다가 주간 사용량 한도에 걸려 멈췄습니다. 거기에 상시 모드로 검증 에이전트를 더 붙였다면 한도를 더 빨리 썼을 것입니다. 토큰 비용에 대해서는 멀티 세션 토큰 비용을 다룬 글에서 따로 적은 적이 있습니다. ultracode 모드의 «token cost is not a constraint» 는 바로 그 비용 계산을 모델이 내려놓게 하는 문장이라, 켜기 전에 한 번 더 생각해 볼 대목이라는 생각이 들었습니다.
훅과 Workflow 가 맞물리지 않는 곳
덧붙여, 제 개인 Claude Code 설정과는 아직 매끄럽게 맞물리지 않는 부분이 있습니다. 예전에 에이전트가 한 번에 수십에서 백 개 넘게 불어난 사고를 겪은 뒤, Workflow 스크립트가 에이전트 6개 이상이거나 반복문 안에서 에이전트를 부르면 훅이 막고 제 승인을 받게 해 두었습니다. 그런데 앞에서 본 품질 패턴(빈손까지 반복, 여러 에이전트의 반증, 판정단)은 대부분 이 규칙에 걸립니다.
반대로 위임 모델과 노력 수준을 점검하는 훅은 Agent 도구에만 걸리고 Workflow 안의 에이전트에는 걸리지 않습니다. 그래서 max 세션에서 Workflow 를 돌릴 때 스크립트가 에이전트마다 노력 수준을 따로 정하지 않으면, 안쪽 에이전트가 점검 없이 전부 max 로 돕니다. 막히는 쪽이 아니라 비용이 새는 쪽입니다(위임할 때 모델을 낮추는 이야기는 서브에이전트 모델 티어링 글에 적었습니다). 이 충돌들을 어떻게 고칠지는 아직 정하지 못했습니다.
정리하면, Workflow 는 반복·조건·병렬을 스크립트가 쥐고 메인에는 결론만 남기는 도구입니다. 2주치 세션에서 부족했던 것은 일을 나누는 단계가 아니라 반증과 완결성 비평이라는 검증 단계였고, 사람의 결정과 대기가 대부분인 구간은 Workflow 가 닿지 않는 곳이었습니다. ultrathink 와 ultracode 가 각각 무엇을 켜는지, 둘이 왜 깊이와 폭이라는 다른 축인지는 «Claude Code ultrathink 와 ultracode 차이»에 정리했습니다.