Claude Code 의 ultrathink 는 그 한 턴만 노력 수준을 xhigh 로 올리는 낱말이고, ultracode 는 생각의 깊이보다 일하는 방식을 바꾸는, Workflow 오케스트레이션을 켜는 낱말이자 모드입니다. 저는 둘 다 «붙이면 더 세게 일한다» 정도로만 알고 있었습니다. 그래서 max 세션에서 두 낱말을 같이 붙이면 비용을 따지지 않고 끝까지 파고드는 상태가 될 거라고 막연히 생각했습니다.

실제 동작을 들여다보니 그 예상은 여러 군데서 어긋나 있었습니다. max 세션에서 ultrathink 는 노력 수준을 바꾸지 않습니다. ultracode 낱말이 붙이는 것은 «이 턴은 Workflow 로 하라»는 안내 한 줄이고, «토큰 비용은 제약이 아니다»라는 문장은 따로 켜는 모드에만 있습니다. 이 글은 두 낱말이 어떻게 동작하는지, 제 예상이 어디서 틀렸는지, 그리고 Workflow 가 무엇이고 언제 쓰면 좋은지를 정리한 기록입니다.

먼저 밝혀 둘 것이 있습니다. 아래 내용은 2026년 11월, Claude Code 2.1.322 기준입니다. 이 영역은 버전마다 동작이 자주 바뀌기 때문에, 시간이 지나면 달라질 수 있습니다. 확인은 두 가지 방법으로 했습니다. 하나는 설치된 실행 파일 안의 문자열과 판정 로직을 읽은 것이고, 다른 하나는 세션 기록 파일에 턴마다 남는 노력 수준(effort) 기록과 안내 첨부를 본 것입니다. 대부분은 실행 파일의 코드를 읽어 확인한 것입니다. 세션 기록으로 실제 동작까지 맞춰 본 것은 그 자리에서 그렇다고 밝히고, 코드로도 조건을 끝까지 확인하지 못한 부분은 따로 적겠습니다.

Claude Code 노력 수준(effort) 다섯 단계

Claude Code 의 노력 수준은 low · medium · high · xhigh · max 다섯 단계이고, 이 순서는 코드에 고정돼 있습니다. Anthropic 공식 문서의 설명으로는 노력 수준이 생각의 양만이 아니라 설명 문장과 도구 호출까지, 응답의 모든 토큰에 영향을 줍니다. 노력 수준이 낮을수록 도구 호출이 줄고 짧아진다고도 적혀 있습니다. 같은 문서의 표에서 xhigh 는 30분 넘게 이어지는 장시간 에이전트·코딩 작업용으로, max 는 가장 깊은 추론과 가장 철저한 분석이 필요한 작업용으로 소개돼 있습니다.

세션의 노력 수준은 /effort <단계> 명령이나 실행할 때의 --effort <단계> 옵션으로 정합니다. 한 가지 눈여겨볼 점은 max 가 설정 파일에 저장되지 않고 그 세션에만 적용된다는 것입니다. 이 사다리를 머릿속에 두면 뒤에 나오는 두 낱말이 각각 어디에 걸리는지가 훨씬 잘 보인다는 생각이 들었습니다.

ultrathink: 한 턴만 xhigh 로 올리는 낱말

발동 조건은 뜻이 아니라 글자입니다

ultrathink 는 프롬프트 글자에 낱말 경계 정규식 \bultrathink\b 가 걸리면 발동합니다. 대소문자는 가리지 않고, 낱말이 어떤 뜻으로 쓰였는지는 보지 않습니다. 이 점은 뒤에서 함정으로 다시 이야기하겠습니다.

발동하면 두 가지 일이 일어납니다. 첫째, 그 턴만 노력 수준을 xhigh 로 올립니다. 여기에는 조건이 둘 있습니다. 현재 노력 수준이 xhigh 보다 낮아야 하고(low · medium · high), 쓰고 있는 모델이 xhigh 를 지원해야 합니다. 둘째, 모델에게 시스템 알림으로 아래 문장을 붙입니다.

