🔥 Claude Code 토큰을 아끼는 세팅: context-mode, Bun, CLAUDE.md/AGENTS.md

Claude Code를 쓰다 보면 처음에는 정말 편합니다. 파일을 열어 달라고 하면 열어 주고, 로그를 붙여 넣으면 원인을 찾아 주고, 프로젝트 구조도 금방 파악합니다.

그런데 프로젝트가 조금만 커져도 금방 이런 문제가 생깁니다.

• 긴 로그를 한 번 붙였을 뿐인데 컨텍스트가 크게 줄어듭니다.
• 큰 파일 몇 개를 읽히면 대화가 무거워집니다.
• 같은 프로젝트 규칙을 매번 다시 설명하게 됩니다.
• 패키지 매니저, 빌드 명령어, 테스트 방식이 계속 흔들립니다.

이 글은 그런 상황을 줄이기 위한 세팅 가이드입니다.

핵심은 세 가지입니다.

1. context-mode로 큰 파일과 로그를 그대로 넘기지 않기
2. Bun으로 빠른 패키지 매니저와 실행 환경을 맞추기
3. CLAUDE.md 또는 AGENTS.md로 프로젝트 규칙을 고정하기

제대로 맞춰 두면 Claude가 매번 불필요하게 많은 내용을 읽지 않아도 됩니다. 작업 방식에 따라 토큰 사용량을 크게 줄일 수 있고, 큰 로그나 긴 파일을 다룰 때는 체감 차이가 꽤 큽니다.

다만 먼저 현실적인 부분부터 짚고 가겠습니다. 이 세팅이 모든 상황에서 무조건 토큰을 90% 줄여 주는 마법은 아닙니다. 효과는 프로젝트 크기, 사용 습관, Claude에게 어떤 방식으로 요청하는지에 따라 달라집니다. 그래도 “큰 파일을 통째로 읽히는 습관”을 줄이는 것만으로도 충분히 의미 있는 개선을 만들 수 있습니다.

---

왜 Claude Code에서 토큰이 빨리 줄어들까

Claude 같은 AI 도구는 대화 내용과 파일 내용, 로그, 코드 일부를 컨텍스트 안에 넣고 작업합니다. 쉽게 말하면 AI가 참고할 수 있는 작업 책상이 있는데, 그 책상 위에 너무 많은 자료를 올려 두면 공간이 빠르게 줄어드는 구조입니다.

예를 들어 이런 요청을 자주 한다고 해 보겠습니다.

이 로그 전체 보고 원인 찾아줘.

또는 이렇게 요청할 수도 있습니다.

이 프로젝트 전체를 보고 구조 파악해줘.

작은 프로젝트라면 괜찮습니다. 하지만 실제 앱 프로젝트, 서버 프로젝트, iOS 프로젝트, 프론트엔드 프로젝트처럼 파일이 많아지면 이야기가 달라집니다.

AI가 꼭 읽지 않아도 되는 파일까지 많이 읽게 되고, 로그도 원인과 관련 없는 부분까지 컨텍스트에 들어갑니다. 그러면 정작 중요한 코드 수정이나 분석에 쓸 공간이 줄어듭니다.

그래서 중요한 원칙은 이것입니다.

AI에게 원본 자료를 전부 넘기기보다, 필요한 결과만 계산해서 넘긴다.

이 원칙을 도와주는 도구가 바로 context-mode입니다.

---

context-mode는 무엇을 해 주나

context-mode는 Claude에게 큰 파일이나 긴 로그를 그대로 먹이는 대신, 로컬에서 명령을 실행하고 필요한 결과만 요약해서 넘기는 방식의 도구입니다.

예를 들어 Claude가 프로젝트 안에서 특정 문자열을 찾고 싶다고 해 보겠습니다.

기존 방식은 이런 식이 되기 쉽습니다.

프로젝트 파일들을 열어 보고 FIXME가 있는 곳을 찾아줘.

그러면 Claude가 여러 파일을 직접 읽으면서 컨텍스트를 많이 사용합니다.

