AI 코딩 에이전트가 같은 파일을 계속 다시 읽을 때 무엇부터 줄일까 2026 — context budget·symbol search·handoff 로그 점검표

Posted on by

저도 오늘 블로그 파이프라인을 돌리면서 같은 문제를 다시 봤다.

글을 쓰기 전에 에이전트 규칙 파일을 읽고, 최근 패턴을 읽고, 기존 글을 찾고, 관련 글을 또 찾는다.

문제는 여기서 시작한다.

필요한 건 보통 한 줄인데, 에이전트는 가끔 파일 전체를 다시 읽는다.

사람으로 치면 열쇠 찾으려고 집 인테리어 도면부터 다시 보는 느낌이다.

똑똑한데 가끔 성실함이 과하다.

2026년 4월 19일 기준으로 AI 코딩 에이전트 비용을 볼 때 모델 가격만 보면 반쪽짜리다.

Claude Code, Codex, Cursor 계열 에이전트를 오래 쓰면 비용은 모델 자체보다 읽기 습관에서 새는 경우가 많다.

특히 이런 패턴이다.

  • 이미 본 파일을 다시 읽는다.
  • 함수 하나 보려고 파일 전체를 연다.
  • 넓은 grep으로 결과를 너무 많이 가져온다.
  • 세션을 갈아탄 뒤 같은 경로를 다시 탐색한다.
  • handoff 로그가 없어서 이전 결정을 다시 추론한다.

이 글은 새로운 비싼 도구부터 붙이는 글이 아니다.

먼저 할 일은 작고 재미없고 효과적인 것들이다.

파일을 읽기 전에 세고, 검색 범위를 줄이고, line range로 읽고, symbol search를 쓸지 판단하고, handoff 로그로 다음 세션의 재탐색을 막는 것.

네, 화려함은 없다.

하지만 청구서는 화려하지 않은 습관에서 조용히 얇아진다.

결론부터 말하면

AI 코딩 에이전트가 같은 파일을 계속 다시 읽는다면 먼저 줄일 것은 모델이 아니다.

먼저 줄일 것은 읽기 경로다.

내 기준 순서는 이렇다.

  1. 파일을 열기 전에 rg --files 또는 파일명 검색으로 후보를 줄인다.
  2. 내용 검색은 넓은 키워드보다 정확한 함수명, 설정명, 에러문으로 좁힌다.
  3. 파일 전체가 아니라 필요한 line range만 읽는다.
  4. 함수, 클래스, 타입 하나를 찾는 작업이면 symbol search나 code intelligence를 우선 고려한다.
  5. 세션을 갈아탈 때는 handoff 로그를 남긴다.
  6. 반복적으로 같은 탐색이 나오면 규칙 파일이나 스킬이 아니라 짧은 운영 체크리스트로 만든다.

핵심은 단순하다.

에이전트에게 더 많은 컨텍스트를 주는 게 아니라 더 좋은 입구를 주는 것이다.

왜 이 문제가 갑자기 중요해졌나

Reddit의 ClaudeAI 커뮤니티에서 Claude Code가 새 세션이나 작업 중에 전체 파일을 읽고, 잘못된 파일을 먼저 찾고, 그 다음에야 필요한 함수를 찾는다는 불만이 올라왔다.

그 글의 작성자는 Tree-sitter 기반 색인과 symbol 단위 제공을 통해 토큰 사용량을 줄이는 MCP 서버를 만들었다고 설명했다.

수치 주장은 해당 프로젝트의 주장으로 봐야 한다.

우리 글에서 그대로 실측처럼 말하면 안 된다.

하지만 신호는 분명하다.

사람들이 불편해하는 지점은 모델이 멍청하다가 아니다.

모델이 필요한 것보다 많이 읽는다다.

이건 TECHTAEK에서 다루기 좋은 주제다.

왜냐하면 실무자는 모델 교체보다 먼저 워크플로를 고칠 수 있기 때문이다.

공식 문서가 말하는 context budget

Claude Code 공식 문서는 context window가 대화 기록, 파일 내용, 명령 출력, CLAUDE.md, memory, skills, system instructions를 포함한다고 설명한다.

즉 파일을 읽는 행위는 그 순간만 지나가는 이벤트가 아니다.

다음 요청의 입력 크기에도 영향을 준다.

공식 문서의 비용 관리 페이지도 컨텍스트 크기가 커질수록 토큰 비용이 늘어난다고 설명한다.

