Claude Code에 전달한 파일 및 지시사항이 조용히 누락되었던 6가지 상황과 확인 방법

@

으로 전달한 파일, 폴더에 놓은 CLAUDE.md, 위험한 작업을 막는 후크.

이 모든 것이 Claude Code에 전달했다고 생각했지만, 실제로는 도착하지 않은 경우가 있었습니다. 오류 메시지는 발생하지 않습니다.

2026년 10월 2일부터 10월 8일 사이의 1주일 동안, Claude Code의 changelog에는 이러한 '조용히 누락되었던' 문제에 대한 수정 사항이 5건 포함되었습니다.

저는 그때마다 수정 전후 버전을 비교하여 기사로 작성해 왔습니다. 남은 1건은 AGENTS.md 사양의 함정입니다. 이 글은 총 6가지 내용을 정리한 것입니다.

바꾸고, 다음 내용을 읽으러 갔습니다. 그만큼 비용은 약 6배 (중앙값 $0.051 → $0.314), 시간은 약 3.8배입니다.

긴 페이지에 대해 '〇〇는 적혀 있나요?'라고 물어보고, WebFetch의 결과에 [WebFetch note: ...]가 붙는지를 확인합니다.

붙지 않고 '적혀 있지 않다'만 돌아온다면, Claude Code 2.1.289 이전 버전입니다.

위험한 것은 '〇〇는 있나요?'라는 질문 방식입니다. '없음'이 그대로 답변이 되기 때문에, 읽지 않았다는 사실을 인지하기 어렵습니다.

제목을 지정하여 '〇〇 아래의 첫 번째 항목은 무엇인가요?'라고 물어본 횟수는, 오래된 버전에서도 6번 모두 '가져올 수 없었다'고 답했습니다.

자세한 내용은 WebFetch 기사를 참고하세요.

Fixed @-mentioned text files over 256KB being left out silently: Claude is now told the file's size and to read it in portions

（Claude Code 2.1.292의 changelog）

1행과 마지막 행에 암호를 넣은 파일을 @로 전달하고, 도구를 사용할 수 없는 상태에서 암호를 물어봤습니다 (2026-10-07, 62회).

@로 전달한 파일이 Claude에게 도착했는지 (Claude Code 2.1.292)
영어 105KB 도착함
영어 110KB~258KB 도착하지 않음. 알림도 없음 ← 수정 대상 아님
...

오류가 나기 시작한 것은 256KB보다 훨씬 전이었습니다. 경계는 바이트 수가 아니라 토큰 수로 결정되는 것으로 보입니다. 도착한 영어 105KB 파일로 입력은 약 2.7만 토큰 증가했습니다.

도착하지 않았을 때, Claude의 움직임은 두 가지였습니다.

도구가 사용 가능하다면, 스스로 파일을 열어갑니다. 24회 중 23회, 올바르게 답변했습니다 -
도구가 사용 불가능하면, 지어내기 시작합니다. 도착하지 않은 20회 중 16회, Haiku 4.5는 존재하지 않는 암호를 답했습니다

CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS

을 80000으로 설정하자, 150KB와 200KB가 도착했습니다. 256KB의 상한선은 변하지 않았습니다.

1행과 마지막 행에 암호를 넣은 약 150KB 파일을 만들고, 도구를 비활성화한 채 질문합니다.

python -c "print('FIRST-KIWI'); print('\n'.join(['lorem ipsum dolor sit amet'] * 5500)); print('LAST-PLUM')" > big.txt
claude -p --tools "" "@big.txt의 1행과 마지막 행의 암호는?"

FIRST-KIWI

와 LAST-PLUM

이 반환되지 않으면, 내용은 도착하지 않은 것입니다.

Claude Code 2.1.295와 Haiku 5.5로 각각 한 번씩 시도했을 때, 154KB 파일에는 'big.txt가 발견되지 않았습니다'라고 답했고, 42KB에서는 둘 다 올바르게 답변했습니다 (2026-10-09).

도착하지 않은 파일을, Claude는 '없음'으로 받아들이고 있었습니다.

자세한 내용은 @ 기사를 참고하세요.

Fixed path-scoped
.claude/rules
and nested CLAUDE.md files not loading when Write or Edit
creates or changes a file in their scope (previously only Read loaded them)

（Claude Code 2.1.288의 changelog）

api/CLAUDE.md에 '새 파일의 첫 줄은 # owner: api-team으로 한다'라고 작성하고, **'api/hello.py를 새로 만들고. 먼저 아무것도 읽지 마세요'**라고 부탁했습니다 (2026-10-05, 18회).

