클로드 코드가 파일을 일부만 읽고 작업할 때 — 전체를 읽게 하는 프롬프트·CLAUDE.md 설정

Q: 지침이 로드됐는지는 어떻게 확인하나요?

/context를 실행해 Memory files 목록을 보면 됩니다. 목록에 없는 파일은 Claude가 볼 수 없습니다.

Claude Code(클로드 코드 — 터미널에서 코드를 읽고 고쳐 주는 Claude의 개발 도구)에게 긴 파일을 맡겼는데, 파일 앞부분만 보고 답한 것 같은 경험을 하신 분이 적지 않습니다. 이 글은 그 이유와, 공식 문서로 확인되는 범위 안에서 전체를 읽게 만드는 방법을 정리합니다. 따라 하는 데 10~15분 정도 걸립니다.

🟢 현행 모델 라인업 일치 · 모델 안내 · Fable 구독 안내

🟢 현행 모델 라인업 일치 · Claude Opus 5.5 / Claude Sonnet 5.5 / Claude Haiku 5.5 (상위 티어: Claude Fable 5.1). 이 안내는 새 모델이 출시될 때만 바뀝니다.

Fable 5·5.1 구독 안내(2026년 11월 1일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Ultra·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당 $10, 출력 $50)으로 이용합니다. 일회성 $100 크레딧은 Fable 5 전환 당시에만 지급됐고 5.1에는 없습니다. 일부 코딩·디버깅 요청은 보안 분류기에 의해 Opus 모델로 대체 응답될 수 있습니다(두 모델 공통). 자세한 내용은 Fable 5.1 가이드와 Fable 5 재개 안내를 참조하세요.

이 글로 할 수 있게 되는 것

Claude Code가 파일을 어떻게 읽는지 이해하고, 전체를 읽도록 요청하는 문장과 CLAUDE.md(클로드 코드가 매 세션 시작 때 읽는 지침 파일) 규칙을 직접 만들 수 있게 됩니다.

시작 전 준비물

Claude Code 설치와 로그인 — 이미 쓰고 계신 상태를 전제로 합니다.
작업 폴더 — 프로젝트 폴더에서 claude를 실행한 상태입니다.
버전 확인 — 아래 '전체 읽기' 기능은 문서상 v2.1.296 이상에서 언급됩니다. 버전은 화면에서 직접 확인하세요.

용어 빠른 풀이

Read 도구 — Claude Code가 파일 내용을 읽을 때 쓰는 내장 기능입니다.
컨텍스트(context window) — Claude가 한 번에 기억하고 참고할 수 있는 작업 메모장입니다.
토큰 — Claude가 글자를 세는 단위입니다. 대략 단어 조각 하나로 보시면 됩니다.
offset·limit — 파일의 어느 줄부터(offset) 몇 줄까지(limit) 읽을지 정하는 값입니다.
훅(hook) — 정해진 시점에 자동으로 실행되는 명령입니다. Claude의 판단과 무관하게 실행됩니다.

왜 파일 일부만 읽은 것처럼 보이나요?

긴 파일은 한 번에 다 읽히지 않고 나눠서 읽히기 때문입니다. 문서에 따르면 Read 호출 한 번은 기본적으로 최대 25,000 토큰까지 돌려주고, 256 KB를 넘는 파일은 통째로 읽기를 거부하므로, Claude는 큰 파일을 offset과 limit으로 나눠 읽습니다. 한도를 넘는 파일을 읽으면 PARTIAL view 안내와 함께 첫 부분이 돌아오고, 더 읽는 방법이 함께 표시됩니다.

즉 기능상 이어 읽을 수는 있지만, 이어 읽을지는 Claude의 판단에 달려 있습니다. 그래서 요청이 모호하면 앞부분만 보고 진행하는 일이 생길 수 있습니다. 구체적인 발생 빈도는 공식 문서에 나와 있지 않습니다.

어떻게 하면 전체를 읽게 할 수 있나요?

요청 문장에서 읽을 범위를 분명히 말하고, 반복되는 요구는 CLAUDE.md에 적어 두는 것이 기본입니다. 아래 단계대로 해 보세요.

1단계. 프롬프트에 범위를 명시합니다

Claude Code 입력창에 다음처럼 입력합니다. 파일 경로는 본인 것으로 바꾸세요.

src/app/page.tsx 파일을 끝까지 모두 읽은 뒤에 작업해 주세요.
한 번에 다 읽히지 않으면 이어서 읽고, 다 읽었다고 확인한 뒤에 수정을 시작해 주세요.

이렇게 보이면 성공: Claude가 같은 파일을 여러 번에 걸쳐 읽거나, 전체를 읽었다고 말한 뒤 작업을 시작합니다.

문서에 따르면 v2.1.296 이상에서는 사용자가 파일 전체를 요청했을 때처럼 필요한 경우 allow_large: true로 전체 또는 긴 구간을 한 번에 읽을 수 있습니다. 이 경우 한도는 남은 컨텍스트 공간을 기준으로 정해집니다.

2단계. 반복되는 요구는 CLAUDE.md에 적습니다

매번 같은 말을 하기 번거롭다면 프로젝트 폴더의 CLAUDE.md에 한두 줄 추가합니다. 문서는 지시가 구체적이고 짧을수록 더 일관되게 지켜진다고 안내합니다. 예를 들면 다음과 같습니다.