그리고 /cost, status line, /clear, /compact, context 확인을 비용 관리 도구로 제안한다.

여기서 실무 포인트가 나온다.

컨텍스트는 큰 창고가 아니다.

매번 들고 다니는 배낭에 가깝다.

배낭에 불필요한 파일을 넣으면 다음 걸음도 무거워진다.

오늘 10분 감사표

글을 쓰기 전에 내 로컬 블로그 파이프라인에서 관련 파일 크기를 먼저 봤다.

단위는 줄 수다.

토큰 수가 아니라서 정확한 비용 계산표는 아니다.

하지만 무엇을 통째로 읽으면 위험한지 감은 충분히 준다.

점검 대상 결과 판단
.claude/rules/blog-writing.md 80줄 한 번 전체 읽기 가능
.claude/MEMORY/warm/recent-patterns.md 134줄 필요한 패턴만 검색 권장
.claude/agents/blog-pipeline-team.md 76줄 한 번 전체 읽기 가능
.claude/agents/blog-idea-capture-team.md 746줄 통째 읽기보다 검색 우선
blog-channel-qc 스킬 80줄 상위 규칙만 읽고 필요한 참고만 추가
관련 Claude Code 운영글 4개 3,432줄 중복 체크는 frontmatter와 특정 구간만

여기서 제일 중요한 숫자는 746줄과 3,432줄이다.

에이전트가 이런 파일을 매번 통째로 다시 읽는다면 비용도 비용이지만 판단도 흐려진다.

많이 읽는다고 항상 더 잘 아는 게 아니다.

가끔은 많이 읽어서 더 헷갈린다.

내가 실제로 본 실패도 있었다.

처음에는 이렇게 넓게 검색했다.

rg -n "Claude Code|MCP|context|토큰|비용" 02.Areas/blog ...

결과가 너무 많이 나왔다.

이건 중복 체크가 아니라 컨텍스트 폭포였다.

다음에는 이렇게 줄였다.

rg -n "같은 파일을|다시 읽|재탐색|handoff|symbol" <관련 파일 4개>

이제 필요한 사실이 보였다.

기존 글에는 비용 튐, handoff, system prompt, MCP/subagents/skills가 이미 있었다.

그래서 이번 글은 읽기 전 감사표와 재탐색 방지로 좁히는 게 맞다고 판단했다.

이게 context budget 운영이다.

같은 파일 재읽기는 왜 생기나

AI 코딩 에이전트가 같은 파일을 다시 읽는 이유는 대부분 악의가 아니다.

사실 성실함에 가깝다.

문제는 성실함에 예산표가 없을 때다.

주요 원인은 다섯 가지다.

첫째, 세션이 새로 시작됐다.

새 세션은 이전 대화의 세부 맥락을 모른다.

공식 문서도 각 세션은 독립적이고 새 context window로 시작한다고 설명한다.

둘째, handoff 로그가 없다.

이전 세션에서 어떤 파일을 봤고 어떤 결정을 했는지 짧게 남기지 않으면 다음 세션은 다시 탐색한다.

셋째, 검색 키워드가 너무 넓다.

cost, context, Claude Code 같은 단어는 AI 도구 글에서 너무 흔하다.

이 키워드로 검색하면 필요한 파일보다 주변 소음이 먼저 온다.

넷째, 함수 단위 질문인데 파일 단위로 접근한다.

질문은 validateToken() 하나인데 파일 전체를 읽으면 당연히 비싸다.

다섯째, 규칙과 참고자료가 한 곳에 섞여 있다.

항상 필요한 규칙, 가끔 필요한 참고, 거의 안 쓰는 사례가 한 파일에 붙어 있으면 매번 다 같이 딸려온다.

먼저 세어라

내가 가장 추천하는 첫 규칙은 읽기 전에 세는 것이다.

대단한 도구가 필요 없다.

wc -l path/to/file.md

또는

rg --files path/to/project

이 두 개만으로도 무작정 파일을 여는 일을 많이 줄일 수 있다.

파일이 50줄이면 그냥 읽어도 된다.

파일이 700줄이면 바로 읽기보다 먼저 찾는다.

파일이 3,000줄 묶음이면 전체 읽기는 마지막 선택이다.

이 기준을 팀 룰로 만들면 좋다.