plaintext
The user included the keyword "ultrathink", requesting deeper reasoning on this turn. Reason as thoroughly as the task warrants.

올리기만 하고 내리지는 않습니다

올리는 조건이 «xhigh 보다 낮을 때»이기 때문에, 세션이 이미 xhigh 나 max 라면 노력 수준은 바뀌지 않습니다. 특히 max 를 xhigh 로 끌어내리지 않습니다. 저는 처음에 «ultrathink = xhigh» 로만 외워 두고 있어서, max 세션에서 붙이면 오히려 한 단계 내려가는 게 아닌가 하는 걱정도 잠깐 했습니다. 판정 로직을 읽어 보니 그럴 일은 없었습니다.

이 설정은 턴 단위라서 다음 턴에는 원래 세션 노력 수준으로 돌아갑니다. 기능 자체를 끄고 싶다면 환경 변수 CLAUDE_CODE_DISABLE_ULTRATHINK 를 켜면 됩니다.

세션 노력 수준 ultrathink 를 쓴 턴의 노력 수준 안내 문장
low · medium · high xhigh 붙음 (high 에서 실측)
xhigh xhigh (변화 없음) 코드상으로는 붙음 (직접 돌려 보지 않음)
max max (변화 없음) 코드상으로는 붙음 (직접 돌려 보지 않음)

세션 기록에서 확인한 것

조사에 쓴 세션의 기본 노력 수준은 high 였습니다. ultrathink 가 들어간 첫 번째와 세 번째 턴은 effort 가 xhigh 로, 낱말이 없던 두 번째 턴은 high 로 기록돼 있었습니다. 안내 첨부도 첫 번째와 세 번째 턴에만 남아 있었습니다. 코드에서 읽은 «그 턴만 올리고 다음 턴에 돌아온다»는 동작이 기록과 그대로 맞았습니다.

정리하면 high 세션에서의 ultrathink 는 «이 한 턴만 xhigh» 이고, 이것은 그냥 max 보다 한 단계 낮습니다. max 세션에서 붙이면 노력 수준은 그대로 max 이고, 더해지는 것은 기껏해야 안내 문장 한 줄입니다. 다만 쓰는 모델이 xhigh 를 지원하지 않으면 high 에서도 노력 수준은 오르지 않는데, 어느 모델이 xhigh 를 지원하는지는 확인하지 못했습니다.

ultracode: 이름은 하나, 갈래는 둘

ultracode 는 같은 이름 아래 성격이 다른 두 가지가 있습니다. 프롬프트에 낱말로 쓰는 것과, 명령으로 켜 두는 모드입니다. 이 둘을 한 덩어리로 기억하고 있었던 것이 제 오해의 출발점이었다는 생각이 들었습니다.

프롬프트에 쓴 낱말: 그 턴만 Workflow 로

프롬프트에 ultracode 낱말이 있으면 그 턴에만 아래 안내가 붙습니다. 코드에서 읽었고, 세션 기록에서도 확인했습니다.

plaintext
The user included the keyword "ultracode", opting this turn into multi-agent orchestration — use the Workflow tool to fulfill the request.

이 낱말은 노력 수준을 바꾸지 않습니다. 코드에서 턴 단위로 노력 수준을 바꾸는 곳은 ultrathink 의 xhigh 승급 하나뿐이었습니다. 이 동작은 설정 workflowKeywordTriggerEnabled 를 false 로 두면 꺼집니다(기본값은 true).

/effort ultracode on: 끌 때까지 이어지는 모드

두 번째 갈래는 /effort ultracode on 으로 켜고 /effort ultracode off 로 끄는 모드입니다. /effort 도움말에는 이렇게 적혀 있습니다.

plaintext
Ultracode (any effort level, this session only): ultracode [on|off]: dynamic workflows on every task

«any effort level» 이라는 말 그대로, 노력 수준과는 따로 켜는 세션 한정 모드입니다. 다만 실행할 때 --effort ultracode 로 시작하면 사정이 조금 다릅니다. 코드에 ultracode 를 xhigh 로 대응시키는 표가 있어서, 이 경로로 켜면 노력 수준이 xhigh 로 정해지고 모드가 켜집니다. 즉 이렇게 켠 ultracode 는 생각의 깊이로만 보면 max 보다 한 단계 낮습니다.

