"Claude Code" 태그로 연결된 18개 게시물개의 게시물이 있습니다.

Claude Code 응답에서 제일 자주 걸러내고 싶은 게 뭘까요. 저는 "먼저 파일을 확인해 보겠습니다" 같은 예고 문장이었어요. v2.1.237에 그걸 기본으로 지워 주는 출력 스타일이 들어왔습니다.

이름은 Concise입니다. 변경 로그 한 줄은 이렇습니다.

Added built-in "Concise" output style: Claude leads with results, skips preamble/narration, works thoroughly

내장 스타일이 다섯 개가 됐다​

출력 스타일은 원래 Default에 Explanatory와 Learning 둘이 붙은 구성이었습니다. 지금은 Proactive와 Concise가 더해져 Default 외에 네 개입니다.

Concise를 두고 오해하기 쉬운 부분이 하나 있습니다. 짧게 답하라는 게 작업을 덜 하라는 뜻은 아닙니다. 공식 문서는 "doing the engineering work as thoroughly as in the Default style"이라고 적어 뒀습니다. 설명을 요청하면 그때는 길게 답합니다. 그리고 짧게 만들지 않는 예외가 정해져 있습니다. 오류 보고, 보안 경고, 파괴적 작업의 확인 문구는 내용을 온전히 유지합니다. 이 예외 목록이 있다는 게 스타일 설계에서 제일 중요한 부분이라고 봅니다. 짧게 쓰다가 위험 신호를 줄여 버리면 절약이 아니라 사고니까요.

Proactive는 성격이 좀 다릅니다. 톤이 아니라 행동 방침을 바꿉니다. auto mode보다 강한 자율 실행 지침인데, 권한 모드는 그대로 둡니다. 무엇을 물어보지 않고 실행할지는 여전히 권한 모드가 결정하고, Proactive는 "판단을 사용자에게 넘기지 말고 스스로 하라"는 쪽만 건드립니다.

스타일을 바꾸는 방법이 달라졌다​

여기서 한 번 헤맬 수 있습니다. /output-style 명령이 없어졌습니다. v2.1.73에서 deprecated 되고 v2.1.91에서 제거됐습니다. 지금은 두 가지 방법뿐입니다.

터미널에서는 /config를 실행해 Output style 항목에서 고릅니다. 선택 결과는 프로젝트 로컬 설정 파일에 저장됩니다.

.claude/settings.local.json

설정 파일을 직접 고쳐도 됩니다.

{
  "outputStyle": "Concise"
}

데스크톱 앱에서는 /config가 메뉴 대신 Settings 화면을 엽니다. 그래서 데스크톱에서는 위 필드를 직접 넣는 쪽이 확실합니다.

바꾼 뒤 바로 안 바뀐다고 당황하지 않아도 됩니다. 출력 스타일은 시스템 프롬프트의 일부이고, 시스템 프롬프트는 세션이 시작할 때 한 번 읽습니다. /clear를 실행하거나 새 세션을 열어야 적용됩니다.

CLAUDE.md와 어디서 갈라지나​

이게 문서에서 가장 값이 나가는 대목입니다. 둘 다 "Claude가 이렇게 행동하게 만드는 장치"인데 붙는 위치가 다릅니다.

출력 스타일은 시스템 프롬프트 끝에 붙습니다. CLAUDE.md는 시스템 프롬프트 뒤에 오는 user message로 들어갑니다. 이 차이가 실무에서 세 갈래 결과를 만듭니다.

첫째, 커스텀 출력 스타일은 기본 소프트웨어 엔지니어링 지침을 빼 버립니다. 변경 범위를 어떻게 잡고, 주석을 어떻게 쓰고, 작업을 어떻게 검증하라는 내장 지침 전체가 사라집니다. 그걸 유지하려면 frontmatter에 keep-coding-instructions: true를 넣어야 합니다. 기본값이 false라는 걸 모르고 커스텀 스타일을 만들면, 톤만 바꾸려던 게 코딩 행동까지 바꿔 버립니다.

둘째, 서브에이전트에는 적용되지 않습니다. 서브에이전트는 자기 시스템 프롬프트로 돕니다. 예외가 fork인데, fork는 부모의 시스템 프롬프트를 통째로 물려받기 때문입니다. Concise로 세션을 돌리면서 서브에이전트에게 요약을 맡겼는데 서브에이전트 응답이 장황한 이유가 여기 있습니다.

셋째, 프롬프트 캐시입니다. 시스템 프롬프트가 바뀌면 캐시 접두사가 깨집니다. 토큰 절약 가이드 글에서 모델과 effort를 세션 시작 시점에 고정하라는 권고를 다뤘는데, 출력 스타일도 같은 부류의 설정입니다. 세션 도중에 바꿀 값이 아닙니다.

커스텀 스타일은 파일 하나다​

내장 다섯 개로 부족하면 마크다운 파일을 만듭니다. 위치는 세 곳이고, 파일명이 스타일 이름이 됩니다. frontmatter에 name을 적으면 그쪽이 이깁니다.

~/.claude/output-styles/          # 사용자 전역
.claude/output-styles/            # 프로젝트

공식 문서 예시가 성격을 잘 보여 줍니다.

---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---

When explaining code, architecture, or data flow, start with a Mermaid diagram
showing the structure, then explain in prose.

프로젝트 스타일은 작업 디렉터리부터 저장소 루트까지의 모든 .claude/output-styles/에서 읽습니다. 같은 이름이 여러 층에 있으면 작업 디렉터리에 가까운 쪽이 이깁니다. 플러그인도 output-styles/ 디렉터리로 스타일을 배포할 수 있는데, 플러그인 전용 필드인 force-for-plugin: true를 켜면 사용자의 outputStyle 설정을 덮어쓰고 강제 적용됩니다. 플러그인을 깔았는데 응답 톤이 갑자기 변했다면 이 필드를 의심해 볼 만합니다.

frontmatter 필드는 네 개입니다.

토큰은 어느 쪽으로 움직이나​

방향이 둘로 갈립니다. 입력 토큰은 스타일 지침이 시스템 프롬프트에 붙는 만큼 늘어납니다. 다만 첫 요청 이후에는 프롬프트 캐시가 이 비용을 상당히 덮습니다. 출력 토큰은 스타일이 결정합니다. Explanatory와 Learning은 설계상 응답이 길어지고, Concise는 반대로 갑니다.

그러니 Concise의 절약 효과는 출력 쪽입니다. 응답 길이가 짧아지는 만큼 출력 토큰이 줄고, 그 짧은 응답이 다음 턴의 입력으로 다시 들어가니 대화가 길어질수록 차이가 누적됩니다. 반대로 Learning 스타일로 긴 세션을 돌리면 그 반대 방향으로 누적됩니다. 제가 지금 이 글을 쓰는 세션이 Learning 스타일인데, 확실히 응답 길이가 기본보다 깁니다.

같은 주에 들어온 나머지​

Concise만 있던 주가 아닙니다. v2.1.234에 실무에서 체감될 항목이 둘 붙었습니다.

사용량 한도 자동 재개입니다. claude.ai 사용량 한도가 초기화되면 세션을 자동으로 이어서 진행합니다. /config에서 켜고 끕니다. 장시간 작업을 돌려 두고 자리를 비우는 사용 방식이라면 이 항목 하나로 흐름이 달라집니다. Routines처럼 사람이 안 보는 동안 도는 작업과 결이 같습니다.

GitLab merge request 배지도 들어왔습니다. GitLab remote가 걸린 저장소에서 glab으로 인증돼 있으면 MR !N 형태로 draft, pending, green 상태를 상태줄에 표시합니다. GitHub PR 배지만 있던 자리에 GitLab이 붙은 셈입니다.

이후 버전도 흐름이 이어집니다. v2.1.238에는 커스텀, 프로젝트, 플러그인 출력 스타일이 세션 도중에 기본 목소리로 되돌아가던 버그 수정이 들어갔습니다. 출력 스타일 자체를 손보는 작업이 한 주 내내 계속됐다는 뜻입니다. v2.1.239에서는 사용량 한도 안내가 세션, 주간, 월간 중 무엇이 초기화되는지 구분해 알려 주게 바뀌었습니다.

어떤 스타일로 쓸까​

정답은 작업 성격에 달렸습니다. 제 기준으로는 이렇게 갈립니다.

익숙한 코드베이스에서 반복 작업을 돌릴 때는 Concise가 맞습니다. 무엇을 할지 이미 알고 있으니 예고가 필요 없습니다. 처음 보는 코드베이스를 파악하는 중이라면 Explanatory가 낫습니다. "왜 이 파일을 골랐나"가 정보이기 때문입니다. 새 기술을 배우려고 붙었다면 Learning이 값을 합니다. TODO(human) 표시가 남으면 직접 손을 대야 하고, 그 지점이 대개 판단이 필요한 자리입니다.

Proactive는 조심스럽습니다. 권한 모드를 안 건드린다지만 "묻지 말고 판단하라"는 지침 자체가 리스크입니다. 되돌리기 쉬운 작업에만 쓰는 쪽이 안전합니다.

그리고 이 다섯 개는 서로 배타적입니다. 한 세션에 하나만 걸립니다. 작업 성격이 바뀌면 /clear하고 다시 고르는 게 정석입니다.

참고​

• Claude Code CHANGELOG
• Output styles 공식 문서
• Permission modes 공식 문서

같은 작업을 시켰는데 어떤 날은 사용량이 순식간에 닳고 어떤 날은 널널했던 경험, 있으실 거예요. 저도 한도에 일찍 닿은 날마다 모델 탓을 했는데, Anthropic이 8월 14일에 낸 공식 가이드를 읽고 나니 범인은 따로 있었습니다. 프롬프트 캐시를 깨는 습관입니다.

요금의 실체는 캐시 히트율​

Claude Code는 매 턴마다 지금까지의 대화 전체를 모델에 보냅니다. 대화가 길어질수록 매 요청의 입력이 커지는 구조인데, 이게 감당되는 이유가 프롬프트 캐시입니다. 직전 요청과 같은 prefix는 캐시에서 읽고, 캐시 읽기 요금은 정상 입력 가격의 0.1배입니다. 반대로 캐시에 새로 쓰는 비용은 최대 2배입니다.

즉 20배짜리 요금 격차가 대화 내내 작동합니다. 캐시가 살아 있으면 긴 대화도 턴당 비용이 낮게 유지되고, 캐시가 깨지면 대화 전체를 정상 가격으로 다시 보내며 다시 캐시 쓰기 할증까지 뭅니다. Claude Code의 캐시 유효 시간은 1시간입니다(API 직접 호출 기본은 5분).

캐시를 깨는 행동들​

가이드가 지목하는 캐시 무효화 요인은 네 가지입니다.

여기서 실무 결론이 나옵니다. 모델과 effort는 세션 시작 시점이나 /clear 직후에 정하고, 대화 중간에는 건드리지 않는 것입니다. 긴 대화 한가운데서 /model을 바꾸면 그 시점까지의 대화 전체가 새 모델 기준으로 재처리되고 재캐싱됩니다. "이 질문만 가볍게 다른 모델로" 하려던 절약이 실제로는 가장 비싼 행동이 되는 역설입니다.

한 시간 자리를 비울 때도 마찬가지입니다. 돌아와서 이어 쓰면 만료된 캐시를 처음부터 다시 씁니다. 가이드는 장시간 중단 전에 /compact를 실행하라고 권합니다. 캐시가 아직 유효할 때 요약해 두는 쪽이 싸기 때문입니다.

문맥 관리 명령 셋의 역할 분담​

/clear, /compact, /rewind가 비슷해 보여도 캐시 관점에서 역할이 다릅니다.

• /clear: 새 작업을 시작할 때. 이전 작업의 문맥은 다음 작업에서 전부 "돈 내고 실어 나르는 짐"이 되므로, 작업 사이에는 비우고 시작합니다
• /compact: 문맥은 이어가야 하는데 대화가 너무 길어졌거나, 장시간 자리를 비우기 직전에
• /rewind: 마지막 몇 턴만 무르고 싶을 때. 캐시를 무효화하지 않는 것이 장점입니다

저처럼 한 세션에서 이 일 저 일 이어 하던 사람에게는 /clear가 제일 아픈 항목입니다. "혹시 아까 맥락이 필요할지 몰라서" 남겨 둔 문맥이 매 턴 입력 토큰으로 청구되고 있었으니까요.

입력을 줄이는 잔기술​

캐시 다음으로 효과가 큰 항목은 문맥에 들어오는 양 자체를 줄이는 것입니다.

파일은 @멘션으로 첨부합니다. src/main.py 읽어 봐라고 쓰면 모델이 Read 도구를 호출하는 왕복이 생기는데, @src/main.py로 멘션하면 파일이 첫 요청에 바로 첨부됩니다. 도구 호출 한 번과 그 결과 처리가 통째로 절약됩니다.

시끄러운 명령 출력은 서브에이전트로 격리합니다. 30,000자를 넘는 명령 출력은 자동으로 파일로 저장되고 미리보기만 문맥에 남습니다만, 그 미만의 장황한 출력(테스트 로그, 빌드 로그)은 고스란히 문맥을 차지합니다. 로그를 뒤져야 하는 작업은 독립 문맥에서 도는 서브에이전트에 맡기면 메인 세션이 가벼워집니다.

자주 쓰는 명령은 CLAUDE.md에 조용한 플래그와 함께 적어 둡니다. 예를 들어 테스트를 verbose로 돌리는 습관이 있다면, CLAUDE.md에 quiet 플래그가 붙은 명령을 기록해 모델이 처음부터 조용한 버전을 실행하게 하는 식입니다.

가이드가 제시한 우선순위는 이렇습니다. 불필요한 파일 읽기 방지, 긴 세션 분할, 모델/effort 고정, 명령 출력 최소화 순입니다.

이 가이드가 나온 맥락​

읽다 보면 이 가이드는 절약 팁 모음이라기보다 과금 구조 설명서에 가깝습니다. 에이전트형 코딩 도구의 비용은 "몇 마디 나눴나"가 아니라 "문맥 몇 토큰을 몇 번 실어 날랐나"로 결정되는데, 사용자 대부분은 전자로 체감합니다. 그 간극에서 "왜 벌써 한도냐"는 불만이 나오고, 이 문서는 거기에 대한 공식 답변으로 보입니다.

