Claude Codex 토큰 절약 컨텍스트 엔지니어링Claude Codex Token-Saving Context Engineering
📅
들어가기 전에 🔗
AI 코딩 에이전트를 오래 사용하며 일을 하다 보면,
비용
은 모델을 잘 선택하는 것도 중요하지만 작업 방식에서 크게 갈립니다.
같은 기능을 구현해도 한쪽은 필요한 파일만 읽고 한 번에 테스트를 통과하지만, 다른 쪽은 저장소 전체를 훑고 여러 번 수정한 뒤 다시 시작합니다.
이 차이는 입력 토큰, 도구 호출 횟수, 대기 시간, 그리고 개발자의 재검토 시간으로 구성되며 이가 누적될수록 그 체감은 커집니다.컨텍스트 엔지니어링
은 모델에게 많은 정보를 때려넣는 것이 아니라, 현재 작업에 필요한 정보만 정확한 순서로 제공하는 일
입니다.
현재 작업을 정확히 끝내는 데 필요한 정보만 적절한 순서로 제공하고, 다음 작업에도 재사용할 수 있게 상태를 남기는 설계입니다.
Claude Code와 Codex 등 모든 AI 코딩 에이전트에 이 원칙은 공통으로 적용됩니다.이 글에서는 토큰을 단순히 줄이는 데서 멈추지 않고, 재작업까지 줄이는 실무 흐름을 다뤄보도록 하겠습니다.
👨💻
회사에서 제공해주는 Agent가 지금 당장 부족하지 않아도, 토큰과 재작업을 줄이는 습관은 갑작스러운 정책 변경이나 모델 교체에도 대응할 수 있는 힘을 길러주겠죠.
필요한 정보만 모아 검증 결과로 연결하는 컨텍스트 엔지니어링 흐름
토큰 절약 원칙 🔗
짧은 프롬프트가 언제나 토큰을 적게 소모하는 것은 아닙니다.
정보가 부족하면 에이전트가 필요하지 않은 파일을
더 많이 탐색하거나 잘못된 가정을 세워 수정과 테스트를 반복하기 때문입니다.
그렇다고 모든 아키텍처 문서와 로그를 한 번에 넣으면 중요한 지시가 묻히고 입력 비용도 커지죠.토큰 낭비 요인 🔗
- 불필요한 저장소 탐색에이전트가 작업과 관계없는 파일을 읽으면서 컨텍스트가 커지는 상황입니다.
- 중복된 저장소 지침AGENTS.md, CLAUDE.md, README에 같은 규칙이 반복되어 매 작업마다 다시 읽히는 상황입니다.
- 너무 큰 도구 출력전체 테스트 로그, 전체 API 응답, 빌드 산출물을 그대로 전달하는 상황입니다.
- 검증 없는 수정수정 범위와 완료 조건이 불명확해 같은 파일을 여러 번 고치는 상황입니다.
토큰 사용량은 비용 지표이지만, 재작업 횟수는 품질 지표이기도 합니다.
토큰이 적어도 재작업이 많다면 좋은 워크플로가 아닙니다.
따라서 한 작업의 효율을 볼 때는 입력과 출력 토큰만 보지 말고 도구 호출 수, 실패한 테스트 수, 사람이 되돌린 변경 수도 함께 기록하며 개선한다면 더 나은 결과를 얻을 수 있습니다.측정 지표 🔗
처음부터 거대한 관측 시스템을 만들 필요는 없습니다.
같은 유형의 작업 세 개를 골라 아래 항목만 기록해도 개선 효과를 확인할 수 있습니다.
| 측정 항목 | 나쁜 신호 | 개선 목표 |
|---|---|---|
| 읽은 파일 수 | 작업 범위보다 훨씬 많음 | 변경 경로에 필요한 파일로 제한 |
| 도구 호출 수 | 동일 명령을 반복 실행 | 탐색과 검증 명령을 사전에 명시 |
| 테스트 재시도 | 원인을 모른 채 반복 | 실패 로그의 관련 부분만 전달 |
| 수정 파일 수 | 작은 기능에 광범위한 변경 | 허용 범위를 작업 요청에 포함 |
| 사람 리뷰 시간 | 의도를 다시 해석해야 함 | 완료 조건과 검증 결과를 함께 남김 |
작업 범위 🔗
에이전트에게 기능 이름만 전달하면, 필요한 파일과 완료 기준을 스스로 추론해야 합니다.
간단한 일에서는 문제가 없어 보여도 저장소가 커질수록 탐색 범위와 가정이 빠르게 늘어납니다.
👨💻
에이전트에게 프로젝트 폴더를 주고 그냥 ~기능 수정해줘 라고 하면 문서 전체를 탐색하며 토큰을 소모합니다.작업 범위와 완료 조건을 먼저 고정하는 것
이 가장 작은 비용 절감할 수 있도록 에이전트를 도와주는 방법입니다.작업 요청 템플릿 🔗
아래 템플릿은 채팅 입력, 이슈 본문, 자동화 파이프라인의 작업 지시 어디에나 사용할 수 있습니다.
목표
- 게시글 목록 API에 페이지네이션을 추가합니다.
수정 범위
- src/app/api/posts/route.ts
- src/lib/posts/query.ts
- 관련 테스트 파일
완료 조건
- page와 limit이 없을 때 기존 응답과 호환됩니다.
- 잘못된 쿼리는 400 응답을 반환합니다.
- npm test와 npm run lint가 통과합니다.
금지 사항
- 데이터베이스 스키마와 공개 응답 필드는 변경하지 않습니다.
- 지정한 범위 밖 리팩터링은 하지 않습니다.
작업 방식
- 수정 전에 관련 파일만 읽고 변경 계획을 세웁니다.
- 완료 후 수정 파일과 검증 결과를 짧게 요약합니다.이 형식의 핵심은
상세한 구현 절차를 강요하지 않는
데 있습니다.
에이전트가 문제를 푸는 방식은 맡기되, 어디까지 읽고 무엇으로 성공을 판정할지는 사람이 판단합니다.작업 분리 기준 🔗
한 번의 작업이 여러 경계를 넘는다면 분리하는 편이 좋습니다.
예를 들어 인증, 데이터베이스 마이그레이션, 화면 변경을 한 요청에 넣으면 각각의 실패 원인이 섞이게 되겠죠.
아래 순서로 나누면 필요한 컨텍스트도 작아집니다.
조사 단계에서는 관련 경로와 현재 동작만 확인합니다.구현 단계에서는 확정한 파일과 테스트만 다룹니다.리뷰 단계에서는 변경된 diff와 검증 결과만 확인합니다.
이렇게 분리하면 이전 단계의 긴 탐색 로그를 다음 단계에 모두 들고 갈 필요가 없습니다.
저장소 지침 🔗
AGENTS.md와 CLAUDE.md는 팀의 규칙을 전달하기에 유용합니다.
하지만 모든 역사와 예외를 한 파일에 쌓으면, 사소한 수정에도 관련 없는 지침이 함께 로드됩니다.
지침 파일은 백과사전이 아니라 작업을 올바른 문서와 명령으로 안내하는 라우터
여야 합니다.최소 지침 🔗
루트 지침에는 다음처럼 대부분의 작업에 공통인 내용만 둡니다.
# 프로젝트 공통 규칙
- 패키지 설치는 npm을 사용합니다.
- 변경 후 npm run lint와 npm test를 실행합니다.
- API 응답 형식 변경은 요청에 명시된 경우에만 허용합니다.
- 데이터베이스 변경은 prisma/schema.prisma와 migration을 함께 검토합니다.
# 작업별 안내
- 인증 작업은 docs/auth.md를 읽습니다.
- 배포 작업은 docs/deploy.md를 읽습니다.
- 데이터베이스 마이그레이션은 docs/database-migrations.md를 읽습니다.인증이나 배포처럼 일부 작업에만 필요한 상세 절차는 별도 문서에 둡니다.
에이전트가 해당 작업을 할 때만 문서를 읽으므로, 매번 지침 전체를 download하지 않아도 됩니다.
OpenAI 공식 문서도 길거나 중복된
Skill 설명과 과도한 저장소 지침이 컨텍스트를 차지하고 필요한 지시의 선택을 어렵게 만들 수 있다고 설명합니다.
OpenAI Docs Skills와 프롬프트 재설계↗제거할 지침 예시 🔗
- 이미 package.json 스크립트로 확인 가능한 긴 명령 목록입니다.
- Git 히스토리에서만 의미가 있는 과거 결정 기록입니다.
- 특정 기능이나 폴더에만 적용되는 상세 규칙입니다.
- 서로 다른 문서에서 반복되는 코드 스타일 규칙입니다.
삭제 전에 잃으면 안 되는 내용은 별도 문서로 옮기고, 루트 지침에는 링크와 적용 조건만 남기면 됩니다.
거대한 단일 지침 문서와 작업별 문서로 나뉜 라우터 구조의 비교
작업 상태 🔗
긴 작업을 이어갈 때 대화 기록 전체를 유지하면 이전의 탐색 결과와 실패 로그가 계속 컨텍스트를 차지합니다.
반면 작업 상태를
짧은 파일
로 남기면 새 세션에서도 필요한 사실만 읽고 다시 시작할 수 있습니다.상태 문서 🔗
상태 문서는 길 필요가 없습니다.
아래 정보만 있어도 새 에이전트나 다른 팀원이 바로 이어받을 수 있습니다.
# 게시글 페이지네이션 작업 상태
## 완료
- 기존 목록 API의 응답 구조를 확인했습니다.
- page와 limit의 기본값을 합의했습니다.
## 남은 작업
- query.ts에 범위 검증을 추가합니다.
- route 테스트에 잘못된 limit 사례를 추가합니다.
## 검증 명령
- npm test -- posts
- npm run lint
## 결정 사항
- 기존 클라이언트 호환성을 위해 total 필드는 추가하지 않습니다.이 파일은 일시적인 대화 요약이 아니라 프로젝트의
결정 기록
입니다.
작업이 끝나면 삭제하거나 ADR과 이슈에 핵심 결정만 옮기면 됩니다.Claude의 공식 가이드도 여러 컨텍스트 창에 걸친 작업에서는 첫 단계에서 테스트와 설정을 준비하고, 이후 단계에서는 구조화된 상태를 활용하는 방식을 권장합니다.
Anthropic Prompting Best Practices↗
새 세션 기준 🔗
다음 상황에서는 이전 대화를 무조건 이어가기보다 새 세션을 시작하는 편이 효율적입니다.
- 조사 단계가 끝나고 구현 범위가 확정된 경우.
- 오류 로그가 길고 여러 번의 실패 시도가 쌓인 경우.
- 담당 기능이 완전히 바뀌어 이전 파일 목록이 의미 없어진 경우.
- 리뷰만 남아 구현 대화의 세부 과정이 더 이상 필요하지 않은 경우.
새 세션의 첫 요청에는 작업 상태 파일, 변경 파일 목록, 검증 명령만 넣습니다.
이 방식은 컨텍스트를 비우는 동시에 사람이 남긴 결정을 보존하게 됩니다.
도구 출력과 검증 🔗
에이전트가 터미널과 MCP 도구를 사용할 때 토큰은 명령 자체보다 결과에서 많이 소모됩니다.
전체 빌드 로그나 전체 테이블 목록을 읽히기보다, 다음 판단에 필요한 결과만 반환해야 합니다.
도구 출력 🔗
파일을 찾을 때는 전체 내용을 먼저 출력하지 말고 경로와 검색 결과를 좁힙니다.
# 필요한 경로를 먼저 찾습니다.
rg --files src | rg 'posts|pagination'
# 관련 심볼이 있는 줄만 확인합니다.
rg -n 'getPosts|page|limit' src/app src/lib
# 확정한 파일만 읽습니다.
sed -n '1,220p' src/lib/posts/query.ts테스트가 실패했을 때도 전체 로그보다 실패한 테스트 이름, 오류 메시지, 관련 스택 프레임부터 확인합니다.
그 뒤에도 원인이 불명확할 때만 출력 범위를 넓힙니다.
검증 루프 🔗
토큰을 아끼려고 테스트를 생략하면 결국 더 많은 재작업이 발생합니다.
대신 한 작업의 완료 기준에 맞춘 가장 작은 검증을 먼저 실행하고, 마지막에 전체 검증을 실행합니다.
1. 변경한 함수의 단위 테스트를 실행합니다.
2. 변경 경로의 타입 검사와 린트를 실행합니다.
3. 영향 범위가 확인되면 전체 테스트를 실행합니다.
4. 수정 파일과 테스트 결과를 diff와 함께 검토합니다.Codex에서는 현재 세션의 모델, 컨텍스트 사용량, 토큰 사용량을
/status 명령으로 확인할 수 있습니다.
작업 전후 수치를 기록하면 어떤 지침과 워크플로가 실제로 효과가 있었는지 판단할 수 있습니다.
파일 검색부터 코드 수정과 테스트, 변경 검토로 이어지는 검증 루프
팀 체크리스트 🔗
✓ 작업 요청에 목표, 수정 범위, 완료 조건, 금지 사항을 적습니다.
✓ 루트 AGENTS.md 또는 CLAUDE.md에는 공통 규칙과 문서 경로만 남깁니다.
✓ 긴 로그와 큰 응답은 먼저 검색하거나 요약해 필요한 부분만 읽습니다.
✓ 조사, 구현, 리뷰처럼 컨텍스트가 다른 단계는 별도 세션으로 분리합니다.
✓ 작업 상태와 검증 명령은 저장소의 짧은 문서로 남깁니다.
✓ 작은 테스트부터 실행하고 마지막에 전체 검증과 diff 리뷰를 합니다.
✓ 한 달 동안 작업 세 개만 골라 읽은 파일 수, 테스트 재시도, 리뷰 시간을 비교합니다.
결론 🔗
Claude와 Codex의 토큰을 절약하는 가장 좋은 방법은 정보량을 무작정 줄이는 것이 아닙니다.
에이전트가 올바른 파일을 읽고, 필요한 도구만 호출하고, 한 번의 수정으로 검증까지 끝낼 수 있게 작업 환경을 설계하는 일입니다.
작업 요청을 계약처럼 작성하고, 저장소 지침을 작업별 문서로 나누고, 상태를 파일로 남기는 세 가지부터 적용해 보시기 바랍니다.