반면 context-mode를 쓰면 이런 식으로 바뀝니다.

ctx_search로 FIXME가 있는 파일과 줄만 찾아줘.

또는 내부적으로 rg, find, sed, git diff 같은 명령 결과만 가져오게 할 수 있습니다. 그러면 Claude는 파일 전체가 아니라 “필요한 줄”, “검색 결과”, “요약된 통계”만 보게 됩니다.

결과적으로 컨텍스트 사용량이 줄어들고, 작업도 더 선명해집니다.

---

context-mode에서 자주 쓰는 도구들

설치 후 Claude에서 사용할 수 있는 대표 도구는 다음과 같습니다.

도구	용도
ctx_execute	셸 명령 하나를 실행하고 결과를 요약해서 가져옵니다.
ctx_batch_execute	여러 명령을 한 번에 실행합니다. 프로젝트 점검에 유용합니다.
ctx_fetch_and_index	URL이나 문서를 가져와 인덱싱합니다. 긴 문서를 다룰 때 좋습니다.
ctx_search	인덱싱된 자료나 프로젝트에서 필요한 내용만 검색합니다.
ctx_stats	context-mode 사용량과 상태를 확인합니다.

초보자 입장에서는 처음부터 모든 도구를 외울 필요가 없습니다. 우선은 아래 세 가지만 기억해도 충분합니다.

ctx_execute: 명령 실행
ctx_search: 필요한 내용 검색
ctx_stats: 상태 확인

---

준비물

이 글은 macOS 또는 Linux 계열 터미널을 기준으로 설명합니다. macOS에서 Claude Code를 쓰는 경우가 많기 때문에 zsh 기준 명령어도 함께 적었습니다.

준비물은 다음과 같습니다.

• Claude Code가 설치되어 있어야 합니다.
• 터미널을 사용할 수 있어야 합니다.
• Node.js 또는 npm이 설치되어 있으면 좋습니다.
• Bun을 설치할 예정입니다.
• 프로젝트 루트에 CLAUDE.md 또는 AGENTS.md를 둘 수 있어야 합니다.

설치가 처음이라면 명령어를 한 줄씩 실행하고, 중간에 에러가 나는지 확인하면서 진행하는 것을 추천합니다.

---

1단계: Bun 설치하기

Bun은 JavaScript 런타임이자 패키지 매니저입니다. Node.js 생태계와 비슷하게 쓸 수 있지만, 설치와 실행 속도가 빠른 편입니다.

터미널에서 아래 명령어를 실행합니다.

curl -fsSL https://bun.sh/install | bash

설치가 끝났다면 zsh 설정 파일에 Bun 경로를 추가합니다.

echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

설치가 잘 되었는지 확인합니다.

bun --version

버전 숫자가 나오면 정상입니다.

만약 command not found: bun이 나온다면 터미널을 완전히 껐다가 다시 열어 보세요. 그래도 안 된다면 아래 명령어로 경로가 들어갔는지 확인합니다.

echo $PATH

$HOME/.bun/bin 또는 실제 홈 경로의 .bun/bin이 보이면 됩니다.

---

2단계: context-mode 설치하기

이제 context-mode를 설치합니다.

npm install -g context-mode

설치 후 도움말이나 상태 명령을 실행해 봅니다.

ctx stats

환경에 따라 명령어가 ctx_stats처럼 노출될 수도 있습니다. 설치한 패키지 버전에 따라 이름이 다를 수 있으니, 명령이 먹지 않으면 아래처럼 도움말을 먼저 확인해 보세요.

context-mode --help

또는 설치 위치를 확인합니다.

which context-mode

여기까지 성공했다면 로컬에서 context-mode를 쓸 준비는 된 것입니다.

---

3단계: Claude MCP 설정에 context-mode 등록하기

Claude가 context-mode를 사용하려면 MCP 서버로 등록해야 합니다.

