Claude Code가 이제 AGENTS.md를 읽지만, CLAUDE.md가 없을 때만 가능합니다 — 이를 조용히 취소하는 세 가지 파일 (2026)

릴리스 노트는 단 한 줄의 글머리 기호로 되어 있습니다. 그 뒤에 있는 "Claude가 프로젝트를 기억하는 방법"이라는 제목의 문서 페이지에 구체적인 메커니즘이 담겨 있으며, 다음과 같은 범위 설명으로 시작합니다. "Claude Code는 AGENTS.md를 프로젝트 지침으로 읽을 수 있으므로, 다른 코딩 에이전트를 위해 이미 설정된 저장소는 CLAUDE.md를 추가하거나 임포트 또는 설정을 하지 않고도 작동합니다."

그다음에는 전체 이야기를 압축한 3행짜리 표가 나옵니다. 작업 디렉터리나 그 상위에 "AGENTS.md가 있고 CLAUDE.md나 CLAUDE.local.md가 없는" 저장소는 "귀하의 AGENTS.md"를 가져옵니다. 작업 디렉터리나 그 상위에 "AGENTS.md가 있고 CLAUDE.md 또는 CLAUDE.local.md가 있는" 저장소는 "귀하의 CLAUDE.md 파일만" 가져옵니다. 그리고 "이미 AGENTS.md를 임포트하는 CLAUDE.md"가 있는 저장소는 "임포트를 통해 AGENTS.md가 포함된 귀하의 CLAUDE.md"를 가져옵니다.

판단 규칙은 별도로 명시되어 있으며, 이는 개인 노트에 복사해 둘 만한 가치가 있는 부분입니다. "영향을 미치므로 Claude가 AGENTS.md 대신 읽게 만드는" 파일은 "작업 디렉터리 또는 그 상위 디렉터리에 있는 CLAUDE.md, .claude/CLAUDE.md 또는 CLAUDE.local.md"입니다. "영향을 미치지 않으며 AGENTS.md와 함께 계속 로드되는" 파일은 "귀하의 ~/.claude/CLAUDE.md, 조직의 관리형 CLAUDE.md 및 .claude/rules/ 파일"입니다.

Anthropic은 또한 자체 노트에서 이러한 함정을 평이한 언어로 기록해 두었습니다. "CLAUDE.local.md가 영향을 미치기 때문에, AGENTS.md에 의존하는 프로젝트에서 커밋되지 않은 자신만의 지침을 유지하기 위해 이를 추가하면 Claude가 AGENTS.md를 읽지 못하게 됩니다."

그리고 확인 방법이 있습니다. 방해하는 파일이 없을 때, 문서에 따르면 세션 시작 시 Claude는 "작업 디렉터리와 그 상위 디렉터리에 있는 모든 AGENTS.md 및 .claude/AGENTS.md"를 읽으며, "대화형 세션의 대화 중에 no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md와 같은 줄이 표시됩니다."

같은 주에 동일한 형태의 두 번째 변경 사항이 있었습니다. 하루 전에 발표된 버전 2.1.275에서는 "로그인된 claude.ai 계정에서 활성화된 스킬 및 플러그인을 터미널 세션에 동기화하는 기능이 추가되었습니다. syncClaudeAiSkills: false 또는 syncClaudeAiPlugins: false로 옵트아웃할 수 있습니다." 이 두 가지를 함께 읽으면 패턴이 명확해집니다. 세션이 시작할 때 로드되는 대상이 저장소의 파일을 아무도 수정하지 않았음에도 불구하고 두 번이나 변경된 것입니다.

이것은 파일의 내용이 아니라 어떤 파일이 권한을 갖는지를 바꿉니다. 저장소에 AGENTS.md만 있는 경우 동작이 개선되므로 아무것도 할 필요가 없습니다. 두 파일이 모두 있는 경우 아무것도 바뀌지 않습니다. Claude는 항상 읽던 CLAUDE.md를 읽고, 그 옆에 있는 AGENTS.md는 여전히 다른 도구들에만 전달됩니다. 가장 놀라게 될 사람들은 가장 많은 작업을 수행한 사람들일 것입니다. 두 세계를 동기화 상태로 유지하기 위해 임포트나 심볼릭 링크를 구축한 사람은 이제 하나의 작업을 수행하는 두 개의 메커니즘을 갖게 되었습니다.