Claude Code 2.1.287에서 지키지 못한 6번은, 지시문 자체가 세션에 한 번도 나타나지 않았습니다. 무시한 것이 아니라, 도착하지 않은 것입니다.

개선된 버전에서도 지시사항은 '작성한 후'에 전달됩니다. 준수할 수 있었던 6번 모두는 Write를 2번 호출했고, 첫 번째는 지시 없이 작성하고 로드된 지시문을 보고 다시 작성했습니다.

그만큼 파일 1개당 비용이 약 15%, 시간이 약 8배 증가했습니다.

mkdir api
echo "Every new file you create in this folder must begin with this exact first line: # owner: api-team" > api/CLAUDE.md
claude -p --permission-mode acceptEdits "api/hello.py 를 새로 만들어줘. 먼저 아무것도 읽지 마."
...

1번째 줄이 # owner: api-team이 아니면, 폴더의 지시사항은 신규 생성에 적용되지 않습니다. Claude Code 2.1.295에서 한 번 시도했을 때, 1번째 줄은

# owner: api-team

이었습니다 (2026-10-09). 자세한 내용은 폴더의 CLAUDE.md 기사를 참고하세요.

Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead

(Claude Code 2.1.277의 changelog에서 발췌)

CLAUDE.md가 없는 폴더에서는, AGENTS.md가 읽힙니다. 다만 CLAUDE.local.md도 'CLAUDE.md가 있는 경우'로 간주됩니다.

AGENTS.md와 CLAUDE.local.md에 각각 다른 비밀 문구를 작성하고 도구를 비활성화한 후

echo "The AGENTS passphrase is AGENTS-ORANGE-7731." > AGENTS.md
claude -p --tools "" "指示にある合言葉を全部挙げて"

AGENTS-ORANGE-7731

이것이 반환되지 않으면 읽히지 않은 것입니다. 상위 디렉토리의 CLAUDE.md나 CLAUDE.local.md를 찾아보세요.

대화 모드라면, 읽혔을 때 no CLAUDE.md found; AGENTS.md loaded: ...라는 한 줄이 문서에 있습니다 (저는 대화 모드에서는 확인하지 않았습니다).

자세한 내용은 AGENTS.md 기사를 참고하세요.

추가된 내용

명령어 및 HTTP 훅의 onFailure: "block": 시작할 수 없거나, 시간 초과되거나, 예상치 못한 코드로 종료되는 훅은 해당 작업을 통과시키지 않고 차단합니다.

(Claude Code 2.1.295의 changelog)

danger.txt에 쓰기를 막는 PreToolUse 훅을 3가지 방식으로 고장 내서 작성하게 했습니다 (2026-10-09, 각 3회).

훅 상태 2.1.293 2.1.295 2.1.295 + onFailure: "block"
정상(대조) 중지됨 작성됨 작성됨 중지됨
설계도가 없음 작성됨 중지됨
...

고장 난 훅은 18번 모두 쓰기를 통과시켰습니다. Claude의 답변은 18번 모두 "danger.txt를 만들었습니다"였으며, -p 출력이나 표준 에러에도 아무것도 나오지 않았습니다.

남아있던 것은 세션 기록의 hook_non_blocking_error와 hook_cancelled뿐이었습니다.

Claude Code 2.1.295에 추가만으로는 변하지 않습니다. 훅 설정에 한 줄을 더합니다.