도구 쪽 기본값도 같은 방향으로 움직이고 있습니다. 최근 릴리스에서 서브에이전트 포크가 캐시를 상속하게 된 것도, 포크할 때마다 문맥을 다시 캐싱하는 비용을 없애는 변경입니다. 캐시를 아끼는 방향으로 도구가 정렬되고 있으니, 사용자 습관만 따라가면 됩니다.

오늘부터 바꿀 것 하나만 고르라면 저는 "작업 끝나면 /clear"를 고르겠어요. 제일 쉽고, 제일 큽니다.

참고 자료​

• Maximizing the value of your Claude Code sessions - Claude Blog, 2026-08-14
• Claude API 프롬프트 캐싱 문서

터미널 두 개에 Claude Code를 띄워 놓고 한쪽 결과를 복사해서 다른 쪽에 붙여넣던 시절이 있었어요. 이번 주 릴리스로 그 복붙이 공식적으로 필요 없어졌습니다.

2.1.232 changelog의 첫 두 줄이 핵심입니다. 서브에이전트 포크가 기본 활성화됐고, 프롬프트에서 @를 입력하면 다른 세션을 이름으로 직접 부를 수 있습니다. 따로 보면 각각 작은 기능인데, 합치면 "세션 하나 = 작업 하나"라는 전제가 무너집니다.

포크: 문맥을 통째로 물려받는 서브에이전트​

기존 서브에이전트의 약점은 기억상실이었습니다. 새 에이전트는 빈 문맥에서 출발하니, 지금까지 대화에서 쌓인 맥락을 프롬프트에 꾹꾹 눌러 담아 전달해야 했습니다. 전달이 부실하면 엉뚱한 결과가 돌아왔습니다.

subagent_type: "fork"로 뜨는 포크 에이전트는 부모의 대화 전체와 프롬프트 캐시를 상속합니다. 지금까지 읽은 파일, 내린 결정, 사용자가 준 피드백을 전부 아는 상태로 출발합니다. 캐시까지 물려받으니 그 문맥을 다시 처리하는 비용도 들지 않습니다.

함께 바뀐 기본값이 하나 더 있습니다. 대화형 세션에서 띄우는 에이전트는 이제 배경 실행이 기본입니다. 에이전트가 도는 동안 메인 세션이 멈춰 기다리지 않고, 끝나면 알림으로 결과가 돌아옵니다. 에이전트의 도구 호출 로그가 메인 문맥을 차지하지도 않습니다. 정리하면 "무거운 조사나 검증은 포크로 떼어 배경에서 돌리고, 메인은 계속 진행한다"가 이제 설정 없이 되는 기본 동작입니다.

@멘션: 세션끼리 직접 대화​

두 번째 변화는 세션 간 통신입니다. 프롬프트에 @를 입력하면 같은 머신에서 돌고 있는 다른 Claude 세션 목록이 뜨고, 이름을 고르면 그 세션으로 메시지가 갑니다. 내부적으로는 SendMessage 도구를 사용합니다.

이걸 받쳐 주는 손질도 같이 들어갔습니다.

• 이름이 정확히 하나의 살아 있는 세션과 일치하면 확인 절차 없이 바로 전달됩니다
• 한 머신의 대화형 세션들은 고유한 이름을 유지합니다. 이미 쓰는 이름으로 시작하면 자동으로 변형된 이름을 받습니다
• /config에 다른 세션에서 오는 메시지를 받을지(수락/보류/거부) 정하는 항목이 생겼습니다

블로그 작업으로 예를 들면 이렇게 됩니다. 포스트 A를 쓰는 세션과 포스트 B를 쓰는 세션을 나란히 띄워 두고, A 세션에서 @세션B 방금 정한 용어 표기를 너도 맞춰 줘라고 보내면 끝입니다. 사람이 두 터미널 사이에서 전서구 노릇을 할 필요가 없습니다. 지시는 각 세션에 직접 하되, 세션끼리 맞출 것은 세션끼리 맞추게 하는 구조입니다.

Opus 4.8 리뷰에서 "한 사람에게 맡기던 일을 한 팀에게 맡긴다"고 썼는데, 이번 릴리스는 그 팀에게 사내 메신저를 지급한 셈입니다. Dynamic Workflows가 한 세션 안의 수직 분업이라면, @멘션은 세션 사이의 수평 분업입니다.

2.1.233: worktree의 GitLab MR, cgroup 메모리 제한​

다음 날 나온 2.1.233에서 운영 관점의 항목 둘이 눈에 띕니다.

GitLab 지원 확대. --worktree 플래그와 claude agents 뷰가 GitLab merge request URL을 인식합니다(MR은 !N으로 표시). 2.1.232에서 이미 GitLab 토큰 계열(glpat- 등) 시크릿 마스킹과 GitLab 플러그인 마켓플레이스 지원이 들어왔으니, 이틀 사이에 GitLab 사용자 대접이 눈에 띄게 좋아졌습니다. GitHub 전용이라 망설이던 조직에는 신호가 될 만합니다.

Bash 도구 메모리 제한. Linux에서 CLAUDE_CODE_TOOL_MEMORY_LIMIT 환경변수로 Bash 명령에 cgroup 메모리 제한을 걸 수 있습니다(opt-in). 에이전트가 실행한 빌드가 폭주해 메모리를 삼키면 세션까지 같이 죽던 문제의 대응입니다. CI 러너나 공용 개발 서버에서 Claude Code를 돌리는 환경이라면 켜 둘 가치가 있습니다.

하나 더, 방향을 보여주는 항목이 있습니다. Opus 4.8과 그 이후 모델에서 todo/task 추적 도구(TodoWrite, TaskCreate 등)가 기본 비활성화됐습니다. 되살리려면 CLAUDE_CODE_ENABLE_TODO_TOOLS=1을 설정해야 합니다. 신형 모델은 할 일 목록을 도구로 관리시키지 않아도 작업을 놓치지 않는다는 판단이 깔린 변경입니다. 화면에서 todo 목록이 사라졌다면 버그가 아니라 이 변경입니다.

써 보고 느끼는 것​

이 글을 쓰는 세션도 뉴스 수집을 포크 에이전트 여섯에 나눠 맡기고, 결과를 메시지로 돌려받는 흐름으로 작업했습니다. 수집 에이전트들이 배경에서 도는 동안 메인 세션은 기존 포스트 목록을 정리했고, 끝난 에이전트부터 결과가 도착했습니다. 복붙도, 파일 경유도 없었습니다.

체감 요령을 남기면, 포크에는 "지금까지의 문맥이 필요한 일"을, 일반 서브에이전트에는 "문맥이 오히려 편견이 되는 일"(백지 검증, 독립 리뷰)을 맡기는 구분이 유효했습니다. 포크가 기본이 됐다고 전부 포크로 보낼 일은 아니에요. 문맥 상속은 힘이면서 동시에 선입견이니까요.

참고 자료​

• Claude Code CHANGELOG (2.1.232, 2.1.233) - Anthropic, 2026-08-13~14
• Claude Code 공식 문서

코딩 에이전트 도입 논의가 보안 검토에서 멈추는 조직, 많죠. 코드는 사내망 밖으로 못 나간다는 원칙과, 에이전트 세션은 벤더 클라우드에서 돈다는 현실이 부딪히는 지점이에요.

Anthropic이 8월 6일 퍼블릭 베타로 공개한 self-hosted environments는 정확히 그 지점을 겨냥합니다. 웹, 모바일, 데스크톱에서 시작하는 Claude Code 클라우드 세션의 실행 환경을 조직이 제공한 머신으로 바꿉니다. 저장소 체크아웃, 빌드 산출물, 시크릿, 세션이 만들거나 수정하는 모든 파일이 조직 인프라 안에 남습니다.

구조: runner라는 상주 프로세스​

동작 단위는 runner입니다. claude self-hosted-runner로 띄우는 장수(long-lived) 프로세스로, 세션 하나가 시작되면 runner 하나가 그 세션의 Claude Code 실행을 맡습니다. 운영 모드는 두 가지입니다.

CI 러너를 운영해 본 조직이라면 구조가 낯설지 않을 겁니다. GitHub Actions의 self-hosted runner와 개념이 같고, 이름도 같습니다. 사내 Kubernetes에 runner 풀을 두고 세션을 받는 그림이 자연스럽게 그려집니다.

기존 Remote Control과의 차이도 여기 있습니다. Remote Control은 특정 개인의 머신에 세션을 묶는 기능입니다. self-hosted environments는 조직 공용 인프라에 세션을 올리고, 권한 있는 누구든 쓸 수 있습니다. 개인의 원격 제어와 조직의 실행 기반이라는 층위 차이입니다.

무엇이 남고, 무엇이 나가나​

이 기능을 검토할 보안 담당자가 볼 핵심은 경계선입니다.

사내에 남는 것: 저장소 체크아웃, 빌드 산출물, 시크릿, 세션이 만들고 수정하는 파일 전부. 코드가 Anthropic의 실행 환경에 복제되지 않습니다.

여전히 Anthropic으로 가는 것: 대화 데이터입니다. 프롬프트, 응답, 도구 실행 결과는 모델 추론을 위해 전송되고, 세션 transcript는 여러 기기에서 이어 쓰기 위해 저장됩니다. 도구 실행 결과에는 코드 조각이 포함될 수 있으니, "코드가 한 줄도 안 나간다"는 이해는 정확하지 않습니다. 나가는 것은 모델이 보는 문맥이고, 남는 것은 파일시스템과 실행 환경입니다.

조건도 명확합니다. Team과 Enterprise 플랜 전용이고, ZDR(zero data retention) 계약 조직은 현재 쓸 수 없습니다. transcript 저장이 기능의 전제라서 생기는 제약으로 보입니다. 그리고 공식 문서가 셋업과 유지보수에 전담 엔지니어링 인력이 필요하다고 미리 말해 둡니다. 켜면 되는 토글이 아니라 운영해야 하는 인프라입니다.

어떤 조직에 의미가 있나​

이 기능이 풀어 주는 매듭은 두 종류입니다.

첫째, 컴플라이언스 매듭입니다. 소스코드의 물리적 위치를 통제해야 하는 조직(금융, 공공, 계약상 제약이 있는 곳)은 지금까지 클라우드 세션 자체가 선택지 밖이었습니다. 실행 환경이 사내로 들어오면 검토의 성격이 "코드를 외부에 두어도 되는가"에서 "대화 데이터 전송을 허용하는가"로 좁혀집니다. 후자는 이미 API 사용 승인과 같은 범주라 통과 경로가 있는 조직이 많습니다.

둘째, 환경 매듭입니다. 빌드에 사내 아티팩트 저장소, 내부 DNS, VPN 안쪽 서비스가 필요한 프로젝트는 벤더가 제공하는 격리 환경에서 애초에 빌드가 안 됩니다. runner가 사내망에 있으면 이 문제가 사라집니다.

베타답게 다듬는 중인 흔적도 보입니다. 바로 다음 릴리스(2.1.233)에서 runner의 세션 시작 시간을 줄이는 개선(working tree 재작성 없는 브랜치 생성, 서버 왕복 2회 제거)이 들어왔습니다.

개인 사용자에게는 당장 해당 없는 기능이지만, 방향은 기억해 둘 만해요. 에이전트가 개인 도구에서 조직 인프라로 올라가는 단계마다 이런 부품이 하나씩 채워지고 있고, self-hosted runner는 그중 꽤 큰 조각입니다.

참고 자료​

• Run Claude Code sessions on your own compute - Claude Blog, 2026-08-06
• Claude Code CHANGELOG

입력창이 더는 안 흔들린다​

Claude가 작업하는 동안 화면이 번쩍이고, 출력이 쏟아질 때 스크롤이 맨 위로 튀어 오르고, 긴 세션에서 메모리가 슬금슬금 차오르던 경험은 Claude Code를 오래 쓴 사람이면 익숙해요. Fullscreen 렌더링은 그 세 가지를 한 번에 잡으려고 나온 새 렌더링 경로로, 대화를 vim이나 htop처럼 터미널의 alternate screen buffer에 그려요.

/tui fullscreen 한 줄이면 켜집니다. 대화는 그대로 유지된 채 fullscreen으로 다시 뜹니다. 세션 중간에 켜도 맥락을 잃지 않습니다. Claude Code v2.1.89 이상에서 동작하는 리서치 프리뷰 기능입니다. (Fullscreen 렌더링 공식 문서)

주의: 이 글은 전부 리서치 프리뷰 기준입니다. 동작 방식, 키 바인딩, 설정 키 이름 모두 정식 출시 전에 바뀔 수 있습니다.

fullscreen은 창 최대화가 아닙니다​

먼저 오해부터 풀고 갑니다. 여기서 fullscreen은 터미널 창을 최대화한다는 뜻이 아닙니다. Claude Code가 터미널의 그리는 표면(drawing surface)을 vim처럼 통째로 가져간다는 뜻입니다. 창 크기와 무관하게, 작은 창에서도 똑같이 동작합니다.

기존 렌더러(classic)는 대화를 터미널의 native scrollback에 차곡차곡 쌓습니다. 매 업데이트마다 화면을 다시 그리면서 터미널로 많은 데이터를 흘려보냅니다. Fullscreen은 다릅니다. 지금 화면에 보이는 메시지만 렌더 트리에 둡니다. 터미널로 보내는 데이터량이 확 줄어듭니다.

깜빡임, 메모리, 스크롤 점프를 줄입니다​

세 가지 문제를 노립니다.

차이가 가장 크게 느껴지는 곳은 렌더링 처리량(throughput)이 병목인 터미널입니다. 공식 문서는 VS Code 통합 터미널, tmux, iTerm2를 콕 집습니다. 이런 환경에서 화면이 번쩍이거나 스크롤이 튀었다면 fullscreen이 정확히 그 증상을 겨냥합니다.

켜고 끄는 법​

가장 쉬운 방법은 대화 안에서 슬래시 명령을 실행하는 것입니다.

/tui fullscreen   # fullscreen 렌더링으로 전환 (대화 유지된 채 재시작)
/tui default      # classic 렌더러로 복귀
/tui              # 인자 없이 실행하면 현재 어떤 렌더러인지 출력