파일이 파싱되는 방식은 변경되지 않습니다. 각 AGENTS.md 내부에서 "@path 임포트가 확장되고, claudeMdExcludes 패턴이 적용되며, 프로젝트 지침을 건너뛰는 서브에이전트는 이 파일들도 건너뜁니다."

확인 방법은 변경됩니다. 설정을 통해 읽은 AGENTS.md는 문서화된 네 가지 위치에서 CLAUDE.md와 다르게 동작합니다. /memory 및 /context 내의 Memory files 목록에서 CLAUDE.md는 "목록에 표시"되는 반면, AGENTS.md는 "목록에 표시되지 않음. Claude가 이를 읽었는지 확인하려면 기본값 아래의 AGENTS.md loaded 라인을 찾거나 Claude에게 프로젝트 지침이 무엇인지 물어보십시오."라고 나옵니다. InstructionsLoaded 훅은 한쪽에서는 "실행"되고 다른 쪽에서는 "실행되지 않음"으로 작동하지만, "CLAUDE.md가 임포트하거나 심볼릭 링크로 연결한 AGENTS.md에 대해서는 평소와 같이 실행됩니다." --add-dir로 추가된 디렉터리는 CLAUDE.md를 로드하지만 AGENTS.md는 로드하지 않습니다. 그리고 작업 디렉터리 외부 파일의 @path 임포트는 "이 프로젝트에 대해 외부 임포트를 이미 승인한 경우에만 프롬프트 없이 로드됩니다."

또한 이 기능이 모든 곳에 한 번에 적용되는 것은 아닙니다. 문서에는 "Claude가 CLAUDE.md 파일만 읽고, /config 설정 패널에 Project instructions가 나타나지 않는" 세션들이 나열되어 있습니다. 여기에는 v2.1.277 이전 버전, "Amazon Bedrock 또는 다른 서드파티 제공업체를 사용하거나 텔레메트리를 비활성화하여 Anthropic으로부터 기능 플래그를 가져오지 않는" 세션, "설치 또는 업그레이드 후 첫 번째 세션", 그리고 "귀하 또는 귀하의 조직이 disableAllHooks 또는 allowManagedHooksOnly를 설정했거나 내장된 agents-md 플러그인을 비활성화한" 설정이 포함됩니다.

"이제 CLAUDE.md를 삭제해도 되겠군요." 저장소에 Claude 전용 설정이 없는 경우에만 해당됩니다. 문서에서는 "일부 세션이 AGENTS.md를 직접 로드할 수 없는 경우" CLAUDE.md를 유지하도록 설명하고 있으며, 이는 가상의 상황이 아닌 실제 발생하는 시나리오입니다.

"이제부터 두 파일이 모두 읽히겠네요." 네 가지 Project instructions 값 중 하나에서만 그렇습니다. 기본값인 claude-md-or-agents-md는 "귀하의 CLAUDE.md 파일, 또는 작업 디렉터리나 그 상위에 CLAUDE.md나 CLAUDE.local.md가 없을 때 귀하의 AGENTS.md 파일"을 읽습니다. 둘 다 읽는 것은 claude-md-and-agents-md이며, 이는 "각 디렉터리의 CLAUDE.md 파일을 먼저 읽고 그 뒤에 AGENTS.md를 함께" 읽습니다.

"제 임포트 설정은 이제 중복되니 제거해야겠네요." 한 가지 설정에 대해 문서는 정반대로 말합니다. "@AGENTS.md를 포함하는 CLAUDE.md"의 경우 "그대로 두어도 됩니다. 어떤 Project instructions 값을 사용하든 임포트를 유지한다고 해서 Claude가 AGENTS.md를 두 번 읽지는 않습니다."라고 설명합니다.

"제 설정에는 중복되는 것이 없습니다." 하나는 중복됩니다. "AGENTS.md를 출력하는 SessionStart 훅"의 경우, 가이드는 "제거하십시오. Claude가 AGENTS.md를 직접 읽게 되면, 해당 훅은 컨텍스트에 두 번째 복사본을 추가하게 됩니다."라고 안내합니다.