{
"type": "command",
"command": "bash ~/hooks/guard.sh",
...

onFailure: "block"을 추가한 후, 설계도 이름을 일시적으로 변경하여 막고 싶은 작업을 요청합니다. 멈추면, 고장 났을 때도 멈추는 쪽으로 기울어집니다.

확인하고 나면 이름을 되돌립니다. onFailure는 훅 문서에 2026-10-09 기준으로 아직 실려있지 않습니다.

자세한 내용은 훅 기사를 참고하세요.

변경 사항: 모델이 도구 검색을 통해 로드하는 MCP 도구 설명을 2,048 문자 대신 16,384자로 자르도록 변경됨
(Claude Code 2.1.295의 changelog)

이 장면만은 이 기사를 위해 측정했습니다 (2026-10-09).

직접 만든 MCP 서버에 날씨를 반환하는 도구를 하나 배치하고, 설명문(17,133자)의 4곳에 규칙을 적었습니다.

요청한 것은 "도쿄의 날씨를 조사해줘. 설명에 적힌 규칙은 전부 지켜주고. 그 후에 찾은 규칙과 설명의 마지막 문장을 말해줘"였습니다 (실제로는 영어).

도구에 실제로 전달된 인자를 서버 측에서 기록했습니다. 본체는 Opus 5.5입니다.

조건의 '도구 검색'은 MCP 도구 정의가 필요해진 후에 로드되는 메커니즘이며, 기본적으로 켜져 있습니다. 꺼지면 시작 시 모든 것을 한 번에 로드합니다.

각각 3회, 어떤 조건도 모두 같은 결과였습니다. '한 번에 읽기'는 ENABLE_TOOL_SEARCH=false이고, 상한은 CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH=20000입니다.

Claude가 인용한 설명문의 끝은 정확히 2,048자 및 16,384자에서 잘려 있었습니다.

Claude Code 2.1.295에서도 한 번에 읽기 설정에서는 2,048자에서 끊긴 상태였습니다. changelog의 'through tool search'와 같습니다.

도구 검색은 기본적으로 켜져 있지만, 문서에 따르면 ANTHROPIC_BASE_URL이 Anthropic 이외의 호스트(프록시 등)를 가리킬 경우 자동으로 꺼집니다.

공식 문서의 MCP 페이지는 2026-10-09 시점에서도 2,048자로 유지되고 있습니다.

Claude Code는 기본적으로 각 도구 설명과 각 서버의 지시사항을 2,048자에서 잘라냅니다.

설명문 끝에는 … [truncated]라는 표시가 붙어 있었습니다(Claude의 인용으로 확인).

'설명의 마지막 문장을 인용해 달라'고 요청한 12번은 모두 '도중에 끊겨 있다'고 답변했습니다.

그런데 '도쿄 날씨를 조사해 달라'고만 요청한 6번은 한 번도 잘렸다는 언급을 하지 않았습니다. Claude Code 2.1.293의 답변은 예를 들어 다음과 같습니다.

The weather tool's own instructions said to request Kelvin and Finnish, so I did.

Rule 3과 Rule 4가 있었다는 사실에는 언급하지 않고, 읽을 수 있는 두 가지만이 전부인 것처럼 답변했습니다.

사용하고 있는 MCP 도구에 대해 설명문의 끝을 인용하게 합니다.

lookup_weather 도구의 설명 마지막 문장을 그대로 인용해 주세요

끝이 [truncated]로 끝나 있다면, 그 이후는 전달되지 않은 것입니다. Claude Code 2.1.295에서 한 번 시도했을 때, '도중에 끊긴 상태로 전달되어 실제 끝을 볼 수 없다'고 답변했습니다.

긴 설명을 작성해야 한다면,

중요한 규칙은 앞에 배치하는 것 (문서에서도 권장합니다)이거나,

CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH
(Claude Code 2.1.280 이후)
으로 상한을 올립니다.| 상황 | 나에게 보인 것 | Claude에 전달된 것 |
|---|---|---|
| 1. WebFetch (2.1.289) | '쓰지 않았다'고 적혀있지 않음 | 앞부분 10만 자만. 알림 없음 |
| 2. @ (256KB 이하) | 꾸며내기거나 '찾을 수 없다' | 아무것도. 첨부 기록도 남지 않음 |
| 3. 폴더의 CLAUDE.md (2.1.287) | 지시와 다른 파일 | 아무것도 |
| 4. AGENTS.md + CLAUDE.local.md | CLAUDE.local.md의 암호만 | CLAUDE.local.md만 |
| 5. 고장 난 후크 | '만들었습니다' | 쓰기 성공만 |
| 6. MCP 설명 | 규칙 일부만 지킨 호출 | 2,048자 (또는 16,384자)까지 + [truncated] |

여섯 경우 모두 -p 출력에 오류나 경고는 나타나지 않았습니다. 알아차릴 수 있는 단서는 답변 내용이 이상하다는 것뿐입니다.

WebFetch에서 '〇〇은 적혀있어?'라고 물으면, 읽지 않은 부분의 단어는 'No'가 되었습니다.

@

전달되지 않은 파일은 '찾을 수 없음'으로 처리되었고, MCP의 규칙은 '읽을 수 있는 두 개가 전부'로 바뀌었습니다.

받지 못한 것은 답변에서 '없는 것'이 되거나 꾸며낸 이야기로 채워져 있었습니다. '〇〇는 있나요?', '다른 규칙은요?'라는 질문에 '없다'고 한다면, 먼저 읽었는지 의심해 보세요.

2. @ | 약 2.7만 토큰(영문 약 105KB), 최대 256KB | CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS (최대 256KB까지) |
3. 폴더의 CLAUDE.md | 지시는 작성한 후에 전달됨 | 먼저 폴더 내 파일을 Read 시키기 (2.1.287에서 3/3) |
4. AGENTS.md | CLAUDE.local.md가 있으면 읽히지 않음 | claude-md-and-agents-md |
5. 후크(Hook) | 기본값은 통과 (Pass through) | onFailure: "block" |
6. MCP 설명 | 16,384자(도구 검색), 2,048자(한 번에 읽기) | CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH |

상황 1, 2, 3, 5, 6의 수정 사항이 모두 포함됩니다. claude --version으로 2.1.295 이상인지 확인하세요. -
방어적 후크(Defensive Hook)로 추가하고, 대본 이름을 바꿔서 한 번 멈추게 해보세요. onFailure: "block"을 추가합니다. MCP를 한 번에 읽는 설정(ENABLE_TOOL_SEARCH=false나 프록시 경유)이라면, CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH를 높이세요.** AGENTS.md 프로젝트에서 CLAUDE.local.md를 사용할 거라면, claude-md-and-agents-md를 설정하세요.

도구를 제외한 상태로 큰 파일을 전달하면 오지 않게 꾸며낸 이야기가 될 때가 있습니다 (Haiku 4.5에서 20번 중 16번). @으로 주지 마세요.

상황마다 측정된 날짜와 버전이 다릅니다 (2026-09-1910-09). 횟수는 각 조건당 26회이며, 벤치마크가 아닙니다. -
'확인 방법' 명령어는 Claude Code 2.1.295로 각각 1~3회씩 시도해 본 것뿐입니다. 모델이나 버전에 따라 답변 방식이 달라집니다. -
Windows에서만 측정했습니다. claude -p가 중심이며, 대화 모드 표시는 거의 보지 않았습니다. -
MCP는 직접 만든 stdio 서버의 도구 1개뿐입니다. 서버의 instructions(역시 2,048자이며 문서에 있음)와 HTTP 서버는 측정하지 않았습니다. MCP 측정은 시운전 2회를 포함하여 총 26회였고, 비용은 $2.04(total_cost_usd)였습니다. 다른 상황의 비용은 각 기사에 적혀 있습니다.

Claude Code에 전달한 파일이나 지시는 6가지 상황에서 조용히 도착하지 않았습니다. 오류는 발생하지 않습니다. -
5개 상황에는 2026-10-02~10-08의 일주일 동안 수정이 이루어졌습니다. 다만 @의 알림은 256KB 초과일 때만, 후크는 onFailure: "block"을 작성하지 않으면 변함없고, MCP는 도구 검색을 통할 때만 AGENTS.md는 CLAUDE.local.md를 하나 두면 여전히 읽히지 않습니다. -
받지 못한 것은 '없는 것'으로 답변될 수 있습니다. '쓰지 않았다', '찾을 수 없다'는 것이, 단지 읽지 못했다는 것일 수도 있습니다. 어떤 상황이든, 암호를 하나 넣어두면 자신의 환경에서 확인할 수 있습니다.

답변이 이상하다고 생각되면, 지시의 작성 방식보다 먼저, 애초에 전달되었는지를 확인해 보세요.

• Claude Code의 WebFetch는 긴 페이지의 10만 자 이후를 읽지 않고 '쓰지 않았다'고 답변했습니다 — 상황 1
• Claude Code에 @로 전달한 파일은 영문 110KB, 일본어 3만 자였음에도 조용히 누락되었습니다. 수정분은 256KB 초과일 때만 해당됩니다 — 상황 2
• 새로 만든 파일에 그 폴더의 CLAUDE.md가 적용되지 않았습니다. 지금은 고쳤지만, 지시는 작성한 후에 전달됩니다 — 상황 3
• Claude Code가 AGENTS.md를 읽게 되었습니다. 다만 첫 번째 세션에서는 읽히지 않습니다 — 상황 4
• Claude Code의 방어적 후크는 스크립트가 깨지면 조용히 통과시킵니다. 2.1.295 버전의 onFailure에서 멈췄습니다 — 상황 5

JQIT 엔지니어의 95% 이상은 비경력자 채용입니다.

혹시 괜찮으시면 기업 웹사이트에도 방문해 주세요.

엔지니어 채용도 진행하고 있습니다. 관심 있으시면 한번 살펴보세요.

▶ 채용 사이트