토큰이 녹는다, Codex·Claude Code 토큰 최적화, 파일을 덜 읽게 만드는 설정

Codex·Claude Code 토큰 최적화, 파일을 덜 읽게 만드는 설정

Codex와 Claude Code의 토큰을 줄이는 가장 확실한 출발점은 짧은 프롬프트가 아니라 읽어야 할 범위를 먼저 좁히는 것입니다. 상시 지침은 짧게, 작업은 한 번에 하나씩, 파일 탐색은 후보를 찾은 뒤 필요한 구간만 읽게 만들면 불필요한 컨텍스트가 덜 쌓입니다. 두 도구의 명령과 설정은 다르지만 원리는 같습니다.

이 글의 목차

왜 짧은 질문만으로는 토큰이 잘 줄지 않을까요?Codex는 AGENTS.md와 시작 위치부터 줄이세요Claude Code는 컨텍스트를 보고 정리 시점을 고르세요두 도구의 최적화 포인트는 어디가 다를까요?프롬프트는 짧게보다 닫히게 쓰세요파일 탐색은 찾기와 읽기를 분리하세요바로 적용할 최소 설정 순서Codex와 Claude Code 중 무엇을 골라야 할까요?적용할 때 놓치기 쉬운 한계핵심 정리: 다섯 가지 질문과 답출처

30초 요약

• 저장소 전체 설명보다 목표·범위·완료 조건을 한 번에 전달합니다.
• Codex는 시작 디렉터리와 AGENTS.md 계층을 좁게 설계합니다.
• Claude Code는 /context로 점유 원인을 보고 작업 경계에서 /compact나 /clear를 선택합니다.
• 큰 파일은 검색으로 후보를 추린 뒤 필요한 구간만 읽게 합니다.
• 절감 효과는 추측하지 말고 같은 작업으로 사용량을 비교합니다.

이 글의 설정 예시는 공식 문서에 적힌 동작을 바탕으로 만든 문서 기반 예시입니다. 특정 저장소에서 토큰이나 비용이 몇 퍼센트 줄어드는지는 직접 측정하지 않았습니다.

왜 짧은 질문만으로는 토큰이 잘 줄지 않을까요?

코딩 에이전트의 입력에는 사용자가 방금 쓴 문장만 들어가지 않습니다. 프로젝트 지침, 이전 대화, 읽은 파일, 명령 결과, 도구 정의가 함께 컨텍스트를 차지합니다. 프롬프트에서 열 글자를 아껴도 테스트 로그 수천 줄을 통째로 읽히면 장바구니에서 껌 하나 빼고 쌀 한 포대를 더 담는 셈입니다.

비용을 줄일 때는 아래 순서가 실용적입니다.

1. 이번 작업과 무관한 디렉터리를 탐색 대상에서 뺍니다.
2. 매 세션에 실리는 지침에서 설명과 중복을 걷어냅니다.
3. 검색 결과와 명령 출력의 양을 제한합니다.
4. 작업 주제가 바뀌면 기존 대화를 계속 들고 갈지 판단합니다.
5. 마지막에 모델과 추론 강도를 조정합니다.

모델만 낮추는 방법부터 택하면 필요한 탐색을 반복하거나 수정이 늘 수 있습니다. 먼저 입력의 질과 범위를 다듬는 편이 안전합니다.

Codex는 AGENTS.md와 시작 위치부터 줄이세요

Codex는 실행을 시작할 때 전역 지침과 프로젝트 지침을 찾아 하나의 지침 묶음으로 합칩니다. 프로젝트 루트에서 현재 작업 디렉터리까지 내려오며 각 디렉터리에서 AGENTS.override.md, AGENTS.md, 설정한 대체 파일 순으로 확인하고, 디렉터리마다 최대 한 파일을 포함합니다.

공식 문서에 따르면 결합된 프로젝트 지침은 project_doc_max_bytes에 설정된 크기에 도달하면 더 추가되지 않으며 기본값은 32 KiB입니다. 이 값은 토큰 절약 목표치가 아니라 지침이 무한정 커지지 않게 하는 바이트 한도입니다. 무턱대고 낮추면 중요한 규칙이 잘릴 수 있으니, 먼저 중복을 없애야 합니다.

루트 AGENTS.md에는 모든 작업에 필요한 사실만 남깁니다.

# Repository rules
- 패키지 관리자는 pnpm을 사용한다.
- 변경 후 관련 테스트와 lint를 실행한다.
- 생성 파일은 직접 수정하지 않는다.

특정 서비스에서만 필요한 규칙은 그 디렉터리 가까이에 둡니다.

