토큰을 아끼고 oh-my-claudecode로
200% 활용하는 실무 매뉴얼

시작하기 전에 — 이 매뉴얼의 한 줄 요약

Claude(Claude Code 포함)는 메시지 개수가 아니라 토큰(token) 누적량으로 사용량을 측정합니다. 따라서 토큰을 아끼는 모든 방법은 결국 세 가지 원칙으로 수렴합니다.

토큰의 기본 이해

절약하려면 먼저 "무엇이 토큰을 먹는지" 알아야 합니다.

▸토큰이란?

AI는 텍스트를 그대로 처리하지 않고 토크나이저(tokenizer)로 단어·기호·공백을 잘게 쪼갠 최소 단위, 즉 토큰으로 변환합니다. 대략적인 환산은 이렇습니다.

▸입력 토큰 vs 출력 토큰

한 번의 요청에는 눈에 보이는 내 메시지보다 훨씬 많은 정보가 함께 전송됩니다. 아래가 전부 입력 토큰으로 계산됩니다.

▸컨텍스트 윈도우 — 작업 메모리

컨텍스트 윈도우는 모델이 한 번에 "볼 수 있는" 모든 정보의 한계치입니다. 시스템 프롬프트, 대화 내역, 파일 읽기 결과, 도구 출력이 모두 이 안에 들어갑니다.

• 표준 모델: 200K 토큰 (책 한 권 분량)
• Opus 4.6/4.7 등 확장 컨텍스트: 최대 1M 토큰
• 대화가 누적될수록 매 턴 전체 이력을 다시 읽으므로 비용이 기하급수적으로 증가합니다.

토큰 사용량 확인하기

"디스크 공간처럼" 컨텍스트가 채워지므로, 정기적으로 확인하는 습관이 절약의 출발점입니다.

토큰 절약 10대 습관

커뮤니티(특히 X @0x_kaize 스레드, 지피터스 정리본)에서 화제가 된 즉시 적용 가능한 습관들입니다. 채팅 UI와 Claude Code 양쪽에 통용됩니다.

CLAUDE.md 작성법 — 가장 효과 큰 다이어트

CLAUDE.md는 매 세션 시작 시 컨텍스트에 자동 로드됩니다. 길수록 모든 요청의 초기 비용이 불필요하게 커집니다. 관건은 "성장"이 아니라 "거버넌스"입니다.

▸원칙 1 — 짧게, 구조화해서

• "이 프로젝트는…" 같은 서술형 문장 제거
• 헤딩·리스트·테이블로 구조화
• 규칙은 최소 단위로 축약, 코드 예시는 과하게 넣지 않기
• Anthropic 공식 권장: 필수 항목만, 약 500줄(또는 그 이하) 유지

▸⭐ 카파시(Karpathy) 4원칙 — 복붙용 CLAUDE.md GitHub 220,000+ ★

안드레이 카파시가 "AI 코딩 에이전트가 반복적으로 저지르는 실수"로 지적한 내용을, 개발자 Forrest Chang이 단 4개의 짧은 행동 원칙으로 정리한 CLAUDE.md입니다. 의존성·빌드 단계 없이 단 한 파일로 GitHub 역사상 가장 빠르게 성장한 리포지토리 중 하나가 되었습니다(MIT 라이선스).

핵심은 이 4개의 짧은 문구입니다. 아래 블록을 그대로 복사해 프로젝트 루트의 CLAUDE.md에 붙여넣으면 됩니다.

CLAUDE.md — copy & paste (KEEP IT IN ENGLISH)# Behavioral Guidelines (Karpathy 4)

## 1. Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
- State assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.

## 2. Simplicity First
Minimum code that solves the problem. Nothing speculative.
- No features beyond what was asked.
- No abstractions for single-use code.
- If you write 200 lines and it could be 50, rewrite it.

## 3. Surgical Changes
Touch only what you must. Clean up only your own mess.
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken. Match existing style.
- Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution
Define success criteria. Loop until verified.
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- For multi-step tasks, state a brief plan first.

⚠️ 위 블록을 한글로 번역하지 마세요. 영어 그대로 두어야 토큰이 3~5배 절약됩니다. 위 4문구는 영어 원문이며, Claude는 영어 지시를 완벽히 이해하고 한국어로 답합니다.

30초 설치 — 방법 A · 이 프로젝트에만 (curl)

터미널 — 프로젝트 루트에서echo "" >> CLAUDE.md && \
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

방법 B · 모든 프로젝트에 (플러그인/스킬, 호출 시에만 로드 → 토큰 절약)

Claude Code 세션 안에서 — 한 줄씩/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