Claude Code 환경마다 설정 파일 위치가 조금 다를 수 있습니다. 이미 MCP 설정을 쓰고 있다면 기존 설정에 context-mode 항목만 추가하면 됩니다.

예시는 다음과 같습니다.

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode",
      "args": ["mcp"]
    }
  }
}

이미 다른 MCP 서버가 있다면 mcpServers 안에 함께 넣어 주세요.

예를 들어 기존 설정이 이런 형태라면,

{
  "mcpServers": {
    "github": {
      "command": "github-mcp-server"
    }
  }
}

아래처럼 하나를 더 추가합니다.

{
  "mcpServers": {
    "github": {
      "command": "github-mcp-server"
    },
    "context-mode": {
      "command": "context-mode",
      "args": ["mcp"]
    }
  }
}

설정을 바꾼 뒤에는 Claude Code를 재시작하는 것이 좋습니다. MCP 설정은 실행 중 자동 반영되지 않는 경우가 많습니다.

---

4단계: Hooks 설정하기

Hooks는 Claude가 도구를 사용하기 전후에 특정 작업을 걸어 둘 수 있는 설정입니다. 쉽게 말하면 “Claude가 작업할 때 지켜야 할 자동 규칙”을 붙이는 느낌입니다.

예시는 다음과 같습니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "context-mode hook pre"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "context-mode hook post"
          }
        ]
      }
    ]
  }
}

이 설정은 프로젝트나 Claude Code 설정 방식에 따라 넣는 위치가 달라질 수 있습니다. 중요한 것은 PreToolUse, PostToolUse가 실제로 Claude의 도구 호출 전후에 실행되도록 연결하는 것입니다.

처음부터 Hooks까지 복잡하게 느껴진다면, 우선 MCP 등록만 해 두고 사용해도 됩니다. 이후에 컨텍스트 관리가 더 필요해졌을 때 Hooks를 추가해도 늦지 않습니다.

---

5단계: CLAUDE.md 또는 AGENTS.md 만들기

Claude에게 매번 같은 설명을 반복하지 않으려면 프로젝트 루트에 규칙 파일을 만들어 두는 것이 좋습니다.

Claude 전용으로는 CLAUDE.md를 많이 사용합니다. 여러 AI 코딩 도구와 함께 쓸 예정이라면 AGENTS.md도 좋습니다.

예를 들어 프로젝트 루트에 아래 파일을 만듭니다.

touch CLAUDE.md

또는

touch AGENTS.md

그리고 다음처럼 프로젝트 규칙을 적습니다.

# Project Rules

## Package Manager
- Use Bun when possible.
- Use `bun install` instead of `npm install`.
- Use `bun run` for scripts.

## Context Usage
- Prefer context-mode tools for large files, logs, and broad searches.
- Do not paste full logs unless necessary.
- Use search commands before opening many files.

## Code Style
- Keep changes small and focused.
- Do not rewrite unrelated files.
- Run tests or build checks after meaningful changes when possible.

## Project Notes
- Write important implementation notes here.
- Add build commands and test commands here.

너무 길게 쓰는 것보다, 프로젝트에서 자주 틀리는 부분을 짧고 명확하게 적는 것이 좋습니다.

예를 들어 iOS 프로젝트라면 이런 내용을 추가할 수 있습니다.

## iOS Build
- Use Xcode project settings as the source of truth.
- Do not modify signing settings unless asked.
- Prefer small UIKit/SwiftUI changes that match the existing design system.

프론트엔드 프로젝트라면 이런 식도 좋습니다.

## Frontend
- Preserve the existing design language.
- Avoid adding new dependencies unless necessary.
- Check mobile layout when touching UI.

이 파일의 목적은 Claude를 묶어 두는 것이 아니라, 프로젝트의 기본 습관을 알려 주는 것입니다.

---

6단계: Bun 명령어로 바꾸기

Bun을 설치했다면 자주 쓰는 npm 명령어를 Bun 기준으로 바꿔 두면 좋습니다.

