주다훤 블로그

Claude Code 최적화 설정 ㅡ everything-claude-code

토큰 최적화, Skills, Hooks, Subagents, 보안까지
2026.04.29발행·17
Claude Code 최적화 설정 ㅡ everything-claude-code

개요

요즘 채용시장이 다시 살아나면서 이런 우스갯소리가 나왔다.

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% 이상의 최적화를 진행하는 것이다.

~/.claude/settings.json
{
  "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 *)"
    ]
  }
}

환경 변수

.env
# 패키지 매니저 지정 (자동 감지 대신 명시)
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"

시스템 프롬프트 별칭

작업 유형별로 다른 컨텍스트를 주입할 수 있다.

~/.zshrc
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 플러그인을 설치하면, 슬래시 커맨드로 다양한 기능을 사용할 수 있다.

1. 플러그인 설치
/plugin marketplace add https://github.com/affaan-m/everything-claude-code
/plugin install everything-claude-code@everything-claude-code
2. Rules 설치
git 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
3. 사용
# 플러그인으로 설치한 경우
/ecc:plan "Add user authentication"
 
# 수동 설치한 경우
/plan "Add user authentication"

핵심 구조

위에 설정이 사실 끝이다. 아래는 좀 더 세부적인 개념과 내용을 다룬다.

everything-claude-code는 Claude Code의 설정을 다섯 가지 계층으로 나눈다.

Skills: 재사용 가능한 워크플로우

Skills는 프롬프트, 구조, 지원 파일, 코드맵을 포함하는 범위가 정해진 워크플로우 번들이다.

~/.claude/skills/
pmx-guidelines.md      # 프로젝트별 패턴
coding-standards.md    # 언어별 모범 사례
tdd-workflow/          # 여러 파일 스킬 + SKILL.md
security-review/       # 체크리스트 기반 스킬

슬래시 커맨드로 호출한다:

같은 작업을 세 번 이상 반복하면 Skill로 승격시켜야 한다.

Skill 승격 프로세스
1. 반복되는 프롬프트를 발견한다
2. 패턴을 추출한다
3. ~/.claude/skills/에 Skill로 정의한다
4. 슬래시 커맨드로 호출한다

초반에 재사용 가능한 워크플로우를 구축하는 데 시간을 쏟았다. 만드는 과정은 지루했지만, 복리 효과는 엄청났다. — Affaan Mustafa

Hooks: 이벤트 기반 자동화

Hooks는 특정 이벤트에서 실행되는 트리거 기반 자동화다. 도구 호출과 생명주기 이벤트에서 동작한다.

Hook 타입목적
PreToolUse도구 실행 전 — 유효성 검증, 알림
PostToolUse도구 실행 후 — 포맷팅, 피드백 루프
UserPromptSubmit메시지 전송 시
StopClaude 응답 완료 시
PreCompact컨텍스트 압축 전 — 중요 상태 저장
Notification권한 요청 시

실전에서 유용한 Hook 예시:

settings.json — Hooks
{
  "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"
          }
        ]
      }
    ]
  }
}

JSON을 직접 작성하기 번거롭다면 /hookify 플러그인으로 대화형으로 Hook을 생성할 수 있다.

Subagents: 작업 위임

Subagents는 제한된 범위로 작업을 위임받는 프로세스다. 백그라운드/포그라운드에서 실행되며, 특정 도구 권한으로 샌드박싱된다.

~/.claude/agents/
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의 순차적 단계는 다음과 같다.

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

[핵심 규칙]

Rules: Instinct(본능)

Rules는 모델이 항상 따라야 할 무의식적 규칙이다. everything-claude-code에서는 이것을 "instinct"라고 부른다.

~/.claude/rules/
security.md      # 하드코딩된 시크릿 금지, 입력 검증
coding-style.md  # 불변성 우선, console.log 커밋 금지
testing.md       # TDD 워크플로우, 80% 커버리지
git-workflow.md  # 커밋 형식, PR 프로세스
agents.md        # 서브에이전트 위임 시기
performance.md   # 모델 선택, 컨텍스트 관리

[CLAUDE.md와의 차이]

MCPs: 외부 서비스 연동

MCPs(Model Context Protocol)는 외부 서비스를 Claude Code에 연결한다. 하지만 컨텍스트 윈도우를 가장 많이 잡아먹는 요소이기도 하다.

200K 컨텍스트 윈도우가 도구 활성화 시 70K로 줄어들 수 있다. — everything-claude-code

MCP 관리 원칙
설정(설치): 20~30개 — 필요한 것은 모두 설치
활성화:     10개 이하 — 현재 작업에 필요한 것만
활성 도구:  80개 미만 — 이 이상은 컨텍스트 낭비

이미 강력한 CLI가 있는 도구(GitHub, Supabase, Vercel 등)는 MCP 대신 Skills로 래핑하는 것이 토큰 절감에 도움된다.

MCP 설정 예시 — .mcp.json
{
  "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로 올려야 하는 시점:

도구 최적화 — mgrep

everything-claude-code에서는 기본 검색 대신 mgrep을 권장한다.

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

Worktree로 병렬 인스턴스 실행
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-59536CVSS 8.7신뢰된 대화 전에 프로젝트 코드 실행
CVE-2026-21852높음ANTHROPIC_BASE_URL 리다이렉션으로 API 키 유출

프롬프트 인젝션은 더 이상 재미있는 실험이 아니다. 에이전트 시스템에서는 셸 실행, 비밀 노출, 워크플로우 악용으로 직결된다.

최소한의 보안 설정

permissions deny 설정
{
  "permissions": {
    "deny": [
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Read(**/.env*)",
      "Bash(curl * | bash)",
      "Bash(ssh *)"
    ]
  }
}

샌드박싱

위험한 작업은 격리된 환경에서 실행한다.

docker-compose.yml — 에이전트 샌드박스
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의 핵심]

AI Agent를 "쓰는 것"과 "잘 쓰는 것"의 차이는 도구의 성능이 아니라 운영 체계의 유무다.