Claude Code API 호출 다 까봤음 ㄹㅇ

Claude Code Agent SDK로 서브디렉토리 CLAUDE.md의 작동 방식을 프록시를 만들어 API 호출을 추적하며 분석

아니 나 Claude Code Agent SDK 쓰면서 서브디렉토리 CLAUDE.md 파일 계속 넣었거든? src/ 폴더에 "타입 힌트 필수" 이런 거 넣어놓으면 잘 적용되긴 하는데... 대체 어떻게 작동하는 건지 도저히 모르겠어서 결국 프록시 만들어서 API 호출을 전부 추적해봤음 😤

핵심 발견들

1. Read 도구만 CLAUDE.md를 트리거함 Bash로 cat src/file.py 해도, Glob으로 파일 검색해도, Write로 파일 써도 서브디렉토리 CLAUDE.md는 절대 안 읽어와. 오직 Read 도구만 트리거함.

| Read → ✓ 로드됨 | | Bash → ✗ 무시됨 | | Glob → ✗ 무시됨 | | Write → ✗ 무시됨 |

즉 에이전트가 파일 안 읽고 바로 코드 쓰면? 서브디렉토리 지시사항 완전 무시하는 거임 🫠

2. 별도 메시지가 아니라 파일 내용 끝에 붙음 시스템 프롬프트에 추가될 줄 알았는데 아님. 파일 내용 뒤에 system-reminder 태그로 그냥 연결됨. 모델 입장에서는 파일 끝에 추가 내용이 있는 것처럼 보이는 거지.

3. 한번 들어가면 세션 끝까지 유지됨

4. 디렉토리당 세션당 1번만 주입됨 src/ 에서 파일 10개 읽어도 CLAUDE.md는 딱 1번만 주입. 중복 걱정 안 해도 됨 ✌️

솔직히 이거 문서에 적어놨으면 프록시 안 만들어도 됐을 텐데... 근데 덕분에 확실히 알게 됐으니 뭐 😅