기존 명령어	Bun 명령어
npm install	bun install
npm install 패키지	bun add 패키지
npm uninstall 패키지	bun remove 패키지
npm run dev	bun run dev
npm run build	bun run build
npx some-tool	bunx some-tool

다만 모든 프로젝트에서 무조건 Bun으로 바꾸는 것은 조심해야 합니다.

이미 팀에서 package-lock.json을 기준으로 npm을 쓰고 있다면 그대로 유지하는 편이 안전할 수 있습니다. 반대로 개인 프로젝트이거나 Bun을 쓰기로 결정한 프로젝트라면 CLAUDE.md나 AGENTS.md에 명확히 적어 두는 것이 좋습니다.

## Package Manager
- This project uses Bun.
- Do not create `package-lock.json`.
- Use `bun.lock` as the lockfile.

이렇게 적어 두면 Claude가 실수로 npm 명령을 쓰는 일을 줄일 수 있습니다.

---

7단계: 제대로 적용됐는지 확인하기

세팅 후에는 바로 큰 작업을 맡기기보다 작은 요청으로 테스트해 보는 것이 좋습니다.

예를 들어 Claude에게 이렇게 요청해 볼 수 있습니다.

프로젝트에서 FIXME 주석이 있는 파일과 줄 번호만 찾아줘. 파일 전체를 열지 말고 검색 결과만 요약해줘.

또는 이렇게 요청해 볼 수 있습니다.

최근 git diff를 요약해줘. 변경된 파일 전체를 읽기보다 핵심 변경점만 정리해줘.

Claude가 ctx_search, ctx_execute, rg, git diff --stat 같은 방식으로 필요한 결과만 가져온다면 방향이 잘 잡힌 것입니다.

상태 확인 명령도 실행해 봅니다.

ctx stats

여기서 중요한 것은 숫자 하나에 집착하지 않는 것입니다. 컨텍스트 절감 효과는 작업 방식에 따라 달라집니다. 대신 다음과 같은 변화가 있는지 보세요.

• Claude가 큰 파일을 무작정 열지 않는다.
• 검색 결과 중심으로 판단한다.
• 긴 로그를 통째로 읽기보다 필요한 줄만 본다.
• 같은 프로젝트 규칙을 반복해서 설명하지 않아도 된다.

이 네 가지가 잡히면 세팅 효과는 충분히 나오고 있는 것입니다.

---

실제로 써 보면 좋은 요청 방식

세팅만큼 중요한 것이 요청 방식입니다. 같은 일을 시켜도 어떻게 말하느냐에 따라 컨텍스트 사용량이 크게 달라집니다.

좋은 예시는 다음과 같습니다.

전체 파일을 다 읽지 말고, 먼저 관련 파일을 검색해서 후보를 좁힌 다음 수정해줘.

이 로그에서 에러 원인으로 보이는 부분만 추려서 설명해줘.

변경 전에 관련 함수가 어디서 호출되는지 검색으로 확인해줘.

큰 파일은 필요한 함수 주변만 읽어줘.

반대로 아래 요청은 컨텍스트를 많이 쓰기 쉽습니다.

프로젝트 전체를 다 보고 문제점 알려줘.

이 로그 전체 분석해줘.

모든 파일 열어서 구조 파악해줘.

물론 정말 전체 분석이 필요한 순간도 있습니다. 하지만 매번 그렇게 시작하면 컨텍스트가 빠르게 줄어듭니다. 먼저 검색으로 범위를 좁히고, 필요한 파일만 읽히는 습관이 좋습니다.

---

CLAUDE.md/AGENTS.md에 넣으면 좋은 내용

규칙 파일에는 모든 것을 적을 필요가 없습니다. Claude가 작업할 때 자주 헷갈릴 만한 것만 넣으면 됩니다.

추천 항목은 다음과 같습니다.

• 프로젝트 실행 명령어
• 테스트 명령어
• 빌드 명령어
• 패키지 매니저 기준
• 코드 스타일
• 수정하면 안 되는 파일
• 자주 발생하는 빌드 이슈
• 배포 전 확인 항목
• UI 작업 시 지켜야 할 디자인 방향