## 파일 읽기 규칙
- 파일을 수정하기 전에 해당 파일 전체를 읽는다. 일부만 보고 수정하지 않는다.
- 파일이 길어 한 번에 다 읽히지 않으면 offset과 limit으로 끝까지 이어 읽는다.
- 전체를 읽지 못했다면 수정 전에 어디까지 읽었는지 먼저 알린다.

주의: "꼼꼼히 읽어"처럼 막연한 문장보다 위 예시처럼 행동이 보이는 문장이 낫습니다. 또 문서는 CLAUDE.md를 한 파일당 200줄 이하로 유지하길 권합니다. 길어지면 오히려 지켜지는 정도가 떨어질 수 있습니다.

위 도식의 세 가지는 강제력이 다릅니다.

프롬프트 — 이번 요청에만 적용되는 가장 간단한 방법입니다.
CLAUDE.md — 매 세션에 로드되지만, 문서에 따르면 시스템 프롬프트가 아니라 사용자 메시지로 전달되며 엄격한 준수가 보장되지는 않습니다.
훅 — 문서는 특정 시점에 반드시 실행돼야 하는 일이라면 CLAUDE.md 대신 훅으로 만들라고 안내합니다. 설정법은 공식 훅 가이드를 참고하세요.

3단계. 지침이 실제로 로드됐는지 확인합니다

세션에서 /context를 입력하고 Memory files 목록에 작성한 CLAUDE.md가 보이는지 확인합니다. 목록에 없다면 Claude는 그 파일을 볼 수 없습니다. 파일 자체는 편집기에서 직접 고치면 됩니다(2026년 11월 1일 기준 공식 문서에서 /memory는 자동 메모리 켜고 끄기 용도로 안내됩니다).

이렇게 보이면 성공: Memory files 아래에 방금 만든 CLAUDE.md가 나타납니다. 안 보이면 프로젝트 폴더 안에서 claude를 실행했는지 확인하세요. 하위 폴더의 CLAUDE.md는 시작 때가 아니라 필요할 때 로드되므로 이 목록에 보이지 않는 것이 정상입니다.

4단계. 파일이 너무 길다면 구조를 바꿉니다

찾는 대상이 정해져 있다면 — "전체 읽기" 대신 Grep(내용 검색 기능)으로 관련 부분을 찾게 하는 편이 낫습니다. 문서도 한도를 넘는 읽기에서 Grep으로 특정 내용을 검색하라고 안내합니다.
자주 쓰는 큰 파일이라면 — 기능별로 파일을 나누면 읽기도, 수정도 쉬워집니다.
한도 값을 바꾸고 싶다면 — 환경변수 CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS로 한 번에 읽는 한도를 조정할 수 있다고 문서에 적혀 있습니다. 다만 값을 키우면 컨텍스트를 더 쓰게 되므로 신중히 정하세요.

자주 막히는 지점

일부만 읽고 바로 고치지는 않나요? — 공식 문서 기준으로 Edit 도구는 같은 대화에서 그 파일을 읽은 뒤에만 수정할 수 있고, PARTIAL view로 잘린 읽기는 읽은 것으로 치지 않습니다. 즉 큰 파일을 앞부분만 받은 상태로는 수정이 적용되지 않습니다(문서는 최신 모델이 권한 확인이 필요 없는 파일을 읽지 않고 고칠 수 있는 예외도 함께 적고 있으니, 안전하게 1단계 문장을 함께 쓰세요).
지시가 서로 부딪히는지 모르겠다 — 세션에서 /doctor prompt-audit를 실행하면 오래된 모델 기준 지시, 없는 파일·명령 참조, 서로 충돌하는 파일을 찾아 수정안을 보여 줍니다(적용은 요청해야 반영).
CLAUDE.md에 적었는데 안 지킨다 — 공식 문서는 모호하거나 서로 충돌하는 지시에서 특히 준수가 흔들린다고 설명합니다. 여러 CLAUDE.md에 상반된 지시가 없는지 확인하고, 문장을 더 구체적으로 고치세요.
파일 전체를 읽혔더니 컨텍스트가 빨리 찬다 — 긴 파일을 통째로 읽으면 그만큼 작업 메모장을 차지합니다. 필요한 구간만 읽게 하는 편이 나을 때가 많습니다.
PARTIAL view 안내가 보인다 — 오류가 아니라 "첫 부분만 받았다"는 뜻입니다. "이어서 끝까지 읽어 주세요"라고 요청하세요.

자주 묻는 질문

Q. Claude Code가 파일을 항상 일부만 읽나요?
아니요, 한도를 넘는 큰 파일에서 나눠 읽는 방식이 적용됩니다. 문서에 따르면 한 번에 반환되는 양은 기본 25,000 토큰이고, 256 KB를 넘는 파일은 통째로 읽히지 않습니다.

Q. CLAUDE.md에 적으면 반드시 전체를 읽나요?
보장되지는 않습니다. 문서는 CLAUDE.md를 강제 설정이 아니라 문맥으로 취급하며, 반드시 지켜져야 하는 동작은 훅으로 만들라고 안내합니다.

Q. 지침이 로드됐는지는 어떻게 확인하나요?
/context를 실행해 Memory files 목록을 보면 됩니다. 목록에 없는 파일은 Claude가 볼 수 없습니다.

이 글의 수치·동작 설명은 2026년 11월 1일 공식 문서 기준입니다. 자세한 내용은 공식 문서의 How Claude remembers your project와 Tools reference에서 확인하실 수 있습니다. 버전에 따라 동작이 달라질 수 있으니 중요한 작업 전에는 화면의 안내를 함께 확인하세요.