▸원칙 2 — 분산 메모리 구조 (2-Tier)

CLAUDE.md가 길어지면 보조 문서로 쪼개고, 필요할 때만 불러오게 합니다. 기본 컨텍스트는 가볍게 유지됩니다.

디렉토리CLAUDE.md            # 핵심 규칙·스택·구조만 (가볍게)
docs/
 ├─ api-guide.md     # 필요할 때만 참조
 ├─ db-guide.md
 └─ deploy-guide.md

• 토큰 절약: 기본 컨텍스트가 가벼워짐
• 유지보수: 기능·역할별로 나뉘어 부분 수정 용이
• 가독성: 필요한 정보를 빠르게 탐색

▸원칙 3 — 특화 지침은 CLAUDE.md → Skills로 이동

PR 검토, DB 마이그레이션처럼 특정 워크플로에서만 필요한 긴 지침을 CLAUDE.md에 두면, 무관한 작업을 할 때도 그 토큰이 항상 존재합니다. Skills는 호출될 때만 로드되므로 기본 컨텍스트를 작게 유지합니다.

SKILL.md (예시)---
name: pr-review
description: 우리 팀 PR 리뷰 규칙 적용
---
# 호출 시에만 컨텍스트로 로드되는 상세 지침
1. 변경 범위 요약
2. 보안 체크리스트 적용
3. 테스트 커버리지 확인

MCP · CLI · 외부 도구 — 도구 정의의 숨은 비용

각 MCP 서버는 유휴 상태에서도 도구 정의를 컨텍스트에 올립니다. GitHub·Web Search·Database·Playwright를 모두 켜면 시스템 영역에 1만 토큰 이상이 추가될 수 있습니다.

▸가능하면 MCP보다 CLI를 선호

이게 공식 문서의 첫 번째 권장사항입니다. CLI 도구는 지속적인 도구 정의를 컨텍스트에 추가하지 않으므로 MCP보다 효율적입니다. Claude가 오버헤드 없이 명령을 직접 실행합니다.

▸🧰 토큰 절약에 쓰는 CLI 도구 모음

아래 CLI들은 ① MCP 스키마 오버헤드가 없고 ② "파일 통째 읽기" 대신 정밀 탐색/필터링을 가능하게 해 컨텍스트를 크게 아낍니다. Claude가 직접 실행하므로, 미리 설치만 해두면 됩니다. (설치 명령은 macOS Homebrew 기준이며 다른 OS는 각 공식 안내 참고)

▸MCP 관리 3원칙

• 필요한 것만 활성화: 프런트엔드 작업엔 Playwright만, 백엔드엔 Database MCP만.
• 사용 안 하는 서버 비활성화: /mcp로 구성 확인 후 끄기. /context로 점유량 확인.
• Tool Search 자동화: MCP 도구 설명이 컨텍스트의 10%를 넘으면 자동으로 도구를 연기(defer)하고 필요 시에만 로드합니다. ENABLE_TOOL_SEARCH=auto:5처럼 임계값을 더 낮출 수도 있습니다.

▸코드 인텔리전스 플러그인 (LSP)

타입 언어를 다룬다면 코드 인텔리전스 플러그인 설치를 강력 권장합니다. 텍스트 grep 대신 정확한 기호 탐색을 제공합니다.

• "정의로 이동" 한 번이 grep + 여러 후보 파일 읽기를 대체 → 불필요한 파일 읽기 감소
• 편집 후 자동 타입 오류 보고 → 컴파일러를 매번 돌리지 않고도 실수 포착

▸Hooks로 전처리 오프로드

Hook은 Claude가 데이터를 보기 전에 가공합니다. 1만 줄 로그를 통째로 읽는 대신, hook이 ERROR만 grep해 수백 토큰으로 줄일 수 있습니다.

settings.json — 테스트 실패만 통과시키는 PreToolUse hook{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type":"command",
        "command":"~/.claude/hooks/filter-test-output.sh" }]
    }]
  }
}

스크립트는 명령이 테스트 러너(npm test, pytest, go test)일 때 grep -E '(FAIL|ERROR)'로 실패 라인만 반환하도록 명령을 수정합니다.

▸Skills로 도메인 지식 주입

"codebase-overview" 같은 skill에 아키텍처·주요 디렉토리·네이밍 규칙을 적어두면, Claude가 구조 파악을 위해 여러 파일을 읽는 대신 즉시 컨텍스트를 획득합니다.

▸Claude Code의 3-Layer 구조 (왜 위임이 싼가)

서브에이전트 · 에이전트 팀