# services/billing/AGENTS.md
- 결제 금액은 정수 원 단위로 다룬다.
- 변경 후 pnpm test billing을 실행한다.

다만 Codex 문서 기준으로 이 계층은 세션 시작 시 현재 작업 디렉터리까지 합쳐집니다. 따라서 단순히 파일을 여러 개로 쪼개는 것만으로 토큰이 줄지는 않습니다. 실행 위치를 실제 작업 폴더로 좁히고, 그 경로에 필요한 규칙만 두는 설계가 함께 필요합니다.

codex --cd services/billing "환불 계산 오류를 수정해. 먼저 실패 테스트를 재현하고 관련 파일만 수정한 뒤 해당 테스트를 다시 실행해."

--cd는 에이전트가 시작할 작업 디렉터리를 지정합니다. 추가 경로가 꼭 필요할 때만 --add-dir를 붙이면 범위도 명확해집니다. 옵션 자체가 비용을 보장하지는 않지만 탐색 출발점과 권한 범위를 쓸데없이 넓히지 않을 수 있습니다.

Claude Code는 컨텍스트를 보고 정리 시점을 고르세요

Claude Code의 컨텍스트에는 대화 기록, 파일 내용, 명령 출력, CLAUDE.md, 자동 메모리, 불러온 스킬과 시스템 지침이 들어갑니다. /context를 실행하면 현재 공간을 무엇이 차지하는지 범주별로 볼 수 있습니다.

CLAUDE.md는 매 세션에 들어가므로 반복해서 필요한 규칙만 남겨야 합니다. Anthropic은 파일당 200줄 미만을 목표로 권하며, 긴 절차는 스킬로 옮기거나 .claude/rules/의 경로 조건을 사용하라고 안내합니다. 200줄은 강제 한도가 아니라 관리 기준입니다.

예를 들어 TypeScript API 파일에서만 필요한 규칙은 다음처럼 제한할 수 있습니다.

---
paths:
  - "src/api/**/*.{ts,tsx}"
---

# API rules
- 모든 입력은 경계에서 검증한다.
- 오류 응답은 공통 포맷을 사용한다.

이 규칙은 일치하는 파일을 다룰 때 로드됩니다. 반대로 paths가 없는 규칙과 프로젝트 루트의 CLAUDE.md는 매 세션의 기본 컨텍스트에 들어갑니다. @파일경로로 import한 문서도 시작 시 펼쳐져 들어가므로, 파일을 분리했다는 이유만으로 가벼워지지는 않습니다.

긴 세션에서는 목적에 따라 명령을 나눠 씁니다.

• /context: 무엇이 공간을 쓰는지 진단합니다.
• /compact focus on the billing refund fix: 현재 작업의 핵심을 지정해 대화를 요약합니다.
• /clear: 서로 관련 없는 새 작업을 시작할 때 이전 대화를 비웁니다.
• /usage: 세션의 토큰 통계와 사용 상태를 확인합니다.

Claude Code는 컨텍스트가 차면 오래된 도구 출력을 먼저 정리하고, 필요하면 대화를 자동 요약합니다. 다만 초반의 세부 지침은 요약 과정에서 흐려질 수 있습니다.

반드시 유지할 규칙이라면 대화 초반에 한 번 말하고 끝내지 마세요. CLAUDE.md에 간결하게 남기는 편이 낫습니다.

두 도구의 최적화 포인트는 어디가 다를까요?

구간	Codex	Claude Code	공통 판단
상시 지침	AGENTS.md 계층과 결합 바이트 한도	CLAUDE.md, 경로별 rules, 스킬	모든 작업에 필요한 규칙만 상시 로드
탐색 시작	--cd, 필요할 때만 --add-dir	실행 디렉터리, 경로별 규칙	저장소 전체보다 담당 디렉터리에서 시작
상태 진단	로드한 지침 출처와 실행 로그로 확인	/context, /usage	감이 아니라 실제 세션 정보 확인
긴 대화 정리	새 작업은 별도 실행으로 경계 분리	/compact, /clear	무관한 작업 기록을 다음 작업에 끌고 가지 않기
도구 구성	실행에 필요한 기능과 경로만 허용	MCP 도구 지연 로드, 스킬 필요 시 로드	쓰지 않는 도구 설명과 결과를 상시 컨텍스트에 두지 않기

기능 이름은 달라도 비용이 커지는 순간은 비슷합니다. 에이전트가 어디를 봐야 할지 몰라 디렉터리를 훑고, 큰 파일을 통째로 읽고, 긴 출력에서 다시 검색하고, 이전 작업의 문맥까지 매 요청에 싣는 순간입니다.