예시는 다음과 같습니다.

# Project Guide

## Commands
- Install: `bun install`
- Dev: `bun run dev`
- Build: `bun run build`
- Test: `bun test`

## Rules
- Keep edits focused.
- Do not change generated files manually.
- Do not add dependencies without explaining why.
- Prefer searching before opening large files.

## Before Finishing
- Run the smallest relevant verification command.
- Summarize changed files and why they changed.

초보자라면 처음에는 이 정도만 적어도 충분합니다. 프로젝트를 진행하면서 필요한 규칙을 조금씩 추가하면 됩니다.

---

흔한 실수와 해결 방법

1. MCP 설정 후 Claude Code를 재시작하지 않음

MCP 설정을 바꿨는데 도구가 보이지 않는다면 Claude Code를 재시작해 보세요. 설정 파일은 저장했지만 실행 중인 세션에는 반영되지 않았을 수 있습니다.

2. CLAUDE.md를 너무 길게 작성함

규칙 파일이 너무 길면 오히려 매번 읽어야 할 정보가 많아집니다. 프로젝트에 꼭 필요한 규칙만 남기는 것이 좋습니다.

3. npm과 Bun을 섞어서 사용함

한 프로젝트에서 package-lock.json, bun.lock, yarn.lock이 뒤섞이면 의존성 관리가 꼬일 수 있습니다. 팀 프로젝트라면 기존 방식을 따르고, 개인 프로젝트라면 하나로 정해 두세요.

4. 로그를 그대로 붙여 넣는 습관을 유지함

context-mode를 설치해도 사용 습관이 그대로라면 효과가 줄어듭니다. 긴 로그는 파일로 두고, Claude에게 필요한 부분만 검색하게 하는 편이 좋습니다.

5. “프로젝트 전체를 봐줘”로 시작함

처음부터 전체 분석을 시키기보다, 증상과 관련된 키워드, 파일명, 에러 메시지를 기준으로 좁혀 가는 편이 좋습니다.

---

개인적으로 추천하는 기본 세팅

처음 시작한다면 너무 복잡하게 가지 말고 아래 순서로 적용하는 것을 추천합니다.

1. Bun 설치
2. context-mode 설치
3. Claude MCP에 context-mode 등록
4. 프로젝트 루트에 CLAUDE.md 작성
5. 큰 파일을 열기 전에 검색부터 하도록 요청 습관 바꾸기
6. 필요해지면 Hooks 추가

처음부터 Hooks와 고급 설정까지 완벽하게 맞추려고 하면 오히려 중간에 지칠 수 있습니다. 먼저 기본 흐름을 만들고, 실제 프로젝트에서 불편한 지점을 하나씩 보완하는 방식이 가장 오래 갑니다.

---

마무리

Claude Code를 잘 쓰는 핵심은 “AI에게 많이 보여 주는 것”이 아니라 “AI가 필요한 것을 정확히 보게 하는 것”입니다.

context-mode는 큰 파일과 긴 로그를 다룰 때 컨텍스트 낭비를 줄여 줍니다. Bun은 빠른 실행 환경과 패키지 관리 흐름을 만들어 줍니다. CLAUDE.md와 AGENTS.md는 프로젝트마다 반복되는 규칙 설명을 줄여 줍니다.

이 세 가지를 함께 쓰면 Claude Code가 더 가볍고 일관되게 움직입니다. 특히 프로젝트가 커질수록 차이가 커집니다.

처음에는 작은 프로젝트 하나에만 적용해 보세요. 그리고 Claude에게 이렇게 요청해 보면 됩니다.

큰 파일을 바로 열지 말고, 먼저 검색으로 관련 위치를 좁힌 다음 필요한 부분만 읽어서 작업해줘.

이 한 문장만 습관이 되어도 Claude Code를 쓰는 방식이 꽤 달라집니다.