파일 크기 추천 행동
1~120줄 전체 읽기 가능
121~500줄 먼저 rg -n으로 위치 찾기
501~1,500줄 line range 읽기 기본
1,500줄 이상 요약, symbol search, 전용 색인 우선

정확한 절대 기준은 아니다.

하지만 팀에 기준이 없을 때보다 훨씬 낫다.

기준이 없으면 에이전트는 친절하게 전부 읽는다.

친절은 고맙지만 영수증은 우리에게 온다.

파일 목록 검색이 먼저다

코드베이스를 탐색할 때 가장 싼 질문은 보통 이것이다.

rg --files

파일 내용을 읽기 전에 파일 이름으로 후보를 줄인다.

예를 들어 인증 로직을 찾는다면 처음부터 전체 grep을 때리지 않는다.

먼저 이런 식으로 본다.

rg --files | rg "auth|token|session"

그 다음에 정말 필요한 파일만 연다.

블로그 파이프라인에서도 똑같다.

Claude Code 비용 글을 찾을 때 전체 볼트에 비용을 검색하면 배당 ETF 비용, 종합소득세 비용, 코인 수수료까지 다 나온다.

이건 검색이 아니라 잡동사니 창고 뒤집기다.

먼저 경로를 줄인다.

rg --files 02.Areas/blog/ai_llm | rg "Claude Code|비용|context"

그 다음 내용 검색을 한다.

순서가 바뀌면 컨텍스트가 커진다.

내용 검색은 좁게 한다

내용 검색은 키워드가 아니라 질문으로 좁혀야 한다.

나쁜 검색은 이렇다.

rg -n "cost|context|file" .

좋은 검색은 이렇다.

rg -n "same file|reread|다시 읽|같은 파일" src docs

더 좋게는 실제 함수명, 설정명, 에러 메시지를 쓴다.

rg -n "validateToken|SessionStart|PreToolUse" src .claude

검색어가 넓을수록 에이전트는 더 많은 결과를 읽는다.

검색어가 좁을수록 에이전트는 더 빨리 결정한다.

이건 사람도 똑같다.

누가 나한테 저번에 그거 있잖아 라고 하면 내 뇌도 팬이 돈다.

4월 9일 handoff 글의 6줄 템플릿 이라고 하면 바로 간다.

line range 읽기를 기본으로 둔다

한 번 위치를 찾았으면 파일 전체를 열 필요가 없다.

line range로 읽으면 된다.

sed -n '680,730p' "파일명.md"

이 방식은 문서, 테스트, 로그, 설정 파일에 특히 좋다.

예를 들어 기존 TECHTAEK 글에서 같은 파일을 여러 번 본 세션 예시만 필요하면 전체 700줄을 열지 않아도 된다.

해당 구간만 보면 된다.

라인 범위 읽기는 에이전트에게도 좋은 습관이다.

왜냐하면 필요한 근거는 보존하면서 불필요한 문맥은 덜 싣기 때문이다.

symbol search는 언제 쓰나

symbol search는 함수, 클래스, 타입, 인터페이스, 메서드, 상수처럼 코드 구조를 기준으로 찾는 방식이다.

모든 프로젝트에 꼭 별도 MCP가 필요한 건 아니다.

IDE의 code intelligence, LSP, Tree-sitter 기반 색인, 전용 MCP, 간단한 rg 조합까지 수준은 다양하다.

중요한 질문은 이것이다.

내가 찾는 게 문장인가, 구조인가.

문장을 찾는다면 rg가 충분할 때가 많다.

구조를 찾는다면 symbol search가 유리하다.

예를 들어 validateToken이라는 함수가 어디 있는지, 어떤 테스트가 연결되는지, 이 함수를 바꾸면 어떤 호출자가 영향을 받는지 봐야 한다면 symbol 기반 탐색이 맞다.

반대로 블로그 글의 금지 헤더를 찾는 작업은 그냥 텍스트 검색이면 된다.

rg -n "Quick Answer|이 글이 필요한 사람|다음에 읽을 글" draft.md

도구를 멋으로 고르면 오히려 컨텍스트가 늘어난다.

질문 유형에 맞춰 고르면 컨텍스트가 줄어든다.

context budget 점검표