"내가 작성한 파일이 곧 컨텍스트입니다." 지침 파일은 상시 브리핑 자료이며, 장기 프로젝트를 망치는 질문들은 대개 규칙보다는 결정 사항에 관한 것입니다. 예를 들어 지난 6월에 두 가지 접근 방식 중 어떤 것으로 결정했는지, 그리고 그 이유는 무엇인지와 같은 것들입니다. 이러한 기록은 시작할 때 에이전트가 읽는 파일과 분리하는 것이 좋습니다. 이에 대한 논지는 왜 긴 컨텍스트가 메모리가 아닌가에서 다루고 있습니다.

1단계: 기억에 의존하지 말고, 영향을 미치는 파일들을 인벤토리화하기

이 검사는 프로젝트 루트뿐만 아니라 상위 디렉터리로 거슬러 올라가며 실행됩니다. 작업 디렉터리와 그 상위의 모든 디렉터리를 탐색하며 정확히 세 가지 이름(CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md)을 찾으십시오. 이 경로 상에 단 하나라도 존재하면 Claude는 CLAUDE.md 파일만 읽게 됩니다.

"읽지 않음"으로 문서화된 두 가지 이름도 살펴볼 가치가 있습니다. 바로 AGENTS.local.md, AGENTS.override.md 또는 .agents/ 디렉터리 아래의 모든 파일입니다. 누군가 개인 오버라이드 설정을 이 중 하나로 분리해 두었다면, 그것은 Claude Code에 전달되지 않았으며 앞으로도 전달되지 않을 것입니다.

개인 및 조직 수준의 파일은 어느 쪽이든 안전합니다. 이들은 "영향을 미치지 않으며 AGENTS.md와 함께 계속 로드"되므로, 자신만의 습관으로 가득 찬 ~/.claude/CLAUDE.md가 저장소의 파일을 취소하는 것은 아닙니다.

2단계: 의도적으로 Project instructions 값 선택하기

/config를 입력하고 기본값을 그대로 상속받기보다 Project instructions를 의도적으로 설정하십시오. 네 가지 값은 네 가지 실제 상황에 매핑됩니다. 하나의 파일이 명확히 프로젝트의 지침일 때는 claude-md-or-agents-md, 공유 파일에 Claude 전용 추가 사항을 더하고 싶을 때(특히 CLAUDE.local.md를 유지할 때)는 claude-md-and-agents-md, 프로젝트가 분기되어 공유 파일이 다른 도구 전용일 때는 claude-md, 그리고 시작 시 "조직의 관리형 CLAUDE.md 및 자동 메모리만" 로드하는 managed-only가 있습니다.

이 값은 패널 대신 설정 파일 내의 pluginConfigs에 있는 내장 agents-md 플러그인 ID 아래, 사용자 설정 파일, --settings 파일 또는 관리형 설정에 위치할 수도 있습니다. 팀에게 중요한 제약 조건이 하나 있습니다. "Claude Code는 프로젝트 및 로컬 설정 파일에서 이 설정을 무시합니다." 즉, 저장소 내부에서 동료들에게 이 선택을 전달할 수 없으므로, 대신 온보딩 노트에 포함해야 합니다. 어떤 경로를 선택하든 "변경 사항은 다음 메시지를 보낼 때부터, 그리고 모든 새 세션에 적용됩니다."

3단계: 로드 확인 후, 중복되는 임시 해결책만 제거하기

세션을 시작하고 해당 라인을 찾으십시오. 방해하는 파일이 없는 기본값 상태에서 대화에는 no CLAUDE.md found; AGENTS.md loaded: 뒤에 경로가 표시됩니다. claude-md-and-agents-md를 사용 중이거나 임포트를 유지한 경우, /context를 실행하여 Memory files 아래에 CLAUDE.md가 나타나는지 확인하십시오. 이는 임포트 및 심볼릭 링크 경로에 대해 문서화된 확인 방법입니다.