Claude Code는 프롬프트 캐시도 자동 관리합니다. 공식 문서에 따르면 요청 앞부분이 같으면 이미 처리한 내용을 캐시로 재사용하지만, 세션 중 모델이나 대부분 모델의 effort를 바꾸거나 일부 도구 구성이 달라지면 다음 요청에서 캐시를 다시 만들 수 있습니다. 모델과 effort는 가능하면 작업 시작 전에 정하고, 압축은 자연스러운 작업 경계에서 하는 편이 좋습니다.

프롬프트는 짧게보다 닫히게 쓰세요

좋은 프롬프트는 글자 수가 최소인 문장이 아니라 탐색의 끝이 보이는 작업 계약입니다. 목표, 범위, 제약, 검증 조건이 빠지면 에이전트가 추가 질문이나 광범위한 탐색으로 빈칸을 채웁니다.

나쁜 입력은 방향만 있습니다.

로그인 버그 고쳐줘.

조금 더 긴 입력이 오히려 불필요한 왕복을 줄일 수 있습니다.

세션 만료 뒤 로그인 화면으로 돌아오지 않는 문제를 수정해.
범위는 src/auth와 tests/auth로 제한하고, 먼저 관련 테스트를 찾아 실패를 재현해.
공개 API는 바꾸지 말고 수정 뒤 해당 테스트와 lint를 실행해.
큰 로그는 오류 전후만 요약해 보여줘.

예상되는 흐름은 전체 저장소 추측 → 여러 파일 열기가 아니라 두 디렉터리 검색 → 관련 테스트 재현 → 최소 파일 수정 → 지정 검증입니다. 이는 문서 기반의 예상 동작이며 실제 도구 호출 횟수는 저장소 상태와 에이전트 판단에 따라 달라집니다.

프롬프트에 파일 목록을 지나치게 많이 박아 넣는 것도 피합니다. 정확한 후보를 알고 있다면 경로를 주되, 모른다면 검색 기준과 제외 범위를 주는 편이 낫습니다.

파일 탐색은 찾기와 읽기를 분리하세요

큰 저장소에서 가장 낭비가 쉬운 패턴은 “관련 파일 전부 읽고 알려줘”입니다. 먼저 파일명이나 심볼을 찾고, 후보가 나온 다음 필요한 구간만 읽는 두 단계로 나누면 됩니다.

1) src와 tests에서 refreshToken을 정의하거나 호출하는 파일 경로만 찾아줘.
2) 결과를 최대 10개로 정리하고, 아직 파일 본문은 읽지 마.
3) 정의부와 실패 테스트 후보만 골라 필요한 함수 주변을 읽어줘.

명령 출력에도 경계를 둡니다. 전체 테스트 로그 대신 실패한 테스트 이름, 첫 오류, 관련 스택 구간을 우선 받습니다. 생성물, 의존성 폴더, 빌드 결과처럼 검색 가치가 낮은 경로는 프로젝트의 검색 도구나 ignore 설정으로 제외합니다.

한 번에 거대한 파일을 읽어야만 이해되는 구조라면 토큰 설정만의 문제가 아닐 수 있습니다. 모듈 경계, 긴 생성 파일, 한 파일에 섞인 책임을 정리하면 사람과 에이전트가 함께 덜 헤맵니다.

바로 적용할 최소 설정 순서

처음부터 복잡한 자동화를 붙일 필요는 없습니다. 아래 순서로 한 변수씩 바꾸면 무엇이 효과가 있었는지 판단하기 쉽습니다.

1. 기준 작업 하나를 정하고 현재 사용량과 도구 호출 흐름을 기록합니다.
2. AGENTS.md 또는 CLAUDE.md에서 중복 설명과 일회성 절차를 뺍니다.
3. 실행 디렉터리를 담당 서비스나 패키지로 좁힙니다.
4. 프롬프트에 범위·제약·완료 검증을 한 번에 넣습니다.
5. 검색 결과 수와 로그 출력 범위를 제한합니다.
6. 같은 종류의 작업으로 다시 측정합니다.

Claude Code의 /usage는 세션 단위 통계를 보여줍니다. API 사용자에게 표시되는 비용과 구독 플랜의 사용 한도는 의미가 같지 않으므로 토큰 수, 캐시 상태, 작업 완료 여부를 함께 봐야 합니다.

Codex에서도 로드한 지침 출처와 세션 기록을 확인하세요. 예상치 못한 상위 지침이나 지나치게 넓은 작업 루트가 잡혔는지 찾는 과정입니다.