/tui 명령은 tui 설정을 ~/.claude/settings.json에 저장하고 그 값으로 다시 띄웁니다. 그래서 다음 세션에도 선택이 유지됩니다.

환경 변수로 켤 수도 있습니다. /tui 명령이 생긴 v2.1.110 이전 버전에서는 이쪽이 유일한 방법이었습니다.

CLAUDE_CODE_NO_FLICKER=1 claude

tui 설정과 CLAUDE_CODE_NO_FLICKER 환경 변수는 같은 의미입니다. /tui 명령은 재시작하는 프로세스에서 CLAUDE_CODE_NO_FLICKER를 지워, 새로 쓴 설정 값이 우선 적용되게 합니다.

fullscreen이 켜졌는지 확인하는 가장 직관적인 신호는 입력창입니다. 출력이 쏟아져도 입력창이 화면 하단에 고정돼 움직이지 않으면 fullscreen이 동작 중입니다. classic 렌더러에서는 입력창이 출력을 따라 위로 밀려 올라갑니다.

두 렌더러는 어디서 갈리나​

대화가 어디에 저장되느냐가 갈림길입니다. 그 한 가지 차이에서 검색/복사 동작이 전부 달라집니다.

대화가 alternate screen buffer에 살기 때문에, 터미널의 native scrollback에 의존하던 동작이 달라집니다.

마우스가 붙는다​

Fullscreen은 마우스 이벤트를 캡처해 Claude Code 안에서 처리합니다. classic 렌더러에는 없던 기능입니다.

입력창을 클릭하면 입력 중인 텍스트의 원하는 위치로 커서가 옮겨집니다. / 명령이나 @ 파일 목록에서는 제안 항목을 클릭으로 바로 고르고, 호버하면 해당 행이 강조됩니다. 권한 프롬프트나 /model//config 같은 select 메뉴도 클릭으로 선택할 수 있습니다(v2.1.187 이상). 접힌 tool 결과를 클릭하면 펼쳐서 전체 출력을 보고, 다시 클릭하면 접힙니다. URL이나 파일 경로는 Cmd(macOS)/Ctrl(Linux/Windows)를 누른 채 클릭하면 링크는 브라우저로, 파일 경로는 기본 앱으로 열립니다. v2.1.181부터는 키 없이 그냥 클릭해도 링크가 열리지 않는데, native 터미널 동작에 맞춘 변경입니다. 이 밖에 드래그로 선택하고 휠로 스크롤하며, 더블클릭은 단어, 트리플클릭은 줄 단위로 선택합니다.

선택한 텍스트는 마우스를 떼는 순간 클립보드에 자동 복사됩니다. 이 동작이 거슬리면 /config에서 Copy on select를 끕니다.

스크롤과 검색​

스크롤도 앱 안에서 처리합니다. 주요 단축키는 다음과 같습니다.

MacBook처럼 PgUp/PgDn 전용 키가 없는 키보드는 Fn과 방향키를 조합합니다. Fn+↑이 PgUp, Fn+↓가 PgDn입니다.

위로 스크롤하면 auto-follow가 멈춰, 새 출력이 다시 맨 아래로 끌어내리지 않습니다. Ctrl+End를 누르거나 맨 아래로 내리면 다시 따라가기 시작합니다.

검색은 transcript 모드에서 합니다. Ctrl+o로 일반 프롬프트와 transcript 모드를 오갑니다. transcript 모드는 less 스타일 탐색을 지원합니다.