그런 다음 직관이 아닌 유형별로 기존 임시 해결책을 처리하십시오. @AGENTS.md 임포트는 그대로 두십시오. Claude에게 말로만 다른 파일을 읽으라고 지시하는 CLAUDE.md는 삭제하십시오. "Claude는 파일을 열기로 결정한 경우에만 AGENTS.md를 보기 때문"입니다. 심볼릭 링크는 "아무것도 하지 않거나 심볼릭 링크를 삭제"하십시오. 어느 쪽이든 Claude는 콘텐츠를 한 번만 읽습니다. 파일을 출력하는 SessionStart 훅은 제거해야 합니다.

심볼릭 링크 경로를 처음 선택하는 경우 두 가지 제약 조건이 적용됩니다. Edit 및 Write 도구는 "심볼릭 링크를 통한 쓰기를 거부"하며, 이 거부는 "Claude가 링크의 대상인 AGENTS.md를 대신 편집하도록 안내"합니다. 그리고 Windows에서는 "심볼릭 링크를 생성하려면 관리자 권한 또는 개발자 모드가 필요하며, core.symlinks가 활성화되어 있지 않으면 Git은 커밋된 심볼릭 링크를 일반 텍스트 파일로 체크아웃합니다."

지침 파일은 "여기서 어떻게 일해야 하는가"에 대한 답을 제공합니다. 하지만 "우리가 무엇을, 언제 결정했는가"를 담기에는 적절한 곳이 아닙니다. 두 개의 파일 이름과 설정을 동시에 다루어야 하는 상황이 되면 그 차이는 더욱 극명해집니다. MemoryLake에 의도적으로 항목을 기록하는 별도의 저장소를 사용하면, 이번 주에 어떤 파일 이름이 선택되었는지와 무관하게 결정 사항과 그 이유를 한곳에 보관할 수 있습니다. 항목은 본인의 언어로 직접 작성합니다. Anthropic의 파일이나 설정에서 아무것도 읽거나 쓰거나 삭제하지 않습니다.

1단계: API 키 생성하기

로그인한 후 워크스페이스 설정에서 API 키를 생성하십시오. 이는 에이전트와 연동 기능이 사용하는 인증 정보이므로, 다른 작업을 시작하기 전에 먼저 생성해 두십시오.

2단계: 첫 번째 메모리 업로드하기

계속해서 다시 설명해야 하는 항목들부터 시작하십시오. 아키텍처 결정 사항, 한때 논쟁을 벌였던 규칙들, 파일 내에서 임의적으로 보이는 제약 조건 뒤에 숨겨진 이유 등이 이에 해당합니다. 긴 문서 대신 짧고 독립적인 노트로 작성하여 각각 개별적으로 검색할 수 있도록 하십시오.

3단계: AI 및 에이전트 연결하기

실제로 사용하는 어시스턴트와 코딩 에이전트를 연결하십시오. 그러면 상시 저장소가 이번 달에 각 도구가 선호하는 지침 파일 이름과 무관하게 여러 도구를 거쳐 여러분과 함께 이동합니다.

온보딩 방식이 바뀝니다. 이전에는 "CLAUDE.md를 읽으십시오"가 완전한 지침이었습니다. 이제는 동료가 동일한 저장소를 복제하고 동일한 버전을 실행하더라도, 이전 작업에서 남겨둔 CLAUDE.local.md 때문에 서로 다른 프로젝트 지침을 받게 될 수 있습니다. 오류가 발생하지는 않지만, 답변의 정보 수준이 낮아질 수 있습니다. 저장소에 이 설정을 담을 수 없으므로, 예상되는 Project instructions 값을 설정 노트에 기록해 두십시오.

"모든 도구를 위한 하나의 파일"이 의미하는 바가 바뀝니다. 공유 파일이라는 아이디어는 여전히 좋지만, 이를 둘러싼 규칙은 도구마다 다릅니다. 예를 들어 Kiro의 가이드 문서에는 "AGENTS.md 파일은 포함 모드를 지원하지 않으며 항상 포함됩니다"라고 명시되어 있습니다. 동일한 파일 이름이지만 로딩 계약이 다릅니다. 여러 에이전트에 걸쳐 하나의 파일을 유지하는 경우, 파일은 공유되지만 동작은 공유되지 않으며, 이는 왜 에이전트가 지침 파일을 무시하는가에서 설명한 것과 동일한 격차입니다.

