개요
요즘 채용시장이 다시 살아나면서 이런 우스갯소리가 나왔다.
AI 토큰값보다 개발자 연봉이 싸서 개발자를 다시 고용한다.
농담처럼 들리지만, AI 시대에 토큰 비용이 얼마나 중요한 문제가 되었는지를 잘 보여준다. AI 빅테크 기업들은 약속이라도 한 듯 구독형 요금제를 내놓았고, 그 가격은 점점 높아지고 있다. 이제 AI가 업무의 필수 도구가 된 시대에, 토큰 최적화는 선택이 아니라 필수다.
하지만 AI 토큰값을 절약하면서도, 성능은 그 전과 동일하게 혹은 더 좋게 유지하는 것은 쉽지 않다.
그래서 이 글에서는 실전에서 검증된 토큰 최적화 설정을 정리한다. (이전 글에서 Context Rot의 원인과 운영 원칙을 다뤘다.)
2025년 9월, Anthropic 해커톤에서 우승한 Affaan Mustafa가 10개월간 Claude Code를 사용하며 최적화한 시스템 everything-claude-code를 공개했다. 이 레포지토리는 Claude Code뿐 아니라 Cursor, Codex, Gemini CLI 등 AI 코딩 에이전트 전반에 적용할 수 있는 설정을 포함하고 있으며, 현재 17만에 가까운 GitHub stars를 보유하고 있다.
이 글에서는 해당 레포지토리의 Claude Code 설정 방법을 중심으로 정리한다.
핵심 설정
settings.json
사실 일단 아래 settings.json을 복사해서 사용하는 게 거의 80% 이상의 최적화를 진행하는 것이다.
{
"model": "sonnet",
"env": {
"MAX_THINKING_TOKENS": "10000",
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
},
"permissions": {
"deny": [
"Read(~/.ssh/**)",
"Read(~/.aws/**)",
"Read(**/.env*)",
"Write(~/.ssh/**)",
"Write(~/.aws/**)",
"Bash(curl * | bash)",
"Bash(ssh *)"
]
}
}model: 기본 모델을 Sonnet으로 설정. 코딩 작업의 90%에 적합하다.MAX_THINKING_TOKENS: 사고 토큰 상한. 무한정 쓰면 컨텍스트가 빠르게 소모된다.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: 컨텍스트 50% 소비 시 자동 압축 트리거.permissions.deny: 민감한 경로와 위험한 명령어를 차단한다.
환경 변수
# 패키지 매니저 지정 (자동 감지 대신 명시)
CLAUDE_PACKAGE_MANAGER=npm
# 서브에이전트 모델 지정
CLAUDE_CODE_SUBAGENT_MODEL=haiku
# Hook 프로필 (standard / minimal / full)
ECC_HOOK_PROFILE=standard
# 특정 Hook 비활성화 (필요 시)
ECC_DISABLED_HOOKS="pre:bash:tmux-reminder"시스템 프롬프트 별칭
작업 유형별로 다른 컨텍스트를 주입할 수 있다.
alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"'
alias claude-review='claude --system-prompt "$(cat ~/.claude/contexts/review.md)"'
alias claude-research='claude --system-prompt "$(cat ~/.claude/contexts/research.md)"'플러그인 설치
everything-claude-code 플러그인을 설치하면, 슬래시 커맨드로 다양한 기능을 사용할 수 있다.
/plugin marketplace add https://github.com/affaan-m/everything-claude-code
/plugin install everything-claude-code@everything-claude-codegit clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code
npm install
# macOS/Linux
./install.sh --profile full
# 특정 언어만
./install.sh typescript python# 플러그인으로 설치한 경우
/ecc:plan "Add user authentication"
# 수동 설치한 경우
/plan "Add user authentication"핵심 구조
위에 설정이 사실 끝이다. 아래는 좀 더 세부적인 개념과 내용을 다룬다.
everything-claude-code는 Claude Code의 설정을 다섯 가지 계층으로 나눈다.
Skills: 재사용 가능한 워크플로우
Skills는 프롬프트, 구조, 지원 파일, 코드맵을 포함하는 범위가 정해진 워크플로우 번들이다.
pmx-guidelines.md # 프로젝트별 패턴
coding-standards.md # 언어별 모범 사례
tdd-workflow/ # 여러 파일 스킬 + SKILL.md
security-review/ # 체크리스트 기반 스킬슬래시 커맨드로 호출한다:
/tdd— 테스트 우선 개발/e2e— E2E 테스트/refactor-clean— 불필요한 코드 정리
같은 작업을 세 번 이상 반복하면 Skill로 승격시켜야 한다.
1. 반복되는 프롬프트를 발견한다
2. 패턴을 추출한다
3. ~/.claude/skills/에 Skill로 정의한다
4. 슬래시 커맨드로 호출한다초반에 재사용 가능한 워크플로우를 구축하는 데 시간을 쏟았다. 만드는 과정은 지루했지만, 복리 효과는 엄청났다. — Affaan Mustafa
Hooks: 이벤트 기반 자동화
Hooks는 특정 이벤트에서 실행되는 트리거 기반 자동화다. 도구 호출과 생명주기 이벤트에서 동작한다.
| Hook 타입 | 목적 |
|---|---|
| PreToolUse | 도구 실행 전 — 유효성 검증, 알림 |
| PostToolUse | 도구 실행 후 — 포맷팅, 피드백 루프 |
| UserPromptSubmit | 메시지 전송 시 |
| Stop | Claude 응답 완료 시 |
| PreCompact | 컨텍스트 압축 전 — 중요 상태 저장 |
| Notification | 권한 요청 시 |
실전에서 유용한 Hook 예시:
{
"hooks": {
"PreToolUse": [
{
"matcher": "tool == \"Bash\" && tool_input.command matches \"(npm|pnpm|yarn|cargo|pytest)\"",
"hooks": [
{
"type": "command",
"command": "if [ -z \"$TMUX\" ]; then echo '[Hook] Consider tmux for long-running commands' >&2; fi"
}
]
}
],
"PostToolUse": [
{
"matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\.(ts|tsx)$\"",
"hooks": [
{
"type": "command",
"command": "npx tsc --noEmit 2>&1 | head -20"
}
]
}
],
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "git diff --name-only | xargs grep -l 'console.log' 2>/dev/null && echo '[Hook] console.log detected in modified files' >&2 || true"
}
]
}
]
}
}- PreToolUse: 장시간 실행 명령어 전에 tmux 사용을 알린다
- PostToolUse: TypeScript 파일 수정 후 자동으로 타입 체크를 실행한다
- Stop: 응답 완료 시 수정된 파일에
console.log가 남아있는지 확인한다
JSON을 직접 작성하기 번거롭다면 /hookify 플러그인으로 대화형으로 Hook을 생성할 수 있다.
Subagents: 작업 위임
Subagents는 제한된 범위로 작업을 위임받는 프로세스다. 백그라운드/포그라운드에서 실행되며, 특정 도구 권한으로 샌드박싱된다.
planner.md # 기능 구현 계획
architect.md # 시스템 설계
tdd-guide.md # 테스트 우선 개발
code-reviewer.md # 품질/보안 검토
security-reviewer.md # 취약점 분석
build-error-resolver.md
e2e-runner.md # Playwright 테스트
refactor-cleaner.md # 불필요한 코드 제거
doc-updater.md # 문서 동기화Subagents는 요약으로 반환하여 메인 컨텍스트를 절감한다. 하지만 orchestrator의 의미적 컨텍스트가 부족할 수 있으므로, 반복적 검색 패턴을 사용한다.
1. Orchestrator가 모든 sub-agent 반환을 평가한다
2. 수락 전에 후속 질문을 한다
3. Sub-agent가 소스로 돌아가 답변을 반환한다
4. 충분할 때까지 반복한다 (최대 3 사이클)Orchestrator의 순차적 단계는 다음과 같다.
Phase 1: RESEARCH (Explore agent) → research-summary.md
Phase 2: PLAN (planner agent) → plan.md
Phase 3: IMPLEMENT (tdd-guide agent) → code changes
Phase 4: REVIEW (code-reviewer agent) → review-comments.md
Phase 5: VERIFY (build-error-resolver)→ done or loop back[핵심 규칙]
- 각 agent는 하나의 명확한 입력과 하나의 명확한 출력을 가진다
- 출력이 다음 단계의 입력이 된다
- 단계 사이에
/clear를 사용한다 - 중간 출력을 파일에 저장한다
Rules: Instinct(본능)
Rules는 모델이 항상 따라야 할 무의식적 규칙이다. everything-claude-code에서는 이것을 "instinct"라고 부른다.
security.md # 하드코딩된 시크릿 금지, 입력 검증
coding-style.md # 불변성 우선, console.log 커밋 금지
testing.md # TDD 워크플로우, 80% 커버리지
git-workflow.md # 커밋 형식, PR 프로세스
agents.md # 서브에이전트 위임 시기
performance.md # 모델 선택, 컨텍스트 관리[CLAUDE.md와의 차이]
CLAUDE.md는 모든 대화에 로드된다 — 핵심 원칙만 넣어야 한다- Rules는 카테고리별로 분리되어 관리가 쉽다
MCPs: 외부 서비스 연동
MCPs(Model Context Protocol)는 외부 서비스를 Claude Code에 연결한다. 하지만 컨텍스트 윈도우를 가장 많이 잡아먹는 요소이기도 하다.
200K 컨텍스트 윈도우가 도구 활성화 시 70K로 줄어들 수 있다. — everything-claude-code
설정(설치): 20~30개 — 필요한 것은 모두 설치
활성화: 10개 이하 — 현재 작업에 필요한 것만
활성 도구: 80개 미만 — 이 이상은 컨텍스트 낭비이미 강력한 CLI가 있는 도구(GitHub, Supabase, Vercel 등)는 MCP 대신 Skills로 래핑하는 것이 토큰 절감에 도움된다.
{
"github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
"memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] },
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
},
"vercel": { "type": "http", "url": "https://mcp.vercel.com" },
"context7": { "command": "npx", "args": ["-y", "@context7/mcp-server"] }
}활성 MCP 확인: /mcp
토큰 최적화
모델 전략
| 작업 유형 | 권장 모델 | 이유 |
|---|---|---|
| 탐색/검색 | Haiku | 빠르고 저렴, 파일 찾기에 충분 |
| 단순 편집 | Haiku | 단일 파일, 명확한 지시 |
| 다중 파일 구현 | Sonnet | 코딩에 최적화된 균형 |
| 복잡한 아키텍처 | Opus | 깊은 추론 필요 |
| PR 검토 | Sonnet | 맥락 이해, 미묘함 포착 |
| 보안 분석 | Opus | 취약점을 놓칠 수 없음 |
| 복잡한 버그 디버깅 | Opus | 전체 시스템 맥락 유지 필요 |
기본값은 Sonnet. Opus로 올려야 하는 시점:
- 첫 시도가 실패했을 때
- 5개 이상의 파일을 동시에 다뤄야 할 때
- 아키텍처 결정이 필요할 때
- 보안이 중요한 코드일 때
도구 최적화 — mgrep
everything-claude-code에서는 기본 검색 대신 mgrep을 권장한다.
# 플러그인으로 설치
/plugin marketplace add https://github.com/mixedbread-ai/mgrep
# 사용
mgrep "function handleSubmit" # 로컬 검색
mgrep --web "Next.js 15 app router" # 웹 검색50개 작업 벤치마크에서, mgrep + Claude Code는 grep 기반 워크플로우 대비 약 2배 적은 토큰을 사용했다. — everything-claude-code
세션 간 메모리 공유
.claude 폴더의 임시 파일에 진행 상황을 저장하고, 다음 세션에서 해당 파일 경로를 제공한다.
- 검증된 작동 방식
- 시도했으나 실패한 접근법
- 아직 시도하지 않은 접근법과 남은 작업동적 시스템 프롬프트 주입으로 세션 시작 시 이전 컨텍스트를 자동 로드할 수도 있다.
claude --system-prompt "$(cat memory.md)"메모리 지속성 Hooks
| Hook | 용도 |
|---|---|
| PreCompact | 컨텍스트 압축 전 중요 상태를 파일에 저장 |
| Stop | 세션 종료 시 학습 내용 저장 |
Stop Hook을 사용하는 이유: UserPromptSubmit은 모든 메시지마다 실행되어 지연이 발생하지만, Stop Hook은 세션 종료 시 한 번만 실행되어 가볍다.
병렬화
Fork
/fork # 큐 메시지 대신 병렬 작업용 대화 분기메인 채팅은 코드 변경에 사용하고, fork는 코드베이스에 대한 질문이나 외부 서비스 조사에 활용한다.
Git Worktrees
git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b
cd ../project-feature-a && claude
# 다른 터미널
cd ../project-feature-b && claude각 worktree에서 별도 Claude 인스턴스를 실행한다. 파일 충돌 없이 병렬 작업이 가능하다.
보안: AgentShield
AI Agent는 셸을 실행하고, 파일을 읽고 쓰고, 외부 API를 호출한다. 이것은 곧 공격 표면이 된다.
실제 CVE 사례
| CVE | 심각도 | 내용 |
|---|---|---|
| CVE-2025-59536 | CVSS 8.7 | 신뢰된 대화 전에 프로젝트 코드 실행 |
| CVE-2026-21852 | 높음 | ANTHROPIC_BASE_URL 리다이렉션으로 API 키 유출 |
프롬프트 인젝션은 더 이상 재미있는 실험이 아니다. 에이전트 시스템에서는 셸 실행, 비밀 노출, 워크플로우 악용으로 직결된다.
최소한의 보안 설정
{
"permissions": {
"deny": [
"Read(~/.ssh/**)",
"Read(~/.aws/**)",
"Read(**/.env*)",
"Bash(curl * | bash)",
"Bash(ssh *)"
]
}
}샌드박싱
위험한 작업은 격리된 환경에서 실행한다.
services:
agent:
build: .
user: "1000:1000"
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
networks:
- agent-internal
networks:
agent-internal:
internal: true숨겨진 문자 검사
# 유니코드 제로 폭 문자
rg -nP '[\x{200B}\x{200C}\x{200D}\x{2060}\x{FEFF}\x{202A}-\x{202E}]'
# 스크립트 인젝션
rg -n '<!--|<script|data:text/html|base64,'
# 위험한 명령어
rg -n 'curl|wget|nc|scp|ssh|enableAllProjectMcpServers'AgentShield는 이런 보안 문제를 체계적으로 검사하는 도구다. 의심스러운 Hooks, 숨겨진 인젝션 패턴, 과도한 권한, 위험한 MCP 설정을 탐지한다. 핵심 원칙은 '편의성이 격리를 앞지르지 않도록 한다.' 는 것이다.
마무리
[everything-claude-code의 핵심]
- 설정을 아키텍처가 아닌 미세 조정처럼: 처음부터 완벽한 설정을 만들려 하지 말고, 쓰면서 점진적으로 개선한다.
- 컨텍스트 윈도우는 귀중하다: 미사용 MCP/플러그인은 비활성화한다.
- 반복 작업은 자동화한다: 포맷팅, 린팅, 타입 체크는 Hooks로 처리한다.
- 재사용 가능한 패턴에 투자하라: Skills, Agents, Commands는 만들 때 지루하지만, 복리처럼 생산성이 불어난다.
- 보안은 처음부터: AI Agent가 셸을 실행하는 순간, 보안은 선택이 아니다.
AI Agent를 "쓰는 것"과 "잘 쓰는 것"의 차이는 도구의 성능이 아니라 운영 체계의 유무다.