비교할 때는 “짧아 보인다”가 아니라 같은 난이도의 작업에서 읽은 파일, 큰 출력, 재탐색, 수정 후 검증이 어떻게 달라졌는지 봅니다. 토큰만 줄고 오류가 늘었다면 최적화가 아니라 정보 부족입니다.

Codex와 Claude Code 중 무엇을 골라야 할까요?

이미 팀이 AGENTS.md 중심으로 규칙을 관리하고 작업 디렉터리별 실행을 선호한다면 Codex의 계층 구조가 자연스럽습니다. CLAUDE.md, 경로별 rules, /context와 /compact로 세션을 세밀하게 다루고 싶다면 Claude Code 쪽 기능이 더 직접적입니다.

비용만으로 하나를 고르는 것은 어렵습니다. 실제 사용량은 모델, 저장소 크기, 과업 난도, 재시도, 요금제에 좌우됩니다. 같은 대표 작업을 두 도구에 주고 완료 품질, 사람이 개입한 횟수, 읽은 범위, 사용량을 함께 비교해야 합니다.

작은 저장소에서 짧은 작업만 한다면 세밀한 규칙 분리의 관리비가 더 클 수도 있습니다. 반대로 모노레포에서 여러 팀의 규칙이 섞인다면 경로별 지침과 좁은 시작 위치가 효과를 내기 좋은 조건입니다.

적용할 때 놓치기 쉬운 한계

지침을 너무 줄이면 보안 규칙이나 필수 테스트가 빠질 수 있습니다. 토큰을 아끼려고 검증 출력을 없애기보다, 성공 여부와 첫 실패 원인을 남기고 반복 로그만 자르는 편이 안전합니다.

도구 정의를 줄이는 것도 기능 손실과 맞바꿀 수 있습니다. 쓰지 않는 Model Context Protocol(MCP) 서버를 상시 연결하지 않는 판단은 합리적이지만, 필요한 코드 탐색 도구까지 빼면 텍스트 검색과 파일 읽기가 오히려 늘 수 있습니다.

공식 문서는 계속 바뀝니다. 특정 설정 키나 명령이 보이지 않으면 현재 설치 버전의 도움말과 최신 공식 문서를 먼저 확인하세요. 이 글의 핵심은 특정 숫자를 외우는 일이 아니라 상시 입력, 탐색 범위, 출력, 세션 경계를 측정 가능한 단위로 줄이는 것입니다.

핵심 정리: 다섯 가지 질문과 답

Q. 프롬프트를 짧게 쓰면 토큰도 바로 줄까요?

항상 그렇지는 않습니다. 목표·범위·완료 조건이 빠지면 추가 탐색과 왕복이 늘 수 있어, 짧기보다 작업의 끝이 보이게 쓰는 편이 낫습니다.

Q. Codex에서 가장 먼저 손볼 곳은 어디일까요?

AGENTS.md의 중복과 실행 시작 디렉터리입니다. 공통 규칙은 짧게 유지하고 실제 작업 폴더에서 시작하되, 필요한 경로만 추가합니다.

Q. Claude Code의 컨텍스트가 커졌는지 어떻게 알 수 있나요?

/context로 점유 범주를 보고 /usage로 세션 사용량을 확인합니다. 관련 작업이면 초점을 준 /compact, 무관한 새 작업이면 /clear를 검토합니다.

Q. 파일 탐색 비용은 어떻게 줄이나요?

검색으로 후보 경로를 먼저 추린 뒤 정의부·호출부·실패 테스트의 필요한 구간만 읽습니다. 전체 로그와 생성물 디렉터리는 기본 탐색 대상에서 빼는 편이 좋습니다.

Q. 최적화가 성공했는지는 무엇으로 판단하나요?

같은 종류의 작업에서 사용량뿐 아니라 읽은 파일, 큰 출력, 재탐색, 사람 개입, 최종 검증까지 함께 비교합니다. 품질이 떨어졌다면 입력을 지나치게 줄인 것입니다.

출처

• OpenAI, Custom instructions with AGENTS.md, 확인일 2026-09-14
• OpenAI, Codex developer commands, 확인일 2026-09-14
• Anthropic, How Claude Code works, 확인일 2026-09-14
• Anthropic, How Claude remembers your project, 확인일 2026-09-14
• Anthropic, Explore the context window, 확인일 2026-09-14
• Anthropic, How Claude Code uses prompt caching, 확인일 2026-09-14
• Anthropic, Manage costs effectively, 확인일 2026-09-14

NEXT READ

이어서 보면 더 좋은 글

지금 읽은 내용과 연결되는 글만 골랐어요.

• AI 최신 기술Ponytail 사용법, Claude Code 과잉 구현을 줄이는 법내용 이어보기 →