AI 코딩 에이전트를 쓰기 전에 아래 체크리스트를 30초만 본다.

  • [ ] 이 작업은 파일 전체가 필요한가?
  • [ ] 먼저 파일 목록으로 후보를 줄였나?
  • [ ] 검색 키워드가 너무 넓지 않은가?
  • [ ] 함수 하나를 보려는 작업인데 파일 전체를 열고 있지 않은가?
  • [ ] 이미 읽은 파일을 다시 읽는 이유가 분명한가?
  • [ ] 이전 세션의 handoff 로그가 있는가?
  • [ ] /context 또는 status line으로 사용량을 볼 수 있는가?
  • [ ] 비용이 튀면 /cost 또는 로그로 확인할 수 있는가?
  • [ ] 큰 문서는 요약본과 원문 링크가 분리돼 있는가?
  • [ ] 규칙 파일이 참고자료 창고가 되어 있지 않은가?

이 체크리스트의 목적은 에이전트를 묶는 것이 아니다.

오히려 반대다.

에이전트가 중요한 일에 토큰을 쓰게 만드는 것이다.

handoff 로그가 재탐색을 줄인다

세션이 바뀌면 에이전트는 다시 묻는다.

무엇을 했지?

어디까지 봤지?

어떤 파일이 중요하지?

무엇은 안 하기로 했지?

이 질문에 답이 없으면 다시 읽는다.

그래서 handoff 로그는 예쁜 문서가 아니라 재탐색 방지 장치다.

내가 추천하는 최소 handoff는 여섯 줄이다.

## Handoff
- Goal: 이번 세션의 목표
- Status: 완료 / 미완료
- Files: 본 파일과 바뀐 파일
- Decisions: 채택한 판단과 버린 선택지
- Failed checks: 실패한 검증
- Next: 다음 세션 첫 행동

여기서 중요한 줄은 Files와 Decisions다.

다음 세션이 이미 본 파일을 알면 재탐색을 줄인다.

이미 버린 선택지를 알면 같은 논쟁을 다시 하지 않는다.

이건 팀 작업에도 좋고 혼자 작업에도 좋다.

어제의 나는 오늘의 나에게 꽤 불친절하기 때문이다.

규칙 파일은 짧게 둔다

Claude Code 문서에서는 CLAUDE.md가 세션 시작 시 로드되는 항상 켜진 컨텍스트라는 점을 설명한다.

그래서 여기에 모든 참고자료를 넣으면 위험하다.

항상 필요한 규칙만 넣고 가끔 필요한 자료는 스킬, docs, runbook, 링크로 빼는 편이 낫다.

공식 extension 문서도 CLAUDE.md, skills, MCP, subagents, hooks가 각기 다른 로딩 방식과 context cost를 가진다고 설명한다.

실무적으로는 이렇게 나눈다.

넣을 곳 넣을 내용
CLAUDE.md 항상 지켜야 하는 짧은 규칙
skill 특정 업무 때만 필요한 절차
docs 길고 상세한 참고자료
hook 반드시 자동 실행돼야 하는 검사
handoff 이번 세션의 상태와 다음 행동

모든 것을 CLAUDE.md에 넣으면 에이전트가 늘 똑똑해질 것 같지만 실제로는 늘 무거워질 수 있다.

status line을 붙이면 좋은 경우

Claude Code status line 문서에는 context window usage, cost, git status 등을 작업 중 계속 보이게 할 수 있다고 나온다.

이건 비용을 직접 줄이는 도구라기보다 비용을 보이게 하는 도구다.

보이면 덜 낭비한다.

운동할 때 걸음 수가 보이면 갑자기 계단을 오르는 척하게 되는 것과 비슷하다.

개발자 버전은 이렇다.

context 82%가 보이면 갑자기 파일 전체 읽기가 민망해진다.

status line이 특히 좋은 경우는 다음과 같다.

  • 장시간 세션을 자주 쓴다.
  • 같은 작업을 여러 번 resume한다.
  • Pro와 API 비용을 같이 관리한다.
  • subagent나 MCP를 여러 개 붙인다.
  • 팀원이 각자 다른 방식으로 Claude Code를 쓴다.

단, status line 자체가 너무 무거우면 안 된다.

비용 보려고 붙인 장치가 매번 비싼 명령을 돌리면 이건 건강검진 받으러 갔다가 감기 걸리는 그림이다.

MCP나 색인 도구는 언제 붙이나

Reddit 원문은 로컬 MCP 서버가 코드베이스를 색인하고 필요한 symbol, dependency, 구조만 제공하는 방향을 제안했다.