마이그레이션 노트의 가치가 바뀝니다. CLAUDE.md를 AGENTS.md로 마이그레이션하는 방법의 경로를 따라 이미 콘텐츠를 AGENTS.md로 이동했다면 이동 자체는 유효합니다. 하지만 "두 파일 모두 유지"라는 결말은 이제 둘 중 하나만 읽히는 상황이 되었으므로, 이 단계를 가장 먼저 다시 검토해야 합니다.

그리고 조용한 세션을 해석하는 방식이 바뀝니다. 아무런 경고가 없는 세션이 모든 것을 성공적으로 로드했다는 의미는 아닙니다. 이는 계층화된 설정에서 발생하는 패턴과 동일하며, 해결책은 콘텐츠를 다시 작성하는 것이 아니라 충돌하는 CLAUDE.md 계층을 조정하는 방법에서처럼 어떤 계층이 우선권을 가졌는지 파악하는 것입니다.

판단 규칙을 누군가의 머릿속이 아닌 저장소에 기록해 두십시오. 공유 파일의 상단 부근에 이를 취소하는 파일 이름들을 명시해 두면, 다음 작업자가 혼란스러운 오후를 보내는 것을 방지할 수 있습니다.

상시 규칙과 날짜가 포함된 결정 사항을 분리하십시오. 규칙은 모든 도구가 읽는 파일에 속합니다. 결정 사항, 절충안, 제약 조건이 존재하는 이유는 검색 가능한 어딘가에 보관해야 하며, 이는 프로젝트 문서를 AI 메모리로 전환하는 방법에서 구분한 내용입니다.

프로젝트당 한 번이 아니라 환경당 한 번 로드를 확인하십시오. 문서화된 사용 불가 사례는 환경적 요인(제공업체, 텔레메트리, 훅 정책, 업그레이드 후 첫 세션)에 기인하므로, 새 장비나 CI 이미지에서 한 번만 확인하면 그 안의 모든 저장소를 커버할 수 있습니다.

시작 시 로드되는 다른 요소들도 주시하십시오. 로그인된 claude.ai 계정의 스킬과 플러그인이 이제 터미널 세션에 동기화되며, 이는 저장소의 어떤 파일로도 제어할 수 없는 두 번째 상시 동작 소스입니다. 이는 Claude Code 세션 간에 컨텍스트를 공유하는 방법에서 설명한 경계와 맞닿아 있습니다.

다른 에이전트들도 함께 변경되었을 것이라 가정하지 마십시오. 공유 파일이 약속하는 바와 각 도구가 실제로 로드하는 것 사이의 격차는 Codex가 AGENTS.md 규칙을 건너뛰지 않도록 하는 방법에서 문서화된 실패 사례와 동일합니다.

마지막으로, 파일을 아카이브가 아닌 요약본(brief)으로 취급하십시오. 긴 지침 파일은 세션의 나머지 공간과 경쟁하게 되며, 압축 과정에서 살아남는 정보가 무엇인지는 별개의 문제입니다. 이는 Claude Code 자동 압축 시 유지해야 할 사항에서 다루고 있습니다.

핵심은 Claude Code가 AGENTS.md를 읽는다는 점입니다. 하지만 실제로 누군가의 오후 일과를 바꿀 부분은 작업 디렉터리와 그 상위의 모든 디렉터리에 세 가지 특정 파일 이름이 없을 때만 이를 읽는다는 것, 개인용 CLAUDE.local.md가 그중 하나라는 것, 그리고 어떤 파일이 로드되었는지 확인하는 방법이 /memory 목록이 아닌 세션 출력 라인에 있다는 점입니다.

10분만 투자해 보십시오. 영향을 미치는 파일들을 나열하고, Project instructions를 의도적으로 설정한 뒤, 세션을 시작하여 로드 라인을 확인하십시오. 그런 다음 어떤 파일이 프로젝트의 상시 요약본이 될지 결정하고, 이를 설명하는 결정 사항들은 파일 이름이 바뀌어도 변하지 않는 곳에 보관하십시오.