Claude Code 2.1.287 및 2.1.289의 CLAUDE.md 적용 방식 비교

Claude Code 2.1.288 (2026-10-02)의 changelog에는 다음과 같이 적혀 있습니다.

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.md와 경로 지정 규칙은 이전에는 Read했을 때만 읽혔습니다.

즉, 새로운 파일 생성 작업만으로는 해당 폴더의 지시가 전달되지 않았던 것입니다.

18번 측정했습니다.

지시 위치 Claude Code 2.1.287 Claude Code 2.1.289
폴더의 CLAUDE.md 0/3 준수 3/3 준수
경로 지정 규칙 0/3 3/3
...

검증 환경: Windows 10 / Claude Code 2.1.287 및 2.1.289를 격리 도입 /

claude -p
/
--output-format stream-json
/ 모든 실행 설정 디렉터리 일회용(콜드) / 측정은 2026-10-05

공식 설명 페이지(memory)는 두 개의 절에서 다른 내용을 작성하고 있습니다 (2026-10-05 조회).

서브 폴더의 CLAUDE.md 절:

Files in subdirectories load on demand when Claude reads files in those directories.

경로 지정 규칙 절:

Path-scoped rules trigger when Claude uses the Read, Write, or Edit tool on a file matching the pattern,

not on every tool use.

규칙 절에서는 'Write에서도 작동한다'고 작성되어 있었습니다. changelog는 '이전에는 Read만 그랬다'고 인정하고 있으므로, Claude Code 2.1.287까지는 쓰여진 대로 작동하지 않았던 것입니다.

서브 폴더 api/
에, 한눈에 준수 여부를 알 수 있는 지시를 놓았습니다.

# Rules for this folder
Every new file you create in this folder must begin with this exact first line:
# owner: api-team

경로 지정 규칙의 경우에는 .claude/rules/api.md의 paths:에 api/**를 지정하고,

첫 줄을 # reviewed-by: rules-file로 했습니다.

요청하는 것은 'api/hello.py를 새로 만들어줘. 먼저 아무것도 읽지 마.' 뿐입니다.
판단은 생성된 파일의 첫 줄입니다. 툴 호출은 stream-json으로 모두 기록하고, '신규 생성만'의 경우에 Read를 사용하지 않았음을 한 번씩 확인했습니다.

각 3회씩.

Claude Code 2.1.287에서는, 신규 생성만 하는 경우 6회 모두 지시가 작동하지 않았습니다.

같은 버전이라도, 먼저 폴더 내 파일을 Read하게 하면 3회 모두 준수했습니다. 전달되는 여부는 Read에 달려 있었습니다.

읽혔는데 무시된 것이 아닙니다. 전체 검색 기록을 살펴보면, Claude Code 2.1.287의 신규 생성만으로는 6회 동안 지침이 한 번도 나타나지 않았습니다.

반면, Claude Code 2.1.289에서는 6회 모두 나타났습니다.

지시를 두지 않은 대조군에서는 첫 줄이 붙지 않으므로, 모델이 임의로 작성한 것도 아닙니다.

Claude Code 2.1.289에서 지켜진 6회는 모두 Write를 2번 호출했습니다. 내용을 나열하면 다음과 같습니다.

1차 Write 첫 줄: def hello(): ← 지시가 아직 없음
(여기서 api/CLAUDE.md가 로드됩니다)
2차 Write 첫 줄: # owner: api-team ← 다시 작성됨

Claude 역시 6회 중 5회, 마지막 보고에서 이 점을 언급했습니다. 예를 들면 다음과 같습니다.

After I made the file, the

api/CLAUDE.md

rules loaded.

지시는 '쓰기 전'이 아니라 '쓴 후'에 도착합니다. 작성한 것이 계기가 되어 로드되고,

Claude가 그것을 보고 다시 작성합니다.

그 비용도 발생합니다. 각 3회 중앙값 기준으로,

파일 하나당 비용이 약 15%, 시간이 약 8할 증가했습니다.

측정한 것은 2026-10-05의 하루, 각 3회입니다. 총 18번 모두 일관했지만, 벤치마크는 아닙니다 -
만든 것은 작은 파일 하나뿐입니다. 긴 파일이나 한 번에 여러 개를 만들 경우 반드시 다시 작성할지는 알 수 없습니다 -
Edit은 측정하지 않았습니다. 기존 파일 변경 시 같은 일이 발생하는지는 미확인입니다 -
Claude Code 2.1.288 단독으로는 측정하지 않았습니다. 비교한 것은 2.1.287과 2.1.289입니다 문서의 규칙 섹션이 언제부터 'Write에서도 유효'라고 쓰여 있었는지는 확인할 수 없습니다-
폴더 바깥의 CLAUDE.md (프로젝트 직하)는 시작 시 읽힌다고 문서에 있지만,

이번에는 측정하지 않았습니다

Claude Code 2.1.287까지는 새로 만든 파일에, 그 폴더의 CLAUDE.md도 경로 지정 규칙도 적용되지 않았습니다-
먼저 그 폴더의 파일을 Read 했더라면 적용되었을 것입니다. 계기는 Read뿐이었습니다 -
문서의 규칙 섹션은 'Write에서도 유효'라고 쓰여 있었습니다. 실제로는 Claude Code 2.1.288까지는 효과가 없었습니다 -
수정된 버전이라도, 지시는 작성 후에 도착합니다. Claude는 한 번 작성한 후, 지시를 보고 다시 작성하는 그만큼 파일 하나당 비용이 약 15%·시간이 약 8할 증가했습니다

폴더별 지시에 의존한다면, 먼저 Claude Code 2.1.288 이상으로 올리는 것이 우선입니다.

그 위에, 신규 생성 시 첫 번째가 지시 없이 작성된다는 점을 기억해 두는 것이 좋을 것 같습니다.

Claude Code가 AGENTS.md를 읽게 되었다. 다만 1차 세션에서는 읽히지 않는다 — 지침서가 '언제' 읽히는지 측정한 회수

• Claude Code의 서브 에이전트에도 CLAUDE.md는 전부 전달된다. 제외 설정이 가능했다 — 지침서가 '어디까지' 도달하는지 측정한 회수

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

괜찮으시면 기업 사이트에도 놀러 오세요.

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

▶ 채용 사이트