이 접근은 매력적이다.

특히 큰 코드베이스에서는 함수 하나 찾으려고 긴 파일을 반복해서 읽는 비용이 크다.

다만 무조건 붙이면 된다는 뜻은 아니다.

MCP도 운영 대상이다.

설치, 권한, 인덱싱, 업데이트, 실패 복구, 팀 공유, 보안 경계가 생긴다.

내 기준은 이렇다.

상황 추천
작은 프로젝트 rg, line range, handoff부터
중간 규모 코드베이스 IDE code intelligence 또는 LSP 활용
큰 monorepo symbol index, dependency graph 검토
자주 같은 함수군을 찾음 symbol search 도입 가치 높음
문서 중심 작업 MCP보다 문서 요약과 링크 정리가 먼저
보안 민감 코드 로컬 색인, 권한, 로그 보존 정책 먼저

즉 MCP는 답이 될 수 있다.

하지만 첫 답은 아니다.

첫 답은 넓게 읽지 않는 습관이다.

새 도구 없이 줄이는 5단계

가장 현실적인 운영 순서는 아래다.

1단계: 파일 후보만 찾기

rg --files src docs tests | rg "auth|token|session"

이 단계에서는 파일 내용을 읽지 않는다.

후보만 줄인다.

2단계: 정확한 키워드로 위치 찾기

rg -n "validateToken|refreshSession|SessionStart" src tests

에러 메시지가 있으면 에러 메시지를 그대로 쓴다.

3단계: line range만 읽기

sed -n '120,190p' src/auth/session.ts

함수 주변만 본다.

필요하면 위아래를 조금 넓힌다.

4단계: 결정 기록하기

- Read: src/auth/session.ts:120-190
- Decision: validateToken itself is fine; refreshSession caller is suspect
- Next: inspect tests around expired token branch

이 한 줄이 다음 재탐색을 막는다.

5단계: 반복되면 규칙화하기

반복되는 탐색이면 handoff에만 남기지 말고 작은 runbook으로 올린다.

예를 들면 이렇다.

## Auth Debug Search Path
1. Search `validateToken|refreshSession`.
2. Read `src/auth/session.ts` around hit only.
3. Check `tests/auth/session-expiry`.
4. Do not read all auth files unless caller graph is unclear.

이 정도면 충분하다.

거대한 문서보다 짧은 길 안내가 더 잘 먹힌다.

기존 TECHTAEK 글과 어떻게 다르나

이 주제는 이미 쓴 글들과 겹치기 쉽다.

그래서 선을 분명히 그어야 한다.

이미 있는 글들은 이런 역할이다.

  • Claude Code API 비용이 갑자기 튈 때...: 비용이 오른 뒤 로그에서 원인을 찾는 글
  • Claude Code 세션 handoff...: 세션을 넘길 때 무엇을 남길지 정리한 글
  • Claude Code system prompt...: 항상 켜진 프롬프트와 설정을 줄이는 글
  • Claude Code에서 MCP·subagents·skills...: 확장 기능을 한꺼번에 붙일 때 느려지는 이유를 정리한 글

이번 글의 역할은 다르다.

이번 글은 비용이 튄 뒤 진단이 아니라 비용이 튀기 전 읽기 경로를 줄이는 글이다.

핵심 문장은 이것이다.

파일을 읽기 전에, 먼저 어디만 읽을지 결정하라.

이 한 문장만 지켜도 AI 코딩 에이전트 운영 품질이 꽤 달라진다.

팀에서 바로 적용하는 규칙

팀에서 쓸 때는 에이전트에게 이렇게 지시하면 된다.

Before reading any file over 300 lines:
1. Search the filename or symbol first.
2. Read only the relevant line range.
3. Record what was read in the handoff note.
4. Do not reread the same file unless the reason is explicit.

한국어로는 이렇게 써도 된다.

300줄 넘는 파일은 바로 전체 읽기 금지.
먼저 파일명/심볼/에러문으로 위치를 찾고,
필요한 line range만 읽어라.
이미 읽은 파일을 다시 읽을 때는 이유를 한 줄로 남겨라.

이건 에이전트의 자유를 빼앗는 규칙이 아니다.

오히려 좋은 탐색을 하게 만드는 가드레일이다.

코드 리뷰 작업에서는 더 중요하다

코드 리뷰는 특히 위험하다.