모드를 켤 때는 다음과 같은 긴 안내가 붙습니다(중간 생략).

plaintext
Ultracode is on: optimize for the most exhaustive, correct answer — not the fastest or cheapest. Use the Workflow tool on every substantive task; token cost is not a constraint. ... Solo only on conversational/trivial turns.

그 뒤로는 여러 턴마다 «Ultracode is still on — use the Workflow tool …» 같은 짧은 안내가 다시 붙고, 끄면 «Ultracode is off — the Workflow tool's standard opt-in rule applies again.» 가 붙습니다. 모드를 켜려면 모델이 지원해야 하고 /config 의 dynamic workflows 가 켜져 있어야 합니다. 조건이 맞지 않으면 «Ultracode needs dynamic workflows enabled» 나 «Ultracode isn't available on <모델>» 같은 오류가 납니다. 노력 수준을 다시 바꾸면 ultracode 가 꺼지는 분기도 코드에 있었는데, 정확히 어떤 조건에서 꺼지는지는 확인하지 못했습니다.

세 가지 설정 비교

설정 모델에 보내는 노력 수준 Workflow 사용 지속 범위
max max 기본 규칙(사용자가 요청할 때만) 세션
ultracode 모드 (--effort ultracode) xhigh 실질적인 작업마다 기본 끌 때까지
ultracode 모드 (/effort max 뒤 /effort ultracode on) 코드상으로는 max (직접 돌려 보지 않음) 실질적인 작업마다 기본 끌 때까지
프롬프트에 ultracode 낱말 바뀌지 않음 그 턴만 그 턴

ultrathink 와 ultracode, 예상이 어긋난 지점

이제 처음의 예상으로 돌아가 보겠습니다. 저는 «max 세션에서 프롬프트에 ultracode 와 ultrathink 를 같이 쓰면, 비용을 따지지 않고 가장 철저하게 일하는 상태가 된다»고 생각했습니다. 동작을 하나씩 놓고 보면 이 예상은 성립하지 않습니다.

ultrathink 는 max 세션에서 노력 수준을 바꾸지 않습니다. ultracode 낱말이 붙이는 문장은 «이 턴은 Workflow 로»뿐입니다. «token cost is not a constraint» 라는 문장은 모드를 켤 때의 안내에만 들어 있습니다. 결국 그 조합으로 얻는 것은 «max 로 생각하면서, 이 한 턴은 Workflow 로 처리하라»는 지시이지, 제가 상상한 «비용 무제한 모드»가 아니었습니다.

지속 범위도 예상과 달랐습니다. 두 낱말은 그 프롬프트 한 턴에만 적용되고 다음 턴에는 저절로 풀립니다. 계속 유지되는 것은 /effort ultracode on 으로 켠 모드뿐입니다. 돌이켜 생각해 보면, 저는 낱말 이름이 주는 인상(«울트라»)을 동작의 크기로 그대로 옮겨 읽고 있었습니다.

ultrathink·ultracode 는 언급만 해도 발동합니다: 쓰는 것과 말하는 것

조사하면서 가장 의외였던 것은 이 대목입니다. 조사 세션의 첫 질문은 ultrathink 가 무엇인지 «설명해 달라»는 말이었는데, 그 턴이 xhigh 로 올라갔습니다. 두 번째 질문 «max와 ultracode의 차이점은?» 도 모드를 켜려는 뜻이 아니라 개념을 묻는 질문이었는데, Workflow 안내가 붙었습니다.

언어철학에는 낱말을 쓰는 것(use)과 낱말에 대해 말하는 것(mention)을 구분하는 오래된 개념이 있습니다. 사람은 «ultrathink 가 뭐야?» 라는 문장이 낱말을 언급할 뿐이라는 것을 바로 압니다. 그러나 낱말 경계만 보는 정규식은 이 둘을 구분하지 못합니다. 그래서 이 기능을 주제로 대화하거나, 관련 문서를 프롬프트에 붙여 넣거나, 서브에이전트에게 이 주제를 맡기는 지시문을 쓰기만 해도 의도치 않게 켜질 수 있습니다.

