Claude Code의 VS Code 확장 기능을 사용하던 중, 프로젝트에 작성한 CLAUDE.md 규칙을 갑자기 지키지 않게 되었습니다.
CLAUDE.md의 내용이나 위치를 변경하지 않았습니다. 그런데 확장 기능이 업데이트된 이후부터는, 제가 작성해 둔 워크플로우를 무시하고 임의의 방식으로 작업을 진행하기 시작했습니다.
조사한 결과, 원인은 CLAUDE.md 작성 방식에 있는 것이 아니었습니다. 확장 기능 v2.1.323에서 도입된 '폴더 신뢰(Folder Trust)' 확인 과정 때문에, 애초에 CLAUDE.md가 로드되지 않았던 것이었습니다.
결론
- VS Code 확장 v2.1.323부터는 폴더를 '신뢰하지 않음'으로 판단할 경우, 프로젝트의 CLAUDE.md, settings, MCP를 로드하지 않고 실행되게 되었습니다.
- CHANGELOG와 확인 다이얼로그에는 'settings와 MCP가 사용되지 않는다'고만 명시되어 있을 뿐, CLAUDE.md도 제외된다는 내용은 명확히 적혀 있지 않았습니다.
- 확장 기능이 신뢰 여부를 판단하는 것은 창(Window)을 열었을 때뿐입니다. 제 환경에서는 'Developer: Reload Window'를 통해 재판단하게 하자 문제가 해결되었습니다. 단순히 새로운 채팅을 시작하는 것만으로는 해결되지 않았습니다.
본 글에서는 다음 세 가지 내용을 순서대로 다룹니다.
-
원인 분리 방법 (세션 로그 확인 방법)
-
문제의 메커니즘
-
대처법
-
macOS 환경에서
-
Claude Code VS Code 확장 v2.1.327(v2.1.322까지는 문제없음)
-
작업 폴더 직하단에
CLAUDE.md
을 배치했을 경우
-
CLAUDE.md에 작성된 절차를 따르지 않습니다.
-
본인(Claude)에게 물어보면, '받은 지침에 CLAUDE.md의 내용은 포함되어 있지 않다'고 답변합니다.
-
사용자 레벨의 스킬이나 auto memory(MEMORY.md)는 이전과 같이 작동하고 있습니다.
Claude Code는 세션 기록을 ~/.claude/projects/<폴더명 변환값>/*.jsonl에 저장합니다. CLAUDE.md가 자동으로 로드된 세션에는 Contents of <경로>/CLAUDE.md (project instructions, checked into the codebase)라는 문자열이 남아 있습니다.
이에 저는 세션별로 '이 문자열의 존재 여부'와 'Claude Code 버전'을 나란히 비교해 보았습니다.
cd ~/.claude/projects/<대상폴더>
for f in $(ls -t *.jsonl | head -15); do
loaded=$(grep -c 'CLAUDE.md (project instructions, checked into' "$f")
...
대화 과정에서 이 문자열 자체를 인용하는 세션도 카운트되기 때문에, 그 점만 유의해 주십시오.
결과는 버전별로 깔끔하게 나뉘었습니다.
| 버전 | CLAUDE.md 자동 로드 여부 |
|---|
| v2.1.319 / v2.1.322 | 모든 세션에서 로드됨 |
| v2.1.325 / v2.1.327 | 한 번도 로드되지 않음 |
확장 기능에는 CLI 본체가 포함되어 있습니다. 같은 버전의 CLI를 같은 폴더에서 실행하여 CLAUDE.md가 로드되는지 확인했습니다.
# 확장 기능에 포함된 CLI (경로는 환경에 맞게 변경)
CLAUDE=~/.vscode/extensions/anthropic.claude-code-2.1.327-darwin-arm64/resources/native-binary/claude
cd <대상폴더>
...
결과는 '포함되어 있음'이었습니다. CLI에서는 로드되지만, VS Code 확장 기능에서만 로드되지 않는 상황인 것입니다.
VS Code의 확장 로그(명령 팔레트에서 'Claude Code: Show Logs')에 다음 줄이 나타났습니다.
[info] /path/to/project에서 폴더의 설정 소스 없이 프로세스를 시작합니다: Claude Code는 해당 프로젝트에 대한 신뢰 기록이 없습니다
[warning] /path/to/project에서 폴더의 설정 소스가 사용되지 않고 있습니다: Claude Code가 이에 대한 신뢰를 부여받지 못했습니다
CHANGELOG의 v2.1.323에는 다음 내용이 기재되어 있습니다.
[VSCode] 아직 신뢰하지 않은 폴더에서 첫 세션을 시작하기 전에 Claude Code 신뢰 프롬프트를 추가했습니다. 거부할 경우, 해당 폴더의 설정과 MCP 서버는 사용되지 않습니다.
확장 기능 코드(v2.1.327의 extension.js)를 살펴보면 작동 방식은 다음과 같았습니다. 관련 부분만 압축된 코드를 추출하여 정리했습니다. 변수명은 버전에 따라 달라집니다.
var n9e=["user","project","local"], r9e=["user"], zJ={CLAUDE_CODE_IGNORE_PERSISTED_TRUST:"1"};
// ...
settingSources: [...C.kind==="trusted" ? n9e : r9e]
- 신뢰된 폴더의 경우:
settingSources: ["user", "project", "local"]로 시작합니다.
- 신뢰되지 않은 폴더의 경우:
settingSources: ["user"]만으로 시작하며, 환경 변수 CLAUDE_CODE_IGNORE_PERSISTED_TRUST=1을 추가합니다.
Agent SDK 문서에 따르면, 프로젝트의 CLAUDE.md(<cwd>/CLAUDE.md 또는 <cwd>/.claude/CLAUDE.md)가 로드되는 것은 settingSources에 `
)
- 도구를 사용하지 않고 "CLAUDE.md의 첫 번째 제목은 무엇인가요?"라고 물으면 올바르게 답변합니다.
- 확장 로그에
without the folder's setting sources가 더 이상 나타나지 않았습니다.
다이얼로그가 표시되지 않은 것은 리로드 시점에 ~/.claude.json에 이 폴더의 신뢰 기록(hasTrustDialogAccepted: true)이 이미 존재했기 때문이라고 생각합니다. 실제로 이 기록이 붙은 후에도, 리로드하기 전 창에서는 여전히 신뢰되지 않은 상태로 시작했습니다. 기록이 언제 생성되었는지는 특정할 수 없습니다.
~/.claude.json에 hasTrustDialogAccepted: true로 설정되어 있음에도 불구하고, "신뢰를 확인할 수 없음"으로 판단되는 보고도 있습니다(issue #110741. 2.1.323 버전 이후의 일반 VS Code에서도 발생한다는 댓글이 있습니다).
이 경우의 회피책으로, 세션 시작 시 CLAUDE.md의 내용을 전달하는 훅(hook)을 만들었습니다. 신뢰되지 않은 동안에는 프로젝트의 .claude/settings.json도 로드되지 않기 때문에, 훅은 **사용자 설정(~/.claude/settings.json)**에 배치합니다.
~/.claude/settings.json
(기존 설정에 추가):
{
"hooks": {
"SessionStart": [
...
훅 주의사항
additionalContext가 1만 자를 초과하면 내용은 파일에 쓰여집니다. Claude에 전달되는 것은 처음 2,000자의 미리보기와 파일 경로뿐입니다. 긴 CLAUDE.md에는 적합하지 않습니다. - 이 훅으로 보완할 수 있는 것은 CLAUDE.md 뿐입니다. 프로젝트의 settings나 MCP 서버는 로드되지 않은 상태이므로, 근본적으로는 1번 조치가 필요합니다.
chmod +x를 잊지 마세요.
훅을 추가한 후, 리로드하기 전 신뢰되지 않은 창에서 새로운 세션을 시작했을 때 훅이 작동했습니다. 세션 기록에는 훅이 전달한 CLAUDE.md의 내용이 남아 있었고, 원래 로드된 내용은 0건이었습니다. 리로드하여 신뢰 상태가 된 후에는 훅은 아무것도 하지 않았습니다.
단독으로 다음 3가지 패턴을 테스트했습니다.