터미널의 Cmd+f나 tmux 검색은 대화를 보지 못합니다. 대화가 native scrollback이 아니라 alternate screen buffer에 있기 때문입니다. 내용을 터미널로 다시 넘기려면 Ctrl+o로 transcript 모드에 들어간 뒤 [를 누릅니다. 전체 대화가 native scrollback에 평범한 텍스트로 다시 쓰이고, 그때부터 Cmd+f/tmux copy mode가 다시 통합니다.

tmux와 함께 쓸 때​

Fullscreen은 tmux 안에서도 동작합니다. 세 가지만 주의합니다.

첫째, 마우스 휠 스크롤은 tmux의 mouse mode가 필요합니다. ~/.tmux.conf에 아래 한 줄을 넣고 설정을 다시 읽습니다. 없으면 휠 이벤트가 Claude Code 대신 tmux로 갑니다.

set -g mouse on

둘째, iTerm2의 tmux 통합 모드(tmux -CC)와는 호환되지 않습니다. 이 모드에서는 alternate screen buffer와 마우스 추적이 제대로 동작하지 않고, 더블클릭이 터미널 상태를 깨뜨릴 수 있습니다. tmux -CC 세션에서는 fullscreen을 켜지 않는 편이 좋습니다. -CC 없는 일반 tmux는 문제없습니다.

셋째, tmux는 synchronized output을 지원하지 않아, Claude Code를 터미널에서 바로 실행할 때보다 redraw 중 깜빡임이 더 보일 수 있습니다. SSH 환경에서 특히 거슬리면 tmux 밖 별도 탭에서 실행하는 편이 낫습니다.

native 선택을 그대로 두고 싶다면​

마우스 캡처는 가장 흔한 마찰 지점입니다. SSH나 tmux 안에서 특히 그렇습니다. Claude Code가 마우스 이벤트를 가져가면 터미널의 native copy-on-select가 멈춥니다. 드래그로 만든 선택은 Claude Code 안에만 있고, 터미널의 선택 버퍼에는 없습니다.

한 번만 native 선택을 쓰고 싶으면 터미널별 지정 키를 누른 채 드래그합니다. Terminal.app은 Fn, iTerm2는 Option, VS Code/Cursor는 Shift입니다.

마우스 캡처 자체가 늘 거슬린다면, 깜빡임 제거와 일정한 메모리는 유지하면서 마우스 캡처만 끌 수 있습니다.

CLAUDE_CODE_NO_FLICKER=1 CLAUDE_CODE_DISABLE_MOUSE=1 claude

이렇게 하면 PgUp, PgDn, Ctrl+Home, Ctrl+End 키보드 스크롤은 그대로 살고, 선택은 터미널이 native로 처리합니다. 대신 클릭으로 커서 옮기기, tool 결과 펼치기, URL 클릭, 앱 안 휠 스크롤은 포기해야 합니다.

DBA/개발자가 지금 해 볼 것​

긴 작업을 자주 돌리는 사람일수록 효과가 큽니다. 대형 리팩터링이나 수십 개 파일을 훑는 세션에서 classic 렌더러는 출력이 쌓이며 메모리가 늘고 스크롤이 튀지만, fullscreen은 일정하게 버팁니다.

일단 /tui fullscreen을 실행하고, 출력이 쏟아질 때 입력창이 고정되는지 봅니다. 안 맞으면 /tui default로 즉시 돌아오면 됩니다. VS Code, tmux, iTerm2 사용자라면 우선순위를 높게 둘 만한데, 깜빡임/스크롤 점프가 가장 심하던 환경이라 체감 차이가 큽니다. tmux를 쓴다면 set -g mouse on을 먼저 넣어야 휠 스크롤이 tmux로 새어 나가지 않습니다. 마지막으로 검색 습관을 바꿔야 합니다. Cmd+f 대신 Ctrl+o로 transcript 모드에 들어가 /로 찾고, 내용을 터미널로 넘기려면 그 안에서 [를 누릅니다.

복귀 경로가 명확한 것도 저는 안심돼요. /tui default로 돌아가거나, 저장된 설정과 무관하게 classic 렌더러를 강제하려면 CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1을 둡니다. agent view나 claude attach로 여는 백그라운드 세션은 항상 fullscreen으로 뜬다는 점만 기억하면 됩니다.

정리​

Fullscreen 렌더링은 Claude Code의 TUI를 vim/htop 계열로 한 단계 올립니다. alternate screen buffer를 써서 깜빡임이 사라지고 메모리가 일정해지며 마우스가 붙는 대신, 검색/복사는 앱 안 동작으로 바뀝니다. 손에 익히는 데 며칠 걸리지만, 긴 세션을 자주 돌리는 사람에게는 그만한 값을 합니다.

아직 리서치 프리뷰라서 흔치 않은 터미널이나 특이한 설정에서는 렌더링 문제가 생길 수 있고, 그럴 땐 /feedback이나 claude-code GitHub 저장소로 터미널 이름/버전과 함께 알리면 돼요. 동작이 바뀔 여지도 남아 있지만, 한 줄(/tui fullscreen)로 켜고 한 줄(/tui default)로 끄는 비용이면 한 번 켜 보고 판단하기에 충분히 싸요.

또 한 단계 올라갔다​

Skills로 명령어를 통합하고, Routines로 예약 실행을 붙이고, Auto 모드로 권한 판단까지 AI에게 넘기더니, 이번엔 Claude가 오케스트레이션 스크립트를 직접 짜서 서브에이전트 수백 개를 한 세션에서 병렬로 돌리는 Dynamic Workflows가 2026년 5월 28일 Opus 4.8과 함께 공개됐어요.

지금까지의 서브에이전트는 Claude가 대화 턴마다 하나씩 띄우고 결과를 자기 컨텍스트로 받아오는 방식이었습니다. 몇 개까지는 괜찮지만, 500개 파일을 동시에 손봐야 하는 작업에서는 컨텍스트가 먼저 터집니다. Dynamic Workflows는 그 한계를 넘으려고 나온 기능입니다. (Anthropic 발표, TechCrunch)

주의: 이 글의 내용은 전부 리서치 프리뷰 기준입니다. 동작 방식, 한도, 요금 모두 정식 출시 전에 바뀔 수 있습니다. Claude Code v2.1.154 이상이 필요합니다.

한 줄 정의​

공식 문서의 정의는 명확합니다.

"A dynamic workflow is a JavaScript script that orchestrates subagents at scale." — Claude Code Docs

워크플로우는 Claude가 작성하는 자바스크립트 오케스트레이션 스크립트입니다. 사용자가 작업을 설명하면 Claude가 그 작업에 맞는 스크립트를 쓰고, 런타임이 그 스크립트를 백그라운드에서 실행합니다. 스크립트가 도는 동안 대화 세션은 그대로 응답 가능한 상태로 남습니다.

중요한 차이는 누가 계획을 들고 있느냐에 있습니다.

서브에이전트/스킬과 무엇이 다른가​

셋 다 멀티스텝 작업을 처리할 수 있습니다. 차이는 계획의 주체와 중간 결과의 저장 위치입니다.

서브에이전트와 스킬에서는 Claude가 오케스트레이터입니다. 무엇을 띄울지 턴마다 판단하고, 모든 결과가 Claude 컨텍스트로 돌아옵니다. 워크플로우는 그 루프와 분기, 중간 결과를 스크립트 안으로 옮깁니다. 그 결과 Claude 컨텍스트에는 최종 답만 남습니다. 그래서 컨텍스트가 터지지 않습니다.

어떻게 도는가​

작업을 워크플로우로 넘기면 세 단계를 거칩니다.

대화 세션은 이 흐름 내내 자유롭습니다. /workflows를 실행하면 진행 중인 런의 진행 화면이 뜨고, 단계별 에이전트 수와 토큰 사용량, 경과 시간을 볼 수 있습니다.

패턴 1: Fan-Out​

워크플로우가 시작되면 Claude가 프롬프트를 기준으로 계획을 세우고, 작업을 서브태스크로 쪼갠 뒤 여러 에이전트에 병렬로 펼칩니다. 이걸 fan-out이라 부릅니다. 한 런에서 수십에서 수백 개의 에이전트가 동시에 돕니다.

예를 들어 라우트 디렉토리 전체에서 인증 누락을 감사하라고 하면, 엔드포인트마다 에이전트 하나씩 붙여 동시에 점검합니다.

Run a workflow to audit every API endpoint
under src/routes/ for missing auth checks

프롬프트에 트리거 키워드를 넣으면 Claude Code가 그 단어를 강조 표시하고, 턴 단위로 처리하는 대신 워크플로우 스크립트를 작성합니다. 발표 직후에는 workflow가 트리거였지만, 2026년 6월 2일 v2.1.160에서 트리거 키워드가 ultracode로 바뀌었습니다. 이제 workflow라는 단어만으로는 런이 시작되지 않습니다. 다만 평소 쓰는 말로 워크플로우를 요청하는 건 그대로 동작합니다. (Claude Code Changelog)

패턴 2: 어드버서리얼 검증​

여기가 단순히 에이전트를 더 많이 돌리는 것과 갈리는 지점입니다. 워크플로우는 반복 가능한 품질 패턴을 적용합니다.

에이전트가 발견한 내용을 그냥 보고하지 않습니다. 다른 에이전트가 그 발견을 반박하는 임무를 맡습니다. 한 에이전트가 "이 함수에 race condition이 있다"고 주장하면, 다른 에이전트는 그 주장을 깨는 일을 맡습니다. 반박을 거치고도 살아남은 주장만 사용자에게 전달됩니다.

번들로 제공되는 /deep-research 워크플로우가 이 패턴을 그대로 씁니다. 여러 각도로 웹 검색을 펼치고, 찾은 출처를 서로 교차검증하고, 각 주장에 투표한 뒤, 교차검증을 통과하지 못한 주장은 걸러낸 인용 리포트를 돌려줍니다.

패턴 3: 수렴 반복​

고정된 단계의 파이프라인이 아닙니다. 워크플로우는 답이 더 이상 바뀌지 않을 때까지 반복합니다. 에이전트 수와 반복 횟수는 작업이 실제로 요구하는 바에 따라 실시간으로 정해집니다.

이 수렴 방식 덕분에 단일 패스로는 도달할 수 없는 결과까지 갑니다. 한 번 훑고 끝내는 게 아니라, 발견과 반박을 답이 안정될 때까지 돌리는 구조입니다.

실제 사례: Bun을 Zig에서 Rust로​

가장 인상적인 사례는 Jarred Sumner가 Bun 런타임을 Zig에서 Rust로 포팅한 작업입니다. 약 75만 줄 코드를 11일 만에 옮겼습니다. 파일마다 에이전트를 붙여 수백 개를 병렬로 돌렸고, 파일당 리뷰어를 두 명씩 뒀습니다. (Anthropic 발표)

Anthropic은 이 기능의 목표를 "코드베이스 규모의 마이그레이션을 킥오프부터 머지까지, 기존 테스트 스위트를 합격 기준으로 삼아 수행"하는 것으로 잡았습니다. (TechCrunch) 기존 테스트가 통과 여부를 판정하니, 사람이 일일이 검수하지 않아도 합격선이 정의됩니다.

발표의 표현을 빌리면 분기 단위로 계획하던 일이 며칠 만에 끝납니다. 다만 이건 잘 풀린 사례입니다. 테스트 커버리지가 부실한 코드베이스라면 합격 기준 자체가 흔들립니다.

한도와 제약​

런타임에는 다음과 같은 제약이 있습니다.

수백 개 병렬이라는 표현과 동시 16개가 충돌하는 것처럼 보이지만, 동시 실행은 16개로 묶이고 누적 총량이 런당 최대 1,000개라는 뜻입니다. (Claude Code Docs, MarkTechPost)

권한 측면도 짚어둘 만합니다. 세션 권한 모드와 무관하게, 워크플로우가 띄우는 서브에이전트는 항상 acceptEdits 모드로 돌고 파일 편집은 자동 승인됩니다. 긴 런에서 셸 명령이나 MCP 도구로 중간에 멈추고 싶지 않다면, 시작 전에 필요한 명령을 allowlist에 넣어두는 편이 낫습니다.

어떻게 켜고 끄는가​

워크플로우를 작성하게 하는 방법은 두 가지입니다.

발표 시점의 트리거 키워드는 workflow였으나 v2.1.160(2026년 6월 2일)에서 ultracode로 바뀌었습니다. 예전 글이나 영상에서 workflow라고 적으라는 안내를 봤다면 키워드만 바꿔 읽으면 됩니다.

ultracode는 xhigh effort(추론 강도)와 자동 워크플로우 오케스트레이션을 묶은 설정입니다. 켜두면 Claude가 작업마다 워크플로우가 필요한지 알아서 판단합니다. 한 요청이 여러 워크플로우로 갈라질 수도 있습니다. 코드 이해용 하나, 변경용 하나, 검증용 하나 식으로. 그만큼 토큰과 시간을 더 씁니다.

마음에 드는 런이 나오면 /workflows에서 그 런을 골라 s 키로 명령어로 저장할 수 있습니다. 프로젝트의 .claude/workflows/에 두면 저장소를 받은 모두가 쓰고, 홈의 ~/.claude/workflows/에 두면 저만 써요.

끄는 방법도 명확합니다.

• /config에서 Dynamic workflows 토글 끄기
• ~/.claude/settings.json에 "disableWorkflows": true
• 환경변수 CLAUDE_CODE_DISABLE_WORKFLOWS=1
• 조직 전체는 managed settings의 "disableWorkflows": true

요금과 가용성​

• 리서치 프리뷰. Claude Code v2.1.154 이상 필요
• 유료 플랜 전체에서 사용 가능 (Pro는 /config에서 켜야 함). 발표 기준 Max, Team, Enterprise는 기본 활성화
• Anthropic API, Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry 지원
• 토큰 소비가 일반 세션보다 크게 많습니다. 에이전트를 수십~수백 개 띄우니 당연합니다

비용 관리 팁도 문서에 있습니다. 큰 런 전에 /model을 확인하고, 강한 모델이 필요 없는 단계는 작은 모델로 라우팅하도록 작업 설명에 명시하면 됩니다.

함께 나온 Opus 4.8은 자기 작업의 불확실성을 더 적극적으로 드러내고, 근거 없는 주장을 덜 한다는 평가입니다. 어드버서리얼 검증 패턴과 맞물려 보면, 모델이 스스로 의심을 표하는 성향이 강해진 게 수백 개 에이전트를 신뢰하는 데 보탬이 됩니다. Fast 모드는 2.5배 속도로 동작하면서 이전 모델보다 3배 저렴해졌습니다. (Anthropic Opus 4.8 발표)

운영자 시각에서 한마디​

Dynamic Workflows의 본질은 에이전트를 더 많이 돌리는 게 아니라 계획을 코드로 옮기는 데 있습니다. 오케스트레이션이 읽고 다시 돌릴 수 있는 스크립트로 굳으면, 매 브랜치마다 같은 리뷰를 같은 방식으로 돌릴 수 있습니다. 일회성 마법이 아니라 반복 가능한 프로세스가 된다는 뜻입니다.

다만 지금은 리서치 프리뷰입니다. 한도도 동작도 바뀔 수 있고, 토큰 비용은 만만치 않습니다. 처음 쓴다면 작은 작업으로 범위를 좁혀 토큰 사용 패턴부터 감을 잡으라는 게 공식 권고입니다.

그래도 방향은 분명해요. 75만 줄 마이그레이션을 11일에 끝냈다는 사례가 과장이 아니라면, 분기 단위 작업의 정의가 다시 쓰이는 중이에요. Skills, Routines, Auto 모드에 이어 이번엔 오케스트레이션 자체가 자동화됐습니다. 따라가는 것만으로도 벅차지만, 한 번쯤 직접 /deep-research부터 돌려보는 게 감을 잡는 가장 빠른 길입니다.

참고 자료​

• Orchestrate subagents at scale with dynamic workflows — Claude Code Docs
• Introducing dynamic workflows in Claude Code — Anthropic Blog
• Introducing Claude Opus 4.8 — Anthropic
• Anthropic releases Opus 4.8 with new 'dynamic workflow' tool (TechCrunch)
• Anthropic Ships Claude Opus 4.8 Alongside Dynamic Workflows, Capped at 1,000 Subagents (MarkTechPost)

출시​

2026년 5월 28일, Anthropic이 Claude Opus 4.8을 출시했고, 모델 ID는 claude-opus-4-8이에요. 직전 모델인 Opus 4.7이 나온 지 41일 만이며, 표준 가격은 입력 $5, 출력 $25(백만 토큰당)로 4.7과 같아요.

직전 글에서 4.7의 방향을 "더 똑똑하기보다 더 맡길 수 있는 모델"이라고 정리했습니다. 4.8은 그 연장선을 한 칸 더 밀어붙입니다. 이번에는 작업 한 건을 통째로 맡기지 않고, 작업을 잘게 쪼개 수백 개의 subagent에게 동시에 맡깁니다. 한 사람에게 맡기던 일을 한 팀에게 맡기는 단계입니다.

한눈에 보는 변화​

가격을 보면 표준 호출 비용은 그대로입니다. 대신 새로 생긴 두 가지 — 동적 워크플로우와 고속 모드 — 가 작업의 단위 자체를 바꿉니다.

핵심 1: 동적 워크플로우​

가장 큰 변화는 수백 개의 subagent를 활용하는 **동적 워크플로우(dynamic workflows)**입니다. Claude Code 안에서 Claude가 직접 작업 계획을 세우고, 그 계획을 orchestration 스크립트로 옮긴 다음, 수백 개의 subagent를 동시에 돌립니다. Anthropic은 이걸 코드를 완성하는 단계를 넘어선 기능으로 설명합니다.

규모 제한은 명확하게 정해져 있습니다.

흐름을 도식으로 보면 이렇습니다.

여기서 중요한 건 분할과 취합을 사람이 짜는 게 아니라는 점입니다. 사람은 "이 작업을 해줘"라고 던지고, 어떻게 쪼갤지와 어떻게 합칠지는 모델이 정합니다. 동시 16개라는 상한이 있어서 1,000개를 한꺼번에 띄우는 게 아니라, 16개씩 흘려보내며 총 1,000개까지 처리하는 구조입니다.

실제로 뭐가 달라지나​

MarkTechPost가 전한 사례가 이 기능의 성격을 잘 보여줍니다. 약 75만 줄 규모의 Rust 코드를 다시 쓰는 작업에서, Opus 4.8이 기존 테스트 스위트의 99.8%를 통과시키며 첫 커밋부터 병합까지 11일 만에 끝냈습니다.

중요한 대목은 기존 테스트 스위트를 합격선으로 삼는다는 점입니다. 수십만 줄 규모의 마이그레이션을 사람이 일일이 검수하는 대신, 통과해야 할 테스트를 기준으로 모델이 스스로 작업의 완료 여부를 판단합니다. 4.7에서 강조됐던 셀프 검증이 워크플로우 전체로 확장된 모양새입니다.

다만 리서치 프리뷰이고, 일반적인 세션보다 토큰을 눈에 띄게 많이 쓴다는 경고가 붙어 있습니다. 가격과 제공 범위가 바뀔 수 있다는 단서도 함께 붙었습니다.

핵심 2: 고속 모드​

두 번째는 2.5배 속도를 내면서 이전 세대보다 가격을 3분의 1로 낮춘 **고속 모드(fast mode)**입니다. 같은 Opus 4.8을 출력 토큰 기준 2.5배 빠르게 돌립니다. 모델 품질은 표준과 동일하고, 속도만 끌어올립니다.

가격은 입력 $10, 출력 $50(백만 토큰당)로 표준의 두 배입니다. 다만 The New Stack에 따르면 이 고속 모드 가격이 이전 모델들의 고속 모드($30/$150)보다 3배 저렴해졌습니다.

쓰는 법도 단순합니다. Claude Code에서 /fast 명령으로 켜고 끄며, 켜진 상태는 작은 번개 아이콘으로 표시됩니다. 다만 청구 방식이 다릅니다. 고속 모드는 플랜 할당량이 아니라 사용량 크레딧(usage credits)에서 차감되므로, 크레딧을 활성화해 둬야 쓸 수 있습니다.

속도가 두 배 이상 빨라진다는 건 단순히 답이 빨리 나온다는 의미를 넘어섭니다. 동적 워크플로우처럼 subagent를 수백 개 돌리는 작업에서는 개별 호출의 속도가 전체 완료 시간을 좌우합니다. 두 기능이 같은 날 나온 게 우연은 아닙니다.

핵심 3: 더 정직해진 모델​

벤치마크 점수 못지않게 강조된 변화가 정직성입니다. Opus 4.8은 자기 작업에서 코드 결함을 놓치는 빈도가 4.7의 약 4분의 1로 줄었다. 작업의 불확실한 부분을 먼저 드러내고, 근거 없는 단언을 덜 한다는 평가도 함께 나왔습니다.

TechCrunch가 전한 Bridgewater Associates의 코멘트가 인상적입니다. 분석의 입력과 출력에서 문제를 능동적으로 짚어내는데, 다른 모델들이 으레 놓치던 지점이라는 것입니다.

이 변화는 동적 워크플로우와 맞물립니다. subagent 수백 개가 동시에 돌아가는 작업에서 모델이 결함을 자주 놓치거나 근거 없이 다 됐다고 보고하면, 사람이 검수할 지점이 폭발적으로 늘어납니다. 결함 누락이 줄고 불확실성을 먼저 알리는 성질은 대규모 위임을 실제로 굴러가게 만드는 전제입니다.

핵심 4: effort 슬라이더와 ultracode​

4.7에서 xhigh effort 레벨이 추가됐던 것을 기억할 것입니다. 4.8은 이 effort 조절을 더 손에 잡히게 바꿨습니다.

• claude.ai와 Cowork에서 슬라이더로 effort 수준을 조절합니다. 품질과 토큰 소비를 직접 저울질하는 방식입니다.
• 기본값은 high effort입니다. 4.7과 같은 토큰을 쓰면서 성능은 더 낫다는 게 Anthropic의 설명입니다.
• Claude Code에는 ultracode 설정이 생겼습니다. xhigh effort에 자동 워크플로우 orchestration을 결합한 모드입니다.

ultracode 외에도 프롬프트에 workflow라는 단어를 넣거나 번들 /deep-research 명령을 쓰면 동적 워크플로우가 작동합니다. 즉 동적 워크플로우는 별도 화면이 아니라 기존 작업 흐름 안에서 자연스럽게 켜지도록 설계됐습니다.

벤치마크​

수치 자체는 4.7만큼 극적이진 않지만, 측정 대상이 달라졌습니다. 단일 코딩 점수보다 에이전트와 실무 작업 쪽에 무게가 실렸습니다.

전체 통과 기준에서 10%를 넘긴 첫 모델이라는 표현이 현재 에이전트 벤치마크의 난이도를 잘 보여줍니다. 부분 점수가 아니라 한 작업을 처음부터 끝까지 완수했는지를 따지면, 아직 대부분의 모델이 한 자릿수에 머문다는 뜻입니다.

정리​

4.7이 사람이 덜 개입해도 되는 방향이었다면, 4.8은 그 위에 한 사람이 못 하던 규모를 한 번에 처리하는 방향을 얹었습니다. 수십만 줄 마이그레이션을 11일에 끝낸 사례가 과장이 아니라면, 위임의 단위가 작업 한 건에서 프로젝트 한 덩어리로 넘어간다고 볼 수 있습니다.

물론 동적 워크플로우는 아직 리서치 프리뷰이고, 토큰을 많이 쓴다는 단서가 붙어 있습니다. 작은 작업이라면 표준 호출이 여전히 합리적입니다. 다만 사람 손으로 며칠 걸리겠다 싶은 큰 작업 앞에서 선택지가 하나 더 생겼다는 건 분명합니다.

출시 직후 외부 클라우드로도 빠르게 퍼졌어요. Databricks Model Serving이 5월 28일 Claude Opus 4.8을 호스팅 모델로 추가했고, AWS도 6월 초 Amazon Bedrock과 AWS의 Claude Platform 양쪽에서 모델 제공을 시작했어요. Bedrock에서는 Guardrails, Knowledge Bases, 데이터 레지던시 같은 관리형 기능과 묶어 쓸 수 있어요.

참고 자료​

• Introducing Claude Opus 4.8 (Anthropic)
• Anthropic releases Opus 4.8 with new 'dynamic workflow' tool (TechCrunch)
• Anthropic Ships Claude Opus 4.8 Alongside Dynamic Workflows and Cheaper Fast Mode (MarkTechPost)
• Claude Opus 4.8 is here: effort controls, dynamic workflows, cheaper fast mode (The New Stack)
• Anthropic Releases Claude Opus 4.8 With Dynamic Workflows, Just 41 Days After Opus 4.7 (Technology.org)
• AWS Weekly Roundup: Claude Opus 4.8 on AWS (AWS Blog)
• Databricks platform release notes (May 2026) (Databricks Docs)

왜 "스위처"가 필요해졌나​

Claude Code가 2024년 말 등장한 직후만 해도 사용량 캡은 거의 의식되지 않았어요. 그게 바뀐 건 2025-08-28이에요. Anthropic이 Pro / Max 플랜에 5시간 롤링 윈도우 + 7일 weekly cap 이중 제한을 도입한 날이에요. Max 5x ($100/mo)와 Max 20x ($200/mo)도 weekly 캡에서 자유롭지 않습니다.

cap에 걸리면 두 가지 길이 있습니다.

1. 그 주가 끝날 때까지 기다립니다
2. 다른 프로바이더로 옮깁니다. Z.AI의 GLM Coding Plan, Moonshot의 Kimi, OpenRouter의 300개 모델 중 하나, 또는 로컬 Ollama를 선택합니다

옮기는 일 자체는 어렵지 않습니다. Claude Code가 환경변수 두 개(ANTHROPIC_BASE_URL와 ANTHROPIC_AUTH_TOKEN)만 보고 동작하기 때문입니다. 예를 들어 GLM으로 옮기는 방법은 Z.AI 공식 가이드 기준으로 두 줄이면 됩니다.

export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"
export ANTHROPIC_AUTH_TOKEN="..."

다른 프로바이더(Kimi, DeepSeek 등)도 같은 패턴이지만 정확한 Anthropic-호환 엔드포인트 URL은 각 프로바이더 공식 문서에서 직접 확인해야 합니다. 같은 회사라도 OpenAI-호환 엔드포인트(/v1)와 Anthropic-호환 엔드포인트가 다르고, 후자가 잘못 표기된 글이 인터넷에 흔합니다.

문제는 하루에 셋넷씩 갈아타게 되는 순간입니다. 회사 계정, 개인 계정, GLM, 로컬 모델, 임시 OpenRouter를 오가며 매번 셸 변수를 바꾸다 보면, 헷갈려서 회사 계정으로 사이드 프로젝트를 돌리기도 하고 캡이 어디서 깎이는지도 까먹습니다. 이 지점에서 등장한 도구가 **CCS (Claude Code Switcher)**입니다.

CCS 한 줄 요약​

@kaitranntt/ccs는 Kai Tran(카이 트란)이 만든 Claude Code용 멀티 프로바이더/멀티 계정 프로필 매니저입니다. MIT 라이선스의 npm 패키지이며, GitHub ★2.2k, 2026-04-29 기준 v7.75.0입니다. 721개 릴리즈와 3,687개 커밋이 쌓일 만큼 개발이 매우 활발합니다.

홈페이지: https://ccs.kaitran.ca/ 저장소: https://github.com/kaitranntt/ccs

자기 소개는 한 문장입니다.

The multi-provider profile and runtime manager for Claude Code and compatible CLIs. — config 파일 갈아엎지 말고, 활성 세션 깨지 않으면서, 몇 초 안에 프로바이더를 옮겨라.

무엇을 지원하나​

설치는 한 줄이면 됩니다.

npm install -g @kaitranntt/ccs
# 또는
bun add -g @kaitranntt/ccs

ccs config 한 번 돌려 초기 설정 후, 프로필 단위로 사용합니다.

지원 프로바이더는 점점 늘어 현재 다음을 포함합니다.

• Claude (Sonnet 4.6, Opus 4.6): 공식
• GLM-5.1, GLM-5-Turbo, GLM-4.7: Z.AI
• Kimi K2.5: Moonshot
• Gemini 3 Pro/Flash: Google (OAuth)
• GPT-5.4 / Codex: OpenAI (OAuth)
• Antigravity Pro/Turbo: ccs agy (OAuth)
• OpenRouter: 300+ 모델 한 번에
• Ollama, llama.cpp, Novita, Alibaba Coding Plan 등 로컬/OpenAI-호환 모두

어떻게 동작하나​

CCS의 핵심은 두 가지 컴포넌트입니다.

첫 번째는 로컬 Anthropic-호환 프록시입니다. GLM/Kimi처럼 이미 Anthropic-호환 엔드포인트를 제공하는 프로바이더는 단순 패스스루로 지나가고, 그렇지 않은 OpenAI-호환 프로바이더(OpenRouter, DeepSeek 등)는 로컬 프록시가 요청과 응답을 변환해 Claude Code가 자기 형식대로 받게 만듭니다.

두 번째는 CLIProxyAPI라는 OAuth 프록시 백엔드입니다. Gemini, Codex, Antigravity처럼 공식 API 키가 없는 OAuth 기반 프로바이더는 이 별도 컴포넌트가 처리하고, 라운드로빈이나 fill-first 같은 토큰 관리 정책도 여기서 돕습니다. 커뮤니티 fork(CLIProxyAPIPlus)도 옵트인으로 쓸 수 있습니다.

활성화는 eval "$(ccs proxy activate)" 같이 셸에 평가시켜 ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN을 그 세션 한정으로 주입하는 방식입니다. 다음 셸이나 다음 디렉토리에서는 다시 깨끗해집니다.

# CCS가 한 번에 처리하는 것
$ ccs glm "이 PR 리뷰해줘"
# 내부적으로:
#  1. ~/.ccs/profiles/glm.settings.json 읽기
#  2. ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic 주입
#  3. ANTHROPIC_AUTH_TOKEN=$GLM_KEY 주입
#  4. claude code 호출

겉으로는 한 줄이지만 안쪽에서 하는 일은 수동 env 셋과 다르지 않고, 그걸 프로필이라는 단위로 캡슐화했을 뿐입니다.

장점은 어디서 나오나​

가장 눈에 띄는 건 명령 하나가 프로파일 하나에 대응한다는 점입니다. 회사 Claude, 개인 Claude, GLM, Kimi, 로컬까지 다섯 개를 셸 변수 갈아끼우지 않고 명령 하나로 분리합니다. 여기서 한 발 더 들어가면 멀티 계정 격리가 있습니다. ccs work와 ccs personal이 같은 머신에서 동시에 다른 Claude 세션을 돌릴 수 있고 weekly cap도 따로 깎이므로, 회사 계정으로 사이드 프로젝트를 돌리다 cap을 축내는 사고가 구조적으로 사라집니다.

비용 이야기도 빼놓기 어렵습니다. 공식 페이지는 "Save $500–1000/month with strategic delegation"이라 적는데, 검증은 본인 워크로드에 따라 다릅니다. 다만 무거운 보일러플레이트는 GLM($10–30/mo)으로 돌리고 설계만 Claude Max로 가는 패턴은 실제로 cap 부담을 크게 줄여줍니다.

나머지 장점은 결이 비슷합니다. Z.AI처럼 API 키를 발급해 쓰는 곳, Gemini처럼 OAuth로 가는 곳, 로컬 Ollama까지 같은 명령 표면 위로 올라오고, proxy.routing 설정으로 "긴 컨텍스트는 Kimi, 추론은 Claude, 백그라운드는 GLM" 식의 자동 라우팅도 짤 수 있습니다. config 파일을 손으로 만지지 않고 비주얼 대시보드로 프로필을 추가/수정할 수 있어, 한국에서 GLM Coding Plan처럼 결제/키 발급이 번거로운 프로바이더를 쓸 때 편합니다. 721 릴리즈에 거의 매일 업데이트될 만큼 개발이 활발해 새 프로바이더가 나오면 빠르게 흡수되는 것도 덤입니다.

단점과 주의사항​

가장 실질적인 부담은 추상화가 두껍다는 점입니다. 프록시가 두 단계(로컬 + CLIProxyAPI)로 끼어들고 프로바이더마다 라우팅 룰이 따로 사는 탓에, "내 요청이 어디로 갔지?"가 헷갈리는 순간이 생깁니다. 로그(~/.ccs/logs/)를 켜둘 가치가 여기 있습니다. 핵심 기능 일부가 CLIProxyAPI라는 별도 프로젝트에 묶여 있다는 점도 같은 맥락인데, 그쪽 이슈가 CCS 동작에 그대로 옮겨붙을 수 있습니다. 버전 업이 매우 빠른 것(v7.75.0, 721 릴리즈)도 새 프로바이더 흡수에는 좋지만 "내 환경에서 안정적인 v7.x"를 고수하려는 보수적 운영에는 부담이라, lockfile로 고정하는 편이 낫습니다.

쓸모의 경계도 분명합니다. 다른 프로바이더를 안 쓰고 회사/개인 두 계정만 격리하는 경우라면 direnv나 .envrc 같은 더 가벼운 도구로 충분하고, CCS는 옮겨 다닐 곳이 셋 이상일 때부터 의미가 생깁니다. 그리고 Codex, Antigravity 같은 비공개 OAuth 프로바이더를 우회로 쓰는 것은 각 서비스 이용약관 위반 소지가 있으니, 회사 환경에서는 한 번 확인하는 편이 안전합니다.

한국에서 쓸 때 걸리는 현실적 지점도 둘 있습니다. Z.AI Coding Plan은 분기 결제(분기당 $30–80), Moonshot Kimi는 위안화 결제라 CCS가 결제까지 해결해주지는 않습니다. 또 이 도구가 weekly cap 회피 수단으로 광고되지만, Anthropic 입장에서 "한 사람이 멀티 계정으로 cap을 돌파"하는 패턴이 쌓이면 정책이 다시 조여질 수 있습니다. 도구의 책임은 아니어도 시장 동학은 의식해 둘 만합니다.

한국 커뮤니티 반응​

CCS 자체에 대한 긱뉴스(news.hada.io) 단일 글은 (작성 시점 기준) 아직 없지만, CCS 같은 도구가 왜 등장했는지를 보여주는 신호는 긱뉴스에 풍부합니다.

• Claude Code Pro Max 5x 요금제, 적당한 사용량에도 1.5시간 만에 할당량은 Max 5x ($100/mo)가 캡 도입 후 적당한 사용량으로도 한 윈도우 안에 끊긴다는 보고입니다. CCS 같은 우회 도구의 시장 자체를 만든 사건입니다.
• Anthropic, 신규 Pro($20/월) 사용자에게 Claude Code 제공 중단?는 정책이 더 조여질 수 있다는 신호입니다. 한 프로바이더에 의존하는 일이 부담스러워지는 환경입니다.
• 월 100달러 Claude Code 예산을 Zed와 OpenRouter로 재배분하기는 캡 회피책을 진지하게 운영 단위로 짠 실전 사례입니다. CCS가 풀려는 문제와 같은 결입니다.
• Z.AI Coding Plan, GLM-5.1 모델 지원: Claude Code 호환은 Z.AI가 Anthropic 호환 엔드포인트를 정식 지원하면서 한국 사용자에게 GLM이 현실적인 두 번째 슬롯이 된 시점을 보여줍니다.
• Claude Code 및 Codex 설정 변경으로 토큰을 절약하는 방법은 한 프로바이더 안에서의 절약 팁입니다. CCS의 시나리오 라우팅이 자동화하려는 작업을 사용자들이 손으로 하던 시기의 사례입니다.
• ccusage: Claude Code/Codex 사용량 분석용 CLI 도구는 사용량을 측정하는 도구가 따로 나왔다는 사실 자체가 캡 시대의 증거임을 보여줍니다. CCS와 같이 쓰면 "어느 프로필에서 얼마 깎였나"가 깔끔하게 보입니다.

스레드(Threads) 쪽에서는 한국어 사용자들이 비슷한 도구를 다양하게 시도 중이라는 점이 눈에 띕니다. vibe proxy로 Claude Code에 AntiGravity와 GLM을 라이드 매핑하거나, oh-my-opencode(★9K)가 Kimi K2.5와 GLM 5를 메인 오케스트레이터로 튜닝하거나, free-claude-code가 NVIDIA NIM 무료 API로 Claude Code를 무료 운영하는 식입니다. 한국 개발자들이 프록시와 멀티 프로바이더라는 패턴 자체에 적극적으로 베팅하고 있다는 의미이고, CCS는 그 흐름에서 가장 잘 정리된 도구 중 하나입니다.

대안 비교​

CCS만 있는 게 아닙니다. 같은 영역에 여러 도구가 경쟁 중입니다.

API 키 기반 프로바이더가 2개 이내이고 라우팅이 필요하다면 claude-code-router가 어울립니다. 별 수도 가장 많고 시나리오 라우팅이 가장 강합니다. OAuth 프로바이더를 포함한 멀티 계정이라면 이 영역에서 거의 유일한 CCS가 맞습니다. 데스크톱 친화성과 멀티 툴 통합 GUI를 원한다면 cc-switch, Anthropic만 쓰면서 단순함을 우선한다면 DIY 또는 claude-code-switch를 고르면 됩니다.

시나리오: 회사 Team + Enterprise 두 계정만 쓴다면​

CCS가 풀려는 문제가 프로바이더 다양화와 OAuth 우회라면, Anthropic만 쓰면서 회사 계정 두 개(Team + Enterprise)만 격리하는 시나리오에는 정확히 그 두 가치가 빠져 있습니다. 이때는 도구 선택이 달라집니다.

이 시나리오의 본질은 두 ANTHROPIC 계정 사이를 빠르고 정확하게 전환하는 한 가지로 줄어듭니다. 다른 프로바이더도, 시나리오 라우팅도, 로컬 모델도 무관합니다.

이 경우라면 direnv가 첫 손에 꼽힙니다. .envrc에 export ANTHROPIC_API_KEY=... 한 줄을 두 회사 디렉토리에 각각 두면 cd만으로 키가 자동 로드됩니다. 이 시나리오에서 가장 큰 리스크는 한 회사 코드에 다른 회사 키가 실수로 흘러가는 사고인데, 디렉토리 경계로 그걸 막아주는 게 direnv의 장점입니다.

더 단순하게 가려면 ~/.zshrc에 alias 두 줄이면 됩니다.

alias cct='ANTHROPIC_AUTH_TOKEN=$TEAM_TOKEN claude'
alias cce='ANTHROPIC_AUTH_TOKEN=$ENT_TOKEN claude'

디렉토리에 묶이지 않아 빠른 대신, 지금 어느 회사 컨텍스트인지는 사람이 기억해야 합니다. Anthropic 전용 미니멀 스위처인 claude-code-switch도 CCS보다 가볍고 이 시나리오에 정확히 맞습니다. CCS를 굳이 쓴다면 멀티 계정 모드만(ccs auth create team / ccs auth create ent) 떼어 쓰는 것도 동작은 하지만, 프로바이더 다양화, 프록시, OAuth 같은 95% 기능을 놀리면서 의존성과 복잡도는 그대로 짊어지게 됩니다. 나중에 GLM 같은 외부 프로바이더로 확장할 가능성이 있을 때만 미리 깔아두는 의미가 있습니다.

Enterprise가 SSO를 강제하면 단순 API 키 토글로는 안 되고 OAuth 로그인 사이클이 필요합니다. 이때는 direnv만으로 부족해 CCS의 OAuth 프로필 분리나 Anthropic Console의 organization 스위처를 써야 하는데, SSO 강제에 잦은 전환까지 겹친 경우가 사실상 CCS를 정당화하는 거의 유일한 회사 시나리오입니다. 정리하면 API 키 기반 두 계정에는 direnv로 충분하고, SSO 강제에 잦은 전환이 겹칠 때만 CCS가 값을 하며, 그 밖에는 대체로 과한 도구입니다.

설정/대화는 공유하면서 계정만 분리하고 싶다면​

같은 시나리오의 변종입니다. 두 회사 계정을 전환은 하되 슬래시 커맨드, MCP, hooks, CLAUDE.md/대화 히스토리는 한 군데에서 공유하고 싶은 경우인데, 이때는 정답이 다릅니다.

먼저 Claude Code가 무엇을 어디 두는지 알면 답이 나옵니다.

핵심은 계정 종속이 토큰 한 가지뿐이라는 점입니다. 토큰만 갈아끼우면 나머지는 자동으로 공유되므로, 답은 direnv로 토큰만 스위칭하는 것입니다. .envrc에 export ANTHROPIC_AUTH_TOKEN=... 한 줄만 두고 ~/.claude/는 건드리지 않으면, 슬래시 커맨드, hooks, MCP, 대화가 전부 자동으로 공유됩니다. 반대로 ccs auth create work 같은 CCS의 isolated profile 모드는 정확히 이 공유를 분리하는 기능이라 피해야 합니다. CCS 자체는 써도 되지만 isolation 옵션은 끄고 토큰만 바꾸는 모드로만 씁니다. 여러 머신 사이에서도 공유하고 싶으면 ~/.claude/를 git으로 관리하는 dotfiles가 답인데, settings.json에 토큰이 평문으로 들어가지 않도록 .gitignore에 settings.local.json을 등록해 두는 정도만 주의하면 됩니다.

다만 Enterprise 데이터 격리는 짚어둘 필요가 있습니다. Enterprise 플랜 약관에 대화 데이터를 다른 organization 환경과 섞지 못하게 하는 조항이 있을 수 있어서, PII, 고객 데이터, 비공개 코드를 다루는 프로젝트라면 ~/.claude/projects/를 공유하는 것이 회사 보안 정책 위반이 될 수 있습니다. 사내 보안팀에 한 번 확인하는 게 안전하고, 우려가 있으면 프로젝트 디렉토리 자체를 회사별로 분리해 자연히 다른 <path-hash>로 떨어뜨리는 패턴(예: ~/work/team/, ~/work/ent/ 두 루트)이 가장 깔끔합니다.

SSO 강제 환경, 한국 회사 현실에 더 가까운 케이스​

위 두 서브섹션은 API 키를 사용자가 직접 발급받을 수 있다는 전제 위에 있습니다. 그런데 국내 대기업, 금융권, 보안 민감 조직 대부분은 그 전제 자체가 깨져 있습니다. Team/Enterprise 플랜에서 SSO를 강제하면 사용자 API 키 발급이 비활성화되고, 인증은 OAuth + IdP MFA 사이클로만 가능합니다. 이 환경에서는 도구 선택이 다시 한 번 달라집니다.

먼저 구조를 짚으면 다음과 같습니다.

1. claude login → 브라우저 → 회사 IdP 로그인 (SSO + MFA) → Anthropic Console → 토큰 발급
2. 토큰은 OS 키체인 또는 ~/.claude/.credentials.json에 저장
3. 토큰은 보통 시간 제한이 있고 (몇 시간~며칠), 만료되면 다시 SSO 사이클
4. 한 머신의 한 OS 유저는 동시에 한 organization의 세션만 보유 가능

즉 SSO 강제 환경에서 두 회사 organization 사이를 전환하려면 결국 logout, 다른 org로 login, 다시 작업 사이클을 돌아야 합니다. IdP가 매번 MFA를 요구하니 도구가 우회할 수 있는 영역이 아닙니다.

실제로 동작하는 패턴은 현실적 운영 순으로 정리할 수 있습니다. 가장 흔한 사례이자 가장 깔끔한 결론은 organization 하나만 쓰는 것입니다. 회사가 Enterprise 하나를 표준화했고 Team이 레거시/POC였다면 둘 다 유지할 이유가 없으니 회사 IT에 정리를 요청하는 편이 낫습니다. 두 organization이 같은 Anthropic Workspace 안의 서로 다른 workspace라면, admin이 workspace를 분리해 두는 것만으로 organization 전환 없이 claude /switch-workspace 식의 in-session 전환이 가능합니다. 이게 되는지부터 회사 IT에 확인하면 가장 매끄럽습니다.

두 organization이 진짜 별개라면 방법이 무거워집니다. 같은 노트북에 OS 계정 두 개를 만들어 각각 SSO 로그인 상태를 독립으로 두면 키체인과 ~/.claude/가 자연히 분리되지만, 설정/대화 공유가 깨져서 dotfiles를 두 OS 유저 사이에 공유하는 추가 작업이 필요합니다. CCS의 OAuth 프로필 분리(ccs auth create work-team / ccs auth create work-ent)는 이론상 이 시나리오에 정확히 맞지만, 회사 IdP가 OAuth 흐름에 거는 추가 검증(IP 화이트리스트, 디바이스 트러스트, MFA 빈도)에 따라 CCS의 토큰 캐시 방식이 IdP 정책과 충돌할 수 있어 시도 전에는 알기 어렵습니다. 사내 보안팀과 사전 협의를 권합니다. 가장 보수적인 선택은 두 회사용 Dev Container나 VM을 따로 띄워 각각 한 organization으로 로그인하는 것인데, 무겁고 호스트 키체인을 못 쓴다는 대가가 따릅니다.

반대로 SSO 환경에서 동작하지 않는 패턴은 다음과 같습니다.

• direnv + ANTHROPIC_AUTH_TOKEN 토글: 사용자 API 키 자체가 없으니 토글할 대상이 없습니다.
• 셸 alias로 토큰 swap: 같은 이유로 동작하지 않습니다.
• "session 토큰을 추출해서 재사용": 만료가 짧고 IdP가 디바이스 핑거프린팅으로 거부할 가능성이 있습니다. ToS의 회색지대이기도 합니다.
• 두 organization의 ~/.claude/.credentials.json을 수동으로 백업/복구: 동작은 할 수 있지만 MFA 빈도 정책을 우회하는 모양새가 되어 정책 위반 우려가 있습니다.

한국 회사 현실에 맞는 결론은, SSO 강제면 organization 전환 자체가 비용이 크다는 사실을 인정하고 두 organization을 동시에 자주 오가지 않는 워크플로우를 설계하는 쪽입니다. 오전엔 Team org에서 한 덩어리, 오후엔 Enterprise org에서 다른 덩어리를 처리하는 식의 시간 분할이, 전환을 도구로 매끄럽게 만드는 것보다 운영 부담이 훨씬 적습니다. 도구는 그 다음 문제입니다.

실전 팁​

블로그, GitHub 이슈, 도구 README의 패턴을 종합해 한국 환경에서 바로 쓸 만한 것만 모았습니다.

가장 큰 가치는 라우팅 자동화보다 자기 워크플로우에 맞는 모델 분리에서 나옵니다. 설계/아키텍처는 ccs(Claude Sonnet), 보일러플레이트/테스트 정리는 ccs glm, 1M 컨텍스트가 필요한 대규모 리뷰는 ccs kimi, 민감 코드는 로컬 ccs ollama 정도가 무난한 시작점입니다. Claude Sonnet 4.6도 1M 컨텍스트를 지원하지만 토큰 값이 비싸서, 큰 monorepo 전체 리뷰는 ccs kimi 한 번이 훨씬 싸게 먹힙니다. 새 prompt가 안정적인지 확인하는 단계라면 첫 5~10번은 무료인 ccs ollama로 돌려보다 만족스러우면 Claude로 옮기면 됩니다.

회사/개인 계정은 무조건 격리하는 편이 좋습니다(ccs auth create work / ccs auth create personal). weekly cap이 섞이지 않아 둘 다 마음 편히 쓸 수 있습니다. 여기에 더해 Claude Max의 weekly cap이 60% 이상 깎였으면 남은 작업의 70% 정도는 GLM으로 돌리는 룰을 정해두면, cap이 갑자기 끊기는 사고가 사라집니다.

라우팅은 단순하게 시작하는 편이 낫습니다. proxy.routing 시나리오 라우팅을 처음부터 복잡하게 짜면 요청이 어디로 갔는지 못 따라가니, 모델을 직접 지정해 일주일 운용하고 패턴이 보이면 그때 룰을 추가합니다. 기본 CLIProxyAPI가 새 프로바이더를 못 잡으면 옵트인 fork(CLIProxyAPIPlus) 활성화부터 시도해 볼 만합니다.

매번 eval 치기 싫으면 ~/.zshrc에 한 줄을 넣어 영구화합니다.

[[ -s "$HOME/.ccs/init.zsh" ]] && source "$HOME/.ccs/init.zsh"

멀티 계정 사고를 디버깅할 때는 CCS_LOG=debug ccs glm "..." 식으로 한 번 돌려보면 어느 base URL로 갔는지, 어느 토큰을 썼는지 정확히 보이니 로그를 켜두는 게 필수입니다.

한 줄로​

CCS는 Claude Code가 환경변수 두 개로 정의되는 도구라는 사실을 그대로 받아들인 도구입니다. 그 두 변수를 프로파일이라는 단위로 정리하고, OAuth 우회와 다중 계정까지 한 명령 표면 위로 올려놓았습니다. weekly cap 시대에 한 프로바이더에만 의지하는 게 부담스러워진 사용자에게 기본기에 가까운 도구가 됐고, 같은 영역에 claude-code-router 같은 더 큰 별 수의 경쟁자도 있습니다. 자기 워크플로우가 옮겨 다닐 곳이 셋 이상인지부터 보고, 그다음에 도구를 고르는 순서가 맞아요.

→ 다음 편: Claude Code Switcher (CCS) 2편: 디렉토리, 설정, 라우팅의 실제 — 사용자 머신의 ~/.ccs/를 직접 들여다보며 instance / shared 격리 모델, config.yaml의 9개 영역, 로컬 프록시의 5단계 변환을 풀어 봅니다.

참고​

• CCS 홈페이지
• kaitranntt/ccs: GitHub (★2.2k)
• @kaitranntt/ccs: npm
• musistudio/claude-code-router: GitHub (★33.2k, 최대 경쟁자)
• farion1231/cc-switch: GitHub (데스크톱 GUI)
• Z.AI GLM Coding Plan: Z.AI
• Managing API key environment variables in Claude Code: Anthropic Support
• Claude Code 사용량 한도: Anthropic Support
• Alorse/cc-compatible-models: 호환 모델 카탈로그
• OpenCode: 오픈 대안

1편의 잔상​

Claude Code Switcher (CCS) — 프로바이더 전환, 멀티 계정, 로컬 모델까지 한 명령으로가 표면의 글이었어요. CCS가 왜 등장했는지, 무엇을 풀고 있는지, 누구에게 언제 맞고 안 맞는지를 다뤘어요. 그 글의 한 단락을 그대로 옮기면 이렇습니다.

CCS는 Claude Code가 환경변수 두 개로 정의되는 도구라는 사실을 그대로 받아들인 도구다. 그 두 변수를 프로파일 이라는 단위로 정리하고, OAuth 우회와 다중 계정까지 한 명령 표면 위로 올려놓았다.

2편은 그 표면 아래를 다룹니다. ~/.ccs/ 한 디렉토리에 무엇이 어떻게 사는지, config.yaml의 어느 키가 무엇을 결정하는지, instance와 shared가 어떻게 갈리는지, 로컬 프록시는 정확히 어떤 변환을 거치는지 살펴봅니다. 1편에서 표 한 줄로만 끝낸 부분을 시스템의 그림으로 풀어 봅니다.

이 글의 모든 디렉토리/키 이름은 사용자 머신의 실제 CCS 설치를 직접 들여다본 결과입니다. 토큰/세션 같은 민감한 값은 보지 않고 구조만 인용합니다.

~/.ccs/ 한 장 지도​

CCS가 머신에 자리 잡으면 홈 디렉토리에 ~/.ccs/ 한 폴더가 생깁니다. 그 안의 트리가 사실상 CCS의 운영 모델 전부인데, 진짜 그림은 심볼릭 링크 체인입니다.

~/.claude/                       ← 사용자의 기존 Claude Code 글로벌 (canonical)
├── settings.json
├── commands/, skills/, agents/, plugins/
└── projects/

~/.ccs/                          ← CCS 영역
├── config.yaml                  ← 메인 설정 (YAML, 11K 정도)
├── .session-secret              ← 세션 비밀 (64B, 절대 공유 금지)
├── .claude/                     ← CCS *번들* (ccs.md, ccs-delegation 스킬 등 자체 주입)
├── cliproxy/bin/                ← CLIProxyAPI 바이너리 (자동 다운로드)
├── cache/, completions/, logs/
│
├── shared/                      ← 사용자 정의 공유 영역
│   ├── settings.json    → ~/.claude/settings.json   (symlink)
│   ├── commands         → ~/.claude/commands         (symlink)
│   ├── skills           → ~/.claude/skills           (symlink)
│   ├── agents           → ~/.claude/agents           (symlink)
│   ├── plugins          → ~/.claude/plugins          (symlink)
│   └── context-groups/default/projects/              (실 디렉토리)
│
└── instances/                   ← per-account 격리 영역
    ├── team/                    ← 회사 Team account
    │   ├── settings.json   → ~/.ccs/shared/settings.json     (symlink)
    │   ├── commands        → ~/.ccs/shared/commands           (symlink)
    │   ├── skills          → ~/.ccs/shared/skills             (symlink)
    │   ├── agents          → ~/.ccs/shared/agents             (symlink)
    │   ├── projects        → ~/.ccs/shared/context-groups/default/projects/  (symlink)
    │   ├── plugins/, .anthropic/, sessions/, session-env/    ← 실 디렉토리
    │   ├── todos/, file-history/, shell-snapshots/, logs/    ← 실
    │   ├── backups/, cache/, debug/, image-cache/, paste-cache/, plans/   ← 실
    │   └── .claude.json, history.jsonl, .session-stats.json,
    │       mcp-needs-auth-cache.json, policy-limits.json, remote-settings.json
    └── enterprise/              ← 회사 Enterprise account (구조 동일)

여기서 눈여겨볼 것은 두 가지입니다. 하나는 2단계 symlink 체인입니다. instances/team/settings.json을 따라가면 ~/.ccs/shared/settings.json으로, 다시 ~/.claude/settings.json으로 이어집니다. 사용자의 기존 Claude Code 글로벌 설정이 모든 인스턴스에 자동 반영된다는 뜻이며, 한 번 만든 슬래시 커맨드, 스킬, MCP가 team과 enterprise 양쪽에서 살아 있는 이유도 여기에 있습니다.

다른 하나는 projects/만 체인이 한 단계라는 점입니다. 대화 히스토리는 instances/team/projects에서 ~/.ccs/shared/context-groups/default/projects/(실 디렉토리)까지만 가고 ~/.claude/projects/까지는 이어지지 않습니다. CCS가 자기 context-group 단위로 대화를 모아 사용자의 평소 Claude Code 대화와 자연히 분리해 두는 것으로, 회사 대화가 개인용 Claude Code에 섞이지 않도록 의도한 끊음입니다.

이 2단계 체인이 이중 구조라고 표현했던 것의 실제 메커니즘이며, 1편의 "공유 vs 분리"가 단일 축이 아니라 어느 단위까지 체인을 잇느냐의 문제였다는 뜻입니다. 5~6절에서 이 단위들을 풀어 봅니다.

config.yaml의 9개 영역​

설정의 거의 전부는 ~/.ccs/config.yaml 한 파일에 모입니다. JSON이 아니라 YAML인 점이 의외인데, 사람이 손으로 읽고 고치기 좋은 쪽을 택한 것으로 보입니다.

키 구조만 추리면 9개 영역으로 나뉩니다.

version:                # 메타
default:                # 기본 프로파일

accounts:               # *instance 단위* 메타
  team:
    context_mode:       # isolated | shared
    context_group:      # shared 일 때 그룹 이름
    continuity_mode:    # 추가 공유 정책
  enterprise:
    ...

profiles:               # 프로바이더 프로파일 (glm, kimi, ollama, ...)

cliproxy:               # OAuth 프록시 백엔드 설정
  backend:
  oauth_accounts:
  providers:
  routing:
    strategy:           # round-robin / fill-first
    session_affinity:
    session_affinity_ttl:

proxy:                  # 로컬 OpenAI-호환 프록시
  profile_ports:        # 프로파일별 포트 매핑
  routing:
    longContextThreshold:

cliproxy_server:        # 원격/로컬 CLIProxy 서버
  remote: { enabled, host, protocol, auth_token }
  fallback: { enabled, auto_start }
  local:   { port, auto_start }

logging:                # 로그 회전·보관
preferences:            # theme, telemetry, auto_update

websearch:              # ★ 8개 fallback 프로바이더
  providers:
    exa, tavily, brave, searxng, duckduckgo, gemini, opencode, grok

# --- 통합 (Claude Code 외부 도구들) ---
copilot:                # GitHub Copilot 라우팅
cursor:                 # Cursor 통합 (ghost_mode 포함)
channels:               # Telegram/Discord/iMessage
thinking:               # opus/sonnet/haiku 별 thinking 기본값
global_env:             # DISABLE_TELEMETRY 등 전역 env 자동 주입

이 9개를 한 번 훑으면 CCS가 단순 스위처가 아니라 Claude Code 주변의 운영 표면 전체를 흡수해 가고 있다는 인상이 분명해집니다. 12절에서 이 중 안 알려진 부분을 따로 추립니다.

Instance 시스템, symlink와 실 상태의 갈림​

instances/<name>/ 디렉토리는 언뜻 보면 Claude Code의 모든 상태를 담은 통 같지만, ls -la로 열어 보면 절반은 shared/로의 symlink이고 나머지 절반만 인스턴스별 실 상태입니다. 둘을 갈라 두면 멘탈 모델이 명확해집니다.

먼저 모든 인스턴스가 공유하는 symlink 항목입니다.

settings.json의 최상위 키 9개는 체인을 따라가 본 결과 다음과 같습니다. 사용자의 기존 ~/.claude/settings.json 스키마 그대로입니다.

alwaysThinkingEnabled
enabledPlugins
env
extraKnownMarketplaces
hooks
permissions
skipAutoPermissionPrompt
skipDangerousModePermissionPrompt
statusLine

다음은 인스턴스별로 격리된 실 상태입니다.

한 가지 눈에 띄는 사실은 이 글의 plan 파일이 instances/team/plans/ccs-hashed-llama.md에 있다는 점입니다(이 항목은 real이고 symlink가 아닙니다). 이 글을 쓰는 동안 사용자의 Claude Code 세션이 team 인스턴스에서 돌고 있었다는 뜻입니다. CCS는 보이지 않게 CLAUDE_CONFIG_DIR 같은 환경변수로 인스턴스 컨텍스트를 끼워 넣습니다.

enterprise 인스턴스는 team보다 가볍게 비어 있는 상태였는데, 활성 사용 중인지 아닌지가 디렉토리 충실도에 그대로 드러납니다. CCS는 인스턴스를 만들 때 symlink와 빈 디렉토리만 만들어 두고, 실제로 사용해야 실 데이터가 채워지는 lazy 모델입니다.

shared/와 context-groups로 1편의 빈칸 메우기​

1편의 "설정/대화는 공유하면서 계정만 분리하고 싶다면" 단락의 진짜 답이 여기 있습니다. CCS는 이 시나리오를 shared/라는 별도 영역과 context_mode/context_group 설정으로 정식 지원합니다.

config.yaml의 accounts: 섹션:

accounts:
  team:
    context_mode: isolated          # 또는 shared
    context_group: default          # shared 일 때만 의미
    continuity_mode: deeper         # 또는 default
  enterprise:
    context_mode: shared
    context_group: default
    continuity_mode: deeper

세 키의 역할:

context_mode: isolated | shared는 인스턴스가 자기 디렉토리에만 사는지, 같은 그룹의 다른 인스턴스와 공유하는지를 정합니다. context_group은 shared일 때 쓸 그룹 이름이며, ~/.ccs/shared/context-groups/<group>/가 그 그룹의 공유 데이터 자리입니다. continuity_mode: deeper는 공유의 깊이를 정하며, deeper는 더 많은 디렉토리를 공유 대상에 포함합니다.

이 셋을 조합해 보면 1편에서 "공유 vs 분리"라고 단순화한 구도가 사실 세 축의 조합임이 드러납니다.

무엇이 공유 가능하고 무엇이 항상 격리되는가​

CCS의 공식 docs는 이 부분을 명시해 두지 않습니다.

CCS only shares workspace context paths (project/session context files). It does not merge or copy authentication credentials between accounts.

— docs/session-sharing-technical-analysis.md

요약 표:

인증은 어떤 경우에도 섞이지 않습니다. 한 인스턴스의 OAuth 토큰이 실수로 다른 인스턴스의 요청에 흘러갈 일이 구조적으로 없으므로, 회사 환경에서 가장 큰 사고 가능성을 시스템 자체가 막아 둡니다.

ccs -r (resume)는 현재 활성 lane만 이어가고, ccs <account> -r은 그 인스턴스의 lane만 이어갑니다. 두 인스턴스 모두 다른 continuity 인벤토리를 가질 수 있다는 점을 의식하고 운영해야 합니다.

4가지 진입점: Target Adapter System​

ccs가 Claude Code만 호출하는 게 아닙니다. CCS는 runtime 자체를 바꾸는 4가지 바이너리를 노출합니다.

내부적으로는 각 바이너리가 CCS_INTERNAL_ENTRY_TARGET 환경변수를 세팅한 후 target resolver에 위임합니다. resolver의 우선순위:

1. CLI 플래그 (--target)
2. 진입 바이너리 자체
3. argv[0] 이름 검출
4. 프로파일별 config
5. 기본값

이 추상화 덕분에 "Claude Code로 GLM 돌리기"와 "Droid로 GLM 돌리기"가 같은 명령 표면 위에서 가능합니다(ccs glm vs ccs --target droid glm). Codex의 경우 자기 ~/.codex/ 상태를 별도 보존하려고 환경변수만 임시로 덮어쓰는 식으로 신경을 더 씁니다.

로컬 프록시 (127.0.0.1:포트)의 5단계 흐름​

ccs glm 같은 OpenAI-호환 프로바이더 명령이 들어오면 다음 5단계를 거칩니다(docs/openai-compatible-providers.md 정리).

1. 127.0.0.1에서 그 프로파일의 로컬 포트 바인딩 (포트는 proxy.profile_ports에서 할당)
2. Claude Code가 보내는 Anthropic 형식 /v1/messages 요청 수신
3. OpenAI chat-completions 형식으로 변환
4. 업스트림 프로바이더로 포워드
5. 스트리밍 응답을 다시 Anthropic SSE로 역변환해 Claude Code에 돌려줌

정리하면 Claude Code는 자기가 Anthropic과 이야기하는 줄 알고, 변환은 프록시 한 점에서만 일어나므로 디버깅 지점도 한 곳으로 모입니다.

Anthropic-호환 엔드포인트는 프록시를 우회합니다. https://api.anthropic.com이나 Z.AI의 /api/anthropic으로 가는 요청은 변환이 필요 없어 그냥 직통하고, 이 분기 덕분에 GLM 사용은 추상화 비용이 거의 0입니다.

CLIProxyAPI 서버 자체는 기본적으로 port 8317에서 동작하는데, cliproxy_server.local.port로 바꿀 수 있고 remote.host를 켜면 다른 머신의 CLIProxy를 쓸 수도 있습니다.

시나리오 라우팅 4종​

CCS가 수동으로 프로바이더를 명시하지 않아도 자동으로 라우팅하는 4가지 시나리오가 있습니다.

config.yaml에 proxy.routing.longContextThreshold 키가 실제로 있어 임계값을 손으로 조절할 수 있습니다. 자동화의 깊이는 워크로드에 따라 잘 맞기도 하고 헷갈리기도 하므로, 처음부터 라우팅 룰을 복잡하게 짜기보다 한 주 동안 단순하게 운영한 뒤 패턴을 보고 추가하는 편이 낫습니다(1편 팁 7절 참조).

CLIProxy 서브시스템, OAuth 프로바이더의 자리​

API 키가 없는 OAuth 기반 프로바이더(Gemini, GitHub Copilot, AWS Kiro 등)는 별도 서브시스템이 책임집니다. ~/.ccs/cliproxy/bin/에 자동 다운로드되는 CLIProxyAPI 바이너리가 그 핵심입니다.

이 서브시스템의 Account manager는 OAuth 토큰의 lifecycle(발급, 갱신, 만료)을 관리하고, Quota manager와 Quota fetcher는 각각 프로바이더별 quota 추적과 자동 failover, 사용량 실시간 동기화를 맡습니다. Auth handler는 Anthropic, Gemini, Copilot, Kiro 등 각 프로바이더의 OAuth 흐름을 처리합니다. Model catalogs에는 프로바이더별 모델 목록과 compatibility 가드가 있으며, codex-plan-compatibility.ts 같은 파일이 plan별로 맞지 않는 모델 조합을 막아 줍니다. Hybrid quota strategy는 round-robin 또는 fill-first(cliproxy.routing.strategy) 방식으로 같은 프로바이더의 여러 OAuth 계정을 어떻게 분산할지 정합니다.

config.yaml의 cliproxy.oauth_accounts가 등록된 OAuth 계정 목록을 담는데, 이 부분은 토큰을 포함하므로 git에 올리면 안 되는 영역입니다. 다음 11절에서 정리합니다.

파일 관리 실전: symlink가 dotfiles의 답입니다​

2절의 symlink 체인을 보고 나면 자연스레 이런 질문이 나옵니다. 내 CCS 환경을 다른 머신에 어떻게 옮기는지, ~/.ccs/를 통째로 git에 넣어도 되는지 궁금해집니다. ~/.ccs/를 versioning하지 않고 ~/.claude/를 versioning해 CCS가 그쪽을 끌어들이게 하면 됩니다.

멘탈 모델: ~/.claude/가 source of truth​

체인의 시작점은 ~/.claude/입니다. CCS의 shared/와 instance들은 그쪽으로 가는 포인터일 뿐입니다. 따라서 dotfiles의 운용 원칙은 하나로 압축됩니다. ~/.claude/를 git으로 관리해 두면, 새 머신에 CCS를 설치하더라도 shared/만 같은 symlink로 다시 걸어 모든 인스턴스가 같은 환경을 보게 됩니다.

git에 올리기 좋은 자산 (~/.claude/ 쪽)​

~/.claude/commands/, ~/.claude/skills/, ~/.claude/agents/에는 각각 슬래시 커맨드, 스킬, 에이전트 정의가 들어가므로 git에 올리기 좋습니다. 글로벌 메모리인 ~/.claude/CLAUDE.md도 관리 대상입니다. ~/.claude/settings.json은 토큰을 직접 적어 두지 않은 경우에만 포함해야 하며, env 필드에 비밀이 있다면 settings.local.json 패턴으로 분리합니다. 실 디렉토리인 ~/.ccs/shared/context-groups/default/에서는 projects/를 빼고 CCS의 그룹 메타만 versioning하는 식으로 관리합니다.

~/.ccs/.claude/ (CCS 번들)은 npm 패키지 일부라 install 시 자동으로 따라옵니다. 직접 versioning 할 필요 없습니다.

절대 git 금지 (자격증명, 세션, 트랜스크립트)​

~/.ccs/config.yaml에는 OAuth 토큰/refresh_token이 있으므로 머신별로 보관하고, 세션 비밀인 ~/.ccs/.session-secret도 제외합니다. ~/.ccs/instances/*/.anthropic/의 Anthropic OAuth와 계정 식별자를 포함한 ~/.ccs/instances/*/.claude.json도 올리면 안 됩니다.

~/.ccs/instances/*/sessions/, session-env/에는 세션과 세션별 env가 있어 토큰 환경변수가 들어갈 가능성이 있습니다. ~/.ccs/instances/*/history.jsonl, file-history/에는 명령과 파일 history가 남아 회사 코드의 흔적이 섞일 수 있습니다. 대화 히스토리 본체인 ~/.ccs/shared/context-groups/*/projects/도 PII나 회사 코드를 포함할 가능성이 있으므로 제외합니다. 바이너리와 휘발성 데이터가 담긴 ~/.ccs/cliproxy/, cache/, logs/, 평소 Claude Code 대화 히스토리인 ~/.claude/projects/도 git에 올리지 않습니다.

새 머신 부트스트랩 4단계​

dotfiles가 ~/.claude/만 들고 있다고 할 때 새 머신에서 같은 환경을 만들려면:

1. dotfiles를 clone해 ~/.claude/를 채웁니다.
2. npm install -g @kaitranntt/ccs로 CCS를 설치합니다.
3. ccs config로 초기 ~/.ccs/ 골격을 생성합니다.
4. symlink를 재구성합니다. ~/.ccs/shared/{commands,skills,agents,plugins,settings.json}을 ~/.claude/의 동명 항목으로 link하며, 한 줄 스크립트로 자동화하기를 권장합니다.

ln -sf ~/.claude/commands       ~/.ccs/shared/commands
ln -sf ~/.claude/skills         ~/.ccs/shared/skills
ln -sf ~/.claude/agents         ~/.ccs/shared/agents
ln -sf ~/.claude/plugins        ~/.ccs/shared/plugins
ln -sf ~/.claude/settings.json  ~/.ccs/shared/settings.json

이 다섯 줄로 새 머신에서도 1편의 instance들이 평소 환경을 그대로 봅니다. OAuth 인증만 각 인스턴스에서 새로 하면 끝입니다.

격리의 운영 이점​

한 인스턴스가 망가져도(plugins/ 깨짐, policy-limits.json 누락 등) 다른 인스턴스는 그대로이므로 단일 장애점이 줄어드는 부수 효과가 있습니다. 인스턴스 단위 백업에는 tar czf team-backup.tgz -C ~/.ccs/instances team을 씁니다. symlink는 그대로 보존하며, 옵션 -h를 추가하면 링크가 가리키는 파일까지 따라가 archive합니다. 복원할 때 같은 dotfiles 환경을 가정하므로 보통은 symlink를 그대로 두는 편이 의미 있습니다.

config.yaml의 비공식 영역들​

CCS의 README가 강조하지 않지만 config.yaml 키만 봐도 드러나는, 단순 스위처라기엔 풍부한 통합이 여럿입니다.

가장 눈에 띄는 것은 WebSearch fallback입니다. websearch.providers 아래에 exa, tavily, brave, searxng, duckduckgo, gemini, opencode, grok 여덟 곳이 등록돼 있어, Claude Code의 WebSearch가 Anthropic 밖 8개 프로바이더로 넘어갈 수 있습니다. docs/websearch.md가 별도 문서로 있을 만큼 일급 통합입니다. 외부 에디터/툴 통합도 넓어서, copilot.account_type, rate_limit, model로 GitHub Copilot을 프로바이더 한 슬롯처럼 다루고 cursor.ghost_mode/cursor.port로 Cursor의 ghost-mode까지 건드립니다. channels.selected, channels.unattended를 통해 Telegram, Discord, iMessage로 Claude에게 일을 시키는 통합도 있습니다(1편의 free-claude-code 텔레그램 봇 사례와 같은 결입니다).

세밀한 정책 키도 있습니다. thinking.tier_defaults는 opus, sonnet, haiku별로 thinking 기본 모드를 다르게 잡게 해주고(Opus는 항상 deep thinking, Haiku는 끄는 식), global_env.env의 DISABLE_BUG_COMMAND, DISABLE_ERROR_REPORTING, DISABLE_TELEMETRY는 보안, 프라이버시에 민감한 회사 환경에서 텔레메트리를 자동으로 꺼줍니다. cliproxy.routing.session_affinity와 session_affinity_ttl은 같은 세션을 같은 OAuth 계정으로 sticky하게 묶는 정책입니다. 이런 영역들은 CCS가 단순 스위처에서 운영 플랫폼으로 진화 중이라는 신호입니다.

한 줄로​

1편이 CCS의 표면이었다면 2편은 안쪽입니다. 안쪽을 보고 나면 "프로파일로 옮겨 다닌다"는 1편의 단순한 설명이 사실은 instance 격리, shared 공유, OAuth 분리, OpenAI와 Anthropic 사이의 변환, 시나리오 라우팅, 여러 통합 지점이라는 축들로 짜여 있다는 게 보입니다. 추상화가 두껍다는 1편의 단점 평가는 그래서 정확하지만, 그 두께가 풀고 있는 문제도 같이 두껍다는 사실이 디렉토리 한 통에 적나라하게 드러납니다.

다음 편이 있다면 두 갈래 중 하나일 가능성이 커요. proxy.routing 시나리오를 실제 워크로드로 맞춰 보는 실측 운영 글이거나, CCS와 dotfiles, Anthropic Workspaces를 엮는 멀티-머신 계정 운영 글일 거예요. 어느 쪽이 먼저 나올지는 다음 글에서 정할게요.

참고​

• CCS 1편 — 프로바이더 전환, 멀티 계정, 로컬 모델까지 한 명령으로
• CCS 홈페이지
• kaitranntt/ccs: GitHub
• docs/codebase-summary.md: 아키텍처 4 레이어
• docs/session-sharing-technical-analysis.md: 공유/격리 모델(이 글의 5~6절 출처)
• docs/openai-compatible-providers.md: 로컬 프록시 변환 흐름
• docs/project-overview-pdr.md: 5 서브시스템 개요
• docs/websearch.md: WebSearch 8 fallback 상세
• Z.AI Claude Code 가이드: Anthropic-호환 엔드포인트의 공식 출처

터미널에서 긴 프롬프트는 힘들다​

Claude Code를 쓰다 보면 몇 줄 넘는 프롬프트를 치고 싶을 때가 종종 있어요. 들여쓰기가 있거나, 코드를 붙이거나, 한글 IME 상태에서 복잡한 편집이 필요한 순간이에요. 터미널의 한 줄 편집기는 이런 상황에 약해요.

이럴 때 Claude Code 프롬프트를 외부 에디터로 열어서 쓸 수 있습니다. 방법 자체는 간단한데, 운용하다 보면 사소한 함정이 하나 있어 같이 정리합니다.

$EDITOR와 Ctrl+X Ctrl+E를 쓰는 기본 방법​

Claude Code는 프롬프트 입력 중 Ctrl+X 뒤이어 Ctrl+E 를 누르면 $EDITOR 환경변수에 지정된 에디터를 띄웁니다. 내부적으로는 claude-prompt-<uuid>.md 같은 임시 파일을 만들고 그걸 에디터에 넘깁니다. 편집 후 저장하고 닫으면 그 내용이 그대로 프롬프트에 입력됩니다.

가장 단순한 세팅:

# ~/.zshrc
export EDITOR='nvim'

이러면 Ctrl+X Ctrl+E로 nvim이 뜨고, :wq로 닫으면 내용이 Claude Code 프롬프트로 들어옵니다.

참고로 최근 Claude Code 버전은 Ctrl+G도 같은 동작으로 바인딩돼 있습니다. 둘 다 테스트해 보고 손에 맞는 것을 쓰면 됩니다.

전역 EDITOR는 nvim, Claude만 Cursor로​

그런데 EDITOR 환경변수는 git, crontab, less 등 여러 곳에서 참조합니다. 저는 이걸 nvim으로 둔 상태가 편해서 바꾸고 싶지 않아요. Claude Code 프롬프트만 GUI 에디터(Cursor, VSCode)로 띄우고 싶을 때는 함수로 감싸서 EDITOR를 이 프로세스 범위에서만 오버라이드하면 됩니다.

제 ~/.zshrc에 들어 있는 것은 이것입니다.

cc() {
  # VSCode 쓸 때
  # EDITOR="code -w" command claude "$@"

  # Cursor 쓸 때
  EDITOR="/Applications/Cursor.app/Contents/Resources/app/bin/cursor -w" command claude "$@"
}

중요한 점은 두 가지입니다.

• command claude: alias나 동명 함수가 걸려 있어도 실제 claude 바이너리를 실행하도록 우회합니다.
• -w 플래그: Cursor/VSCode는 기본적으로 연 뒤 바로 셸로 제어를 반환합니다. -w(또는 --wait)를 붙여야 에디터 창이 닫힐 때까지 대기합니다. 없으면 Claude Code가 빈 파일을 바로 읽어 갑니다.

이제 터미널에서 cc만 실행하면 Claude Code가 뜨고, 프롬프트 편집 시 Cursor로 열립니다. 다른 툴들은 EDITOR=nvim을 그대로 봅니다.

실제 동작​

1. 프롬프트에서 Ctrl+X Ctrl+E​

2. Cursor에 임시 파일이 열립니다​

파일명은 claude-prompt-<uuid>.md 형식입니다. 마크다운이라 코드 블록이나 리스트도 편하게 쓸 수 있습니다.

3. 저장하고 닫으면 프롬프트로 들어옵니다​

여기서 한 가지 이상한 게 생겼습니다.

![복귀 후 프롬프트에 ^[[O^[I 이상 문자가 끼어든 상태

프롬프트 앞부분의 기존 텍스트와 Cursor에서 쓴 내용 사이에 ^[[O^[[I^[[O^[[I^[[O가 끼어 있습니다. 정체가 무엇일까요?

^[[O, ^[[I의 정체​

이 문자들은 Focus Reporting에서 나옵니다.

터미널에는 포커스 리포팅(Focus Reporting) 이라는 기능이 있습니다. ANSI/xterm 스펙의 DEC Private Mode 1004. 이게 켜져 있으면 터미널 창의 포커스가 들어오고 나갈 때 아래 두 이스케이프 시퀀스가 터미널에 주입됩니다.

이걸 왜 쓰느냐면, vim/tmux 같은 TUI 앱이 유휴 상태일 때 렌더링을 멈추거나 커서 스타일을 바꾸기 위해 필요합니다. 터미널이 보내주는 이 이벤트로 현재 창이 활성인지 아닌지를 알 수 있습니다.

문제는 이 지점입니다.

1. Claude Code가 Cursor를 띄웁니다. 이 순간 터미널 포커스가 제 터미널에서 Cursor 윈도우로 이동하고, 터미널이 ^[[O (focus-out)을 내보냅니다.
2. Cursor에서 저장/종료하면 포커스가 다시 터미널로 돌아옵니다. ^[[I (focus-in)이 내보내집니다.
3. 창 전환을 두세 번 하다 보면 여러 번의 in/out이 생깁니다.
4. 이 이스케이프 시퀀스들은 stdin 버퍼에 쌓입니다. Claude Code가 에디터 종료 후 다시 입력 읽기를 시작할 때, 앞서 쌓인 것들을 프롬프트 텍스트로 흡수합니다.

정리하면 Cursor/VSCode 같은 별도 윈도우 GUI 에디터를 띄울 때만 이 현상이 생깁니다. 터미널에서 포커스가 실제로 왔다갔다 하기 때문입니다.

해결 방법​

1순위: nvim / vim / helix / micro​

같은 터미널 세션 안에서 도는 TUI 에디터는 포커스가 창 단위로 움직이지 않습니다. 창은 하나, 안에서 그냥 화면이 바뀔 뿐입니다. focus-in/out 이벤트 자체가 생기지 않습니다.

export EDITOR='nvim'

제 경험상 이게 제일 안정적이에요. nvim이 충분히 좋은 마크다운 편집기이기도 하고요.

2순위: 그래도 Cursor/VSCode를 쓰고 싶다면​

몇 가지 부분 해결책이 있지만 완벽한 건 없습니다.

• 복귀 후 섞인 ^[[ 시퀀스를 backspace로 수동 제거한 뒤 Enter를 누릅니다.
• 터미널 앱 설정에서 focus reporting을 비활성화합니다(Ghostty, iTerm2 등에 옵션이 있습니다). 단 vim/tmux 쪽 기능도 같이 잃습니다.
• Cursor/VSCode를 쓰되 cc 함수 내에서 임시로 focus reporting을 꺼 주는 래퍼를 끼웁니다. 번거로운 방법입니다.

깔끔한 길은 첫 번째예요. 긴 프롬프트 편집에 IDE급 기능이 꼭 필요한 게 아니라면 TUI 에디터 쪽이 나아요.

요약​

• Claude Code 프롬프트는 Ctrl+X Ctrl+E (또는 Ctrl+G)로 $EDITOR를 호출합니다.
• 전역 EDITOR를 건드리지 않고 싶다면 cc() 함수 패턴으로 Claude에 한정해 오버라이드합니다. -w 플래그를 꼭 붙여야 합니다.
• Cursor/VSCode를 쓰면 포커스 리포팅 시퀀스가 프롬프트에 섞이는 부작용이 있습니다.
• 제일 안정적인 조합은 TUI 에디터(nvim 등) + EDITOR=nvim입니다.

참고 링크​

• ClaudeLog — How to Edit Prompts in External Editor
• GitHub anthropics/claude-code #18990 — 외부 에디터 설정 관련 피드백
• Claudefast — Claude Code Keybindings Guide
• xterm Focus Reporting 스펙 — DECSET ?1004h / ?1004l