PR 하나를 보려고 관련 파일, 테스트, 문서, 설정, 이전 이슈까지 다 열면 금방 커진다.

리뷰 작업에서는 먼저 바뀐 파일부터 본다.

그 다음 영향 받는 symbol을 본다.

그 다음 테스트를 본다.

그래도 부족하면 주변 파일을 본다.

순서는 이렇다.

  1. diff
  2. changed symbols
  3. direct callers
  4. tests
  5. docs or config
  6. broader architecture

처음부터 6번으로 가면 리뷰가 철학 세미나가 된다.

철학도 좋지만 PR은 보통 금요일 오후에 온다.

살아남아야 한다.

문서 작업에서는 이렇게 바꾼다

문서 작업은 코드보다 더 넓게 퍼진다.

비슷한 글, 비슷한 제목, 비슷한 허브, 비슷한 소스가 많다.

그래서 문서 작업의 첫 질문은 이 글과 가장 가까운 기존 글 3개가 무엇인가다.

오늘 감사에서도 그랬다.

관련 글 4개가 3,432줄이었다.

이걸 다 읽으면 새 글을 쓰기 전에 이미 지친다.

대신 frontmatter와 특정 구간만 봤다.

중복 여부는 대개 제목, 요약, published_url, 핵심 체크리스트만 봐도 판단된다.

전체 문체를 맞출 때만 일부 본문을 읽으면 된다.

비용을 수치로 과장하지 말자

이 주제에서 조심할 점이 하나 있다.

토큰 절감률을 쉽게 말하면 안 된다.

Reddit 원문에는 큰 절감률 주장이 나온다.

그건 그 프로젝트와 그 테스트 조건의 주장이다.

우리 작업에서 실측한 것은 라인 수, 검색 결과의 폭, 중복 글의 분량, 탐색 순서다.

따라서 이 글의 약속도 정직해야 한다.

이렇게 하면 무조건 90% 줄어든다 가 아니다.

이렇게 하면 같은 파일을 다시 읽는 패턴을 발견하고 줄일 수 있다 다.

TECHTAEK 글은 숫자를 크게 부풀릴수록 약해진다.

작은 숫자를 정확히 말할 때 오래 간다.

실패 신호

아래 신호가 보이면 context budget이 새고 있을 가능성이 높다.

  • 같은 파일명이 세션 로그에 여러 번 나온다.
  • 검색 결과가 수백 줄인데 그대로 읽는다.
  • 파일 하나를 읽고도 다음 행동이 정해지지 않는다.
  • /compact가 자주 필요하다.
  • handoff가 없어서 세션마다 같은 질문을 한다.
  • 규칙 파일이 계속 길어진다.
  • MCP, skills, hooks를 붙였는데 체감 속도는 느려졌다.
  • 비용이 올랐는데 어떤 행동 때문인지 설명하지 못한다.

이 중 세 개 이상이면 모델 교체보다 탐색 루틴부터 보는 편이 낫다.

좋은 신호

반대로 좋은 신호도 있다.

  • 파일을 열기 전에 후보 파일 수가 줄어든다.
  • sed -n이나 line range 읽기가 늘어난다.
  • handoff에 이미 본 파일이 남는다.
  • 기존 글이나 기존 코드와의 차이가 한 문장으로 정리된다.
  • 큰 파일은 요약본과 원문 링크가 분리된다.
  • 함수 단위 질문은 symbol 또는 호출자 기준으로 좁혀진다.
  • /context나 status line으로 현재 상태를 볼 수 있다.

이런 신호가 있으면 에이전트가 더 적게 읽고도 더 잘 움직인다.

내 추천 운영 문구

에이전트에게 바로 넣을 수 있는 문구는 이렇다.

Context budget rule:
Search before reading.
For files over 300 lines, avoid full reads unless necessary.
Prefer file list, exact keyword search, symbol lookup, and line-range reads.
When rereading a file, state why.
At handoff, list files already inspected and the decision made from each.

한국어 버전은 이렇다.

컨텍스트 예산 규칙:
읽기 전에 먼저 검색한다.
300줄 넘는 파일은 필요할 때만 전체를 읽는다.
파일 목록, 정확한 키워드, symbol 탐색, line range 읽기를 우선한다.
같은 파일을 다시 읽을 때는 이유를 남긴다.
handoff에는 이미 본 파일과 그 파일에서 내린 결정을 적는다.