대량 출력 작업(테스트 실행, 문서 가져오기, 로그 처리)은 본 대화를 오염시킵니다. 이를 서브에이전트에 위임하면 상세 출력은 서브에이전트 안에 남고 요약만 본 대화로 돌아옵니다.

▸서브에이전트의 토큰 이점

• 각 서브에이전트는 자체 컨텍스트 윈도우를 가짐 → 대형 코드베이스 탐색 시 사실상 추가 윈도우 확보
• 탐색·로그 분석 같은 작업을 더 저렴한 모델 티어로 라우팅 가능 (예: model: haiku)
• 여러 서브에이전트를 병렬로 실행 가능 ("4개 task로 디렉토리를 나눠 탐색")

서브에이전트 구성 — 단순 작업은 haiku로---
name: explorer
model: haiku   # 탐색은 가벼운 모델로 비용 절감
---

▸에이전트 팀 (실험 기능) — 강력하지만 비싸다

에이전트 팀은 각자 컨텍스트 윈도우를 가진 여러 Claude 인스턴스를 띄웁니다. plan mode에서 표준 세션의 약 7배 토큰을 쓸 수 있습니다.

settings.json — 에이전트 팀 활성화(기본 비활성){ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

모델 선택 & 확장 사고 조정

"매일 내리는 가장 중요한 결정"은 모델 선택입니다.

• 세션 중 전환: /model · 기본값 설정: /config
• 서브에이전트 단순 작업: 구성에서 model: haiku
• Sonnet이 대부분의 코딩을 잘 처리합니다. Opus는 정말 깊은 추론에만 예약하세요.

▸확장 사고(Extended Thinking) 조정

확장 사고는 기본 약 32,000 토큰 예산으로 활성화되어 있고, 사고 토큰은 출력 토큰으로 청구됩니다. 깊은 추론이 필요 없는 작업이라면:

• /effort 또는 /model에서 노력 수준 낮추기
• /config에서 사고 비활성화
• 예산 직접 축소: MAX_THINKING_TOKENS=8000

/goal 명령어 — 자율 실행 루프

2026년 5월 등장한 가장 화제의 명령어입니다. "한 턴 일하고 멈춰서 사용자에게 넘기는" 기존 방식을 끝내고, 완료 조건(completion condition)을 정의하면 그 조건이 충족될 때까지 Claude가 스스로 계획·작성·테스트·검증·반복을 이어갑니다.

▸핵심 동작

• 완료 조건을 자연어로 정의하면, 경량 완료 검증 모델(evaluator)이 매 반복마다 "목표가 객관적으로 충족됐는지" 평가합니다.
• 충족될 때까지 여러 턴(때로는 수 시간~수 일) 자율 진행하며 경과 시간·턴 수·토큰을 추적합니다.
• 목표가 달성되면 자동으로 goal이 해제됩니다.
• 대화형 모드, -p 플래그(헤드리스), Remote Control에서 모두 동작합니다.

▸명령어 레퍼런스 (v2.1.139+)

▸좋은 목표 vs 나쁜 목표 (4장 카파시 4원칙과 직결)

"강한 완료 조건"이 핵심입니다. 모호하면 검증이 불가능해 무한 루프나 "그럴듯한 엉망"으로 끝납니다. 4장의 Goal-Driven Execution 원칙이 그대로 적용됩니다.

실전 예시/goal pytest 전체 통과 + ruff 린트 0 에러 + 커버리지 80% 이상
/goal /auth 모듈의 보안 취약점을 수정하고 회귀 테스트를 추가해 모두 통과시킨다
/goal show          # 진행 상황·토큰 점검
/goal clear         # 중단

▸⚠️ 토큰 관점에서의 주의

▸OMC에도 /goal이 있나? — 개념적 등가물

OMC 공식 문서에 동일한 이름의 /goal 명령은 (현재 확인 범위에선) 없습니다. 다만 "완료될 때까지 멈추지 않는 자율 실행"이라는 개념은 OMC가 이미 다른 이름으로 제공합니다.

oh-my-claudecode(OMC)란 무엇인가

허예찬(Yeachan Heo)이 만든 OMC는 Claude Code 위에 얹는 멀티 에이전트 오케스트레이션 레이어입니다. 한 줄 요약은 — "Don't learn Claude Code. Just use OMC."

▸OMC의 작동 철학 — 스킬 합성(Skill Synthesis)

Claude Code는 마스터 에이전트를 교체하지 않고 고정된 마스터에 스킬을 주입(inject)해 행동을 바꿉니다. OMC는 이를 레이어로 정리합니다.

예: "UI 작업 + 여러 파일 수정 + 커밋"이면 실행 레이어 위에 frontend-ui-ux, git-master를 얹습니다. 모드를 '갈아타는' 게 아니라 행동을 '겹겹이 쌓는' 방식이라 맥락이 끊기지 않습니다.

▸패키지 구성 (버전에 따라 수치 변동)

설치 & 첫 세션 (약 30초)

Step 1 — 설치 (슬래시 명령은 한 줄씩 입력)

Claude Code 세션 안에서# 1) 마켓플레이스 추가
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode

# 2) 플러그인 설치
/plugin install oh-my-claudecode

npm CLI 경로를 선호하면(패키지명 주의 — 브랜드는 oh-my-claudecode지만 npm 패키지는 oh-my-claude-sisyphus):

터미널npm i -g oh-my-claude-sisyphus@latest

Step 2 — 설정 (CLAUDE.md 갱신)

세션 안 / 터미널/setup            # 또는  /omc-setup
omc setup         # 터미널에서

Step 3 — 무언가 만들기

자연어로autopilot build me a todo CLI app
/autopilot "build a REST API for managing tasks"

▸CLI 명령 vs 세션 내 스킬

▸요구사항이 막연할 때 — Deep Interview

소크라테스식 질문으로 요구사항 명료화/deep-interview "I want to build a task management app"

▸업데이트 & 문제 해결

유지보수# npm 설치 시
npm i -g oh-my-claude-sisyphus@latest

# 마켓플레이스 설치 시
/plugin marketplace update omc
/setup

# 문제 발생 시 캐시 진단
/omc-doctor

매직 키워드 — 파이프라인을 한 마디로

대부분 자동이지만, 필요하면 키워드로 모드를 강제할 수 있습니다.

Autopilot · Team 모드

▸Autopilot — 5단계 자동 파이프라인

아이디어 하나를 주면 완성 코드까지 자동으로 만듭니다.

1. Expansion — analyst·architect가 아이디어를 기능 요구사항·기술 스펙으로 확장 (.omc/autopilot/spec.md)
2. Planning — planner가 구현 계획 작성, critic이 빈틈 검토 (.omc/plans/autopilot-impl.md)
3. Execution — executor가 ralph+ultrawork 모드로 완료까지 코딩(필요 시 병렬)
4. QA — 빌드·테스트 검증, 실패 시 자동 수정·재검증(최대 5회)
5. Validation — 기능·보안·품질 3관점 최종 리뷰. 모두 APPROVED여야 완료(최대 3라운드)

▸Team 모드 — 여러 에이전트 동시 실행

형식: N:agent-type "작업"/team 3:executor "fix all TypeScript errors"
omc team 2:codex "review auth module for security"   # tmux 워커
team ralph 3:executor "implement full auth system"   # team + ralph

▸계획 워크플로 선택

OMC 내장 MCP 도구 — 토큰을 아끼는 무기들

OMC는 에이전트가 내부적으로 쓰는 MCP 도구를 제공합니다. 이 중 상당수가 직접적인 토큰 절약 장치입니다.

OMC 비용 최적화 — Haiku-First 원칙

OMC는 3개 모델 티어를 쓰며, 적절한 티어 선택만으로 토큰 30~50%를 절감한다고 공식 문서가 안내합니다. 핵심은 "가장 가벼운 모델로 시작하고 필요할 때만 올린다".

▸고비용 작업 (꼭 필요할 때만)

• team — 여러 에이전트 동시 실행
• ralph — 완료까지 루프
• autopilot — 5단계 풀 파이프라인
• qa-tester — tmux 세션 기반 검증

▸검증 비용 최적화 (싼 것부터)

▸일반 팁

1. 작게 시작: 단일 에이전트로 시작해 필요 시 team/autopilot으로 확장
2. 계획 먼저: 복잡한 작업은 /plan·ralplan으로 먼저 계획
3. 노트 활용: /note로 핵심 정보를 컴팩션에서 살리기
4. 상태 모니터링: HUD·상태 파일로 진행 추적
5. 중단 타이밍: cancelomc로 불필요한 작업 빠르게 중지

안티패턴 — 토큰을 태우는 흔한 실수

실전 워크플로 — 토큰 의식 + OMC + /goal

큰 작업을 토큰 효율적으로 끝내는 표준 흐름입니다.

▸OMC 스킬 파이프라인 예시

요구사항을 deep-interview로 명료화 → omc-plan으로 계획 → autopilot으로 실행. 막연한 아이디어를 토큰 낭비 없이 완성으로 가져가는 안전한 경로입니다.

최종 체크리스트