피하려면 낱말 경계를 깨면 됩니다. «울트라씽크» 처럼 한글로 쓰거나, «ultra-think» 처럼 하이픈을 넣는 식입니다. 실행 파일 안에도 낱말을 ultra-think 꼴로 바꿔 쓰는 처리가 들어 있었습니다. 다만 이 우회 표기가 실제로 발동을 막는지는 코드로만 확인했고, 직접 돌려 보지는 않았습니다.

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» 는 바로 그 비용 계산을 모델이 내려놓게 하는 문장이라, 켜기 전에 한 번 더 생각해 볼 대목이라는 생각이 들었습니다.

정리: max 는 깊이, ultracode 는 폭

조사를 마치고 제가 정리한 쓰임새는 이렇습니다.

상황 쓸 것 이유
high 이하 세션에서 이 한 턴만 더 깊게 ultrathink 그 턴만 xhigh. max·xhigh 세션에서는 효과가 거의 없음
첫 종합 보고서·감사·전수 조사를 요청하는 프롬프트 ultracode 낱말 그 한 턴만 Workflow. 반증과 완결성 비평을 넣는 것이 핵심
큰 이관·감사처럼 세션 전체가 조사·검증 ultracode 모드 끌 때까지 실질적인 작업마다 Workflow
한 응답의 깊이가 필요할 때 max 노력 수준 사다리의 맨 위

ultracode 모드는 사람과 주고받으며 길게 이어지는 대화형 세션에는 권하지 않습니다. 실질적인 작업으로 판단되는 턴마다 Workflow 가 붙어 비용이 불어나기 쉽고, 그런 세션의 시간 대부분은 앞에서 본 것처럼 Workflow 가 도울 수 없는 결정과 대기 구간이기 때문입니다.

한 줄로 줄이면 max 는 깊이, ultracode 는 폭입니다. 노력 수준은 한 응답을 얼마나 깊게 생각하느냐의 축이고, Workflow 는 여러 축을 나누고 서로 검증하게 하느냐의 축입니다. 저는 이 둘을 «더 세게»라는 한 방향의 다이얼로 보고 있었습니다.

덧붙여, 제 개인 Claude Code 설정과는 아직 매끄럽게 맞물리지 않는 부분이 있습니다. 예전에 에이전트가 한 번에 수십에서 백 개 넘게 불어난 사고를 겪은 뒤, Workflow 스크립트가 에이전트 6개 이상이거나 반복문 안에서 에이전트를 부르면 훅이 막고 제 승인을 받게 해 두었습니다. 그런데 앞에서 본 품질 패턴(빈손까지 반복, 여러 에이전트의 반증, 판정단)은 대부분 이 규칙에 걸립니다.

반대로 위임 모델과 노력 수준을 점검하는 훅은 Agent 도구에만 걸리고 Workflow 안의 에이전트에는 걸리지 않습니다. 그래서 max 세션에서 Workflow 를 돌릴 때 스크립트가 에이전트마다 노력 수준을 따로 정하지 않으면, 안쪽 에이전트가 점검 없이 전부 max 로 돕니다. 막히는 쪽이 아니라 비용이 새는 쪽입니다(위임할 때 모델을 낮추는 이야기는 서브에이전트 모델 티어링 글에 적었습니다). 이 충돌들을 어떻게 고칠지는 아직 정하지 못했습니다.

돌이켜 보면 이번에 배운 것은 기능 두 개의 사용법보다, 이름이 주는 인상과 실제 동작 사이의 거리를 직접 재 보는 일의 값이었다는 생각이 들었습니다. «울트라»라는 접두어는 같아도 하나는 사다리의 한 칸을 한 턴 빌리는 것이고, 다른 하나는 일하는 방식을 바꾸는 것이었습니다. 다음에는 아직 돌려 보지 않은 pipeline 과 반복 패턴을, 반증 단계를 넣은 조사 한 건에 실제로 써 보려 합니다.