이 정도면 너무 무겁지 않다.

규칙이 길어지면 그 규칙 자체가 context budget을 먹는다.

규칙도 다이어트가 필요하다.

네, 규칙도 야식 먹는다.

언제 전체 파일을 읽어도 되나

전체 파일 읽기가 항상 나쁜 것은 아니다.

다음 경우에는 전체 읽기가 맞다.

  • 파일이 짧다.
  • 구조 전체가 중요한 설정 파일이다.
  • 보안 리뷰라서 빠뜨리면 안 된다.
  • 리팩터링 전에 전체 흐름을 파악해야 한다.
  • 문서의 톤과 구조를 통째로 봐야 한다.
  • line range만 보면 오해할 가능성이 크다.

문제는 전체 읽기가 아니라 무의식적인 전체 읽기다.

의도한 전체 읽기는 투자다.

습관적 전체 읽기는 비용이다.

FAQ

Q1. Claude Code만의 문제인가?

아니다.

Claude Code에서 자주 보일 뿐, 긴 컨텍스트를 쓰는 AI 코딩 에이전트 전반의 문제다.

Codex, Cursor, Windsurf, OpenCode류 도구에서도 탐색 경로가 넓으면 비슷한 문제가 생길 수 있다.

도구보다 작업 방식의 문제에 가깝다.

Q2. /compact를 자주 쓰면 해결되나?

부분적으로만 해결된다.

/compact는 긴 세션을 이어가는 데 도움을 준다.

하지만 큰 파일을 계속 다시 읽는 습관은 요약 후에도 반복될 수 있다.

먼저 읽기 경로를 줄이고, 그 다음 compact를 쓰는 편이 낫다.

Q3. symbol search는 꼭 MCP로 해야 하나?

아니다.

IDE code intelligence, LSP, Tree-sitter 색인, 전용 MCP, 단순 rg 조합 모두 선택지다.

중요한 건 함수나 타입 하나를 찾는 작업에 파일 전체 읽기를 남발하지 않는 것이다.

Q4. 작은 프로젝트도 이 규칙이 필요한가?

작은 프로젝트에서는 느슨하게 적용해도 된다.

다만 handoff와 line range 습관은 작을 때 들여야 커져도 유지된다.

처음부터 거창한 MCP를 붙일 필요는 없다.

Q5. 비용이 아니라 속도 때문에도 필요한가?

그렇다.

컨텍스트가 커지면 비용뿐 아니라 응답 속도, 판단 선명도, 실수 가능성에도 영향을 줄 수 있다.

적게 읽는다는 건 덜 아는 게 아니라 필요한 것을 먼저 아는 것이다.

Q6. 이미 읽은 파일을 다시 읽으면 무조건 나쁜가?

아니다.

파일이 바뀌었거나, 다른 line range가 필요하거나, 처음 판단을 검증해야 한다면 다시 읽어야 한다.

다만 이유 없이 같은 파일 전체를 반복해서 읽는 것은 줄일 대상이다.

Q7. 팀 규칙으로 넣으면 에이전트가 답답해지지 않나?

너무 빡빡하게 쓰면 답답해진다.

그래서 금지가 아니라 우선순위로 쓰는 게 좋다.

검색 먼저, 필요한 범위만, 재읽기 이유 남기기 정도면 충분하다.

관련 글

이 글은 아래 글들과 같이 묶으면 좋다.

읽는 순서는 이 글을 먼저 보고, handoff 글, system prompt 글, MCP/subagents 글로 가는 게 좋다.

먼저 새는 구멍을 보고 그 다음 구조를 고치는 순서다.

참고 자료/공식 출처

마무리

AI 코딩 에이전트가 같은 파일을 계속 다시 읽는다면 그건 꼭 모델이 나빠서가 아니다.

대부분은 탐색 입구가 넓고, handoff가 짧지 않고, 읽기 기준이 없어서 생긴다.

처음부터 거대한 도구를 붙이지 않아도 된다.

먼저 파일을 세고, 검색을 좁히고, line range로 읽고, symbol search가 필요한 순간만 구분하고, handoff에 이미 본 파일과 결정을 남기자.

이 다섯 가지가 잡히면 AI 에이전트는 덜 읽고도 더 빨리 움직인다.

그리고 우리 지갑은 아주 조금 덜 긴장한다.

이 정도면 작지만 확실한 운영 승리다.