클로드 코드 AGENTS.md 지원 — 직접 읽지만 로컬 파일 하나에 막힘

여러 AI 코딩 도구가 함께 읽는 공용 지침 파일을 정리하면서, 클로드 코드에서는 CLAUDE.md 안에 불러오기를 적어 두는 방법을 권해 드린 적이 있습니다. 그게 2.1.277판부터 필요 없어졌습니다 — 이제 AGENTS.md를 그냥 읽습니다.

반가운 변화인데 조건이 붙습니다. 특히 개인용 지시 파일을 하나 만들어 두면 그 순간 AGENTS.md를 안 읽습니다. 예전 요령을 그대로 쓰고 계시다면 확인이 필요합니다.

📌 30초 요약

• 불러오기가 필요 없습니다.
• 둘 다 있으면 CLAUDE.md만입니다.
• 개인용 파일이 가로막습니다.
• 안 읽히는 경우가 넷입니다.
• 목록에는 안 뜹니다.

1. 이제 그냥 읽습니다

공식 문서의 표현이 분명합니다 — 다른 코딩 에이전트용으로 이미 꾸며 둔 저장소라면, 클로드 전용 파일도 불러오기도 설정도 더하지 않고 그대로 동작합니다. 저장소에 무엇이 있느냐에 따라 읽는 것이 갈립니다.

저장소 상태	읽는 것
공용 파일만 있음	공용 파일을 그대로
둘 다 있음	클로드 전용 것만
불러오기를 적어 둠	전용 것 + 불러온 공용 파일
설정을 바꿈	둘을 나란히(전용이 먼저)

둘째 줄이 기본 성질입니다 — 클로드 전용 파일이 있으면 공용 파일은 무시됩니다. 둘을 함께 쓰고 싶으면 넷째 줄처럼 설정을 바꿔야 하는데, 같은 폴더에서 전용 파일이 먼저 실리고 공용 파일이 뒤에 붙습니다. 이미 불러오기로 들어온 건 두 번 세지 않습니다.

읽어 가는 범위도 넓습니다. 세션이 시작될 때 작업 폴더와 그 위쪽 폴더들의 공용 파일을 전부 훑고, 일하다가 하위 폴더의 파일을 열면 그 폴더의 공용 파일도 그때 읽습니다(그 폴더에 전용 파일이 없을 때만요). 파일 안의 불러오기 표기도 그대로 펼쳐집니다.

2. 무엇이 가로막나

「전용 파일이 있으면 무시」라는 규칙에서 무엇이 전용 파일로 세어지느냐가 핵심입니다. 문서가 둘로 갈라 두었습니다.

세어지는 것은 작업 폴더나 그 위 어느 폴더든에 있는 클로드 전용 파일 세 종류입니다 — 일반 파일, 숨김 폴더 안의 파일, 그리고 개인용 파일이죠. 안 세어지는 것은 홈에 둔 내 개인 지침, 조직이 관리하는 지침, 그리고 규칙 폴더의 파일들입니다. 이 셋은 공용 파일과 나란히 계속 실립니다.

⚠️ 개인용 파일 하나가 공용 파일을 통째로 막습니다

문서가 따로 경고를 붙여 둔 대목입니다. 개인용 지시 파일도 「전용 파일」로 세어지기 때문에, 공용 파일로 굴러가던 프로젝트에 내 취향을 적으려고 개인용 파일을 하나 만들면 그 순간부터 공용 파일을 안 읽습니다. 커밋도 안 되는 파일이라 팀원은 멀쩡한데 내 세션에서만 팀 규칙이 빠지는 상황이 됩니다. 게다가 조용히 그렇게 되죠. 둘 다 살리려면 설정을 「둘 다 읽기」로 바꿔 두셔야 합니다.

설정은 대화 중에 설정 화면을 열어 「프로젝트 지시문」 항목에서 고릅니다. 값이 넷인데 기본은 「전용 아니면 공용」이고, 나머지는 「둘 다」·「전용만」·「조직 것만」입니다. 설정이 덮어쓰기가 아니라 합쳐지던 성질을 떠올리면 헷갈리기 쉬운데, ★이 값은 프로젝트나 로컬 설정 파일에 적으면 무시되고 홈 설정이나 관리 설정에서만 먹습니다.

3. 아예 안 읽히는 네 경우

파일 배치와 무관하게 기능 자체가 안 도는 상황도 있습니다. 이때는 설정 화면에 「프로젝트 지시문」 항목이 아예 안 보입니다.

이런 경우	왜 그런가
판이 낮음	2.1.277판부터 생긴 기능
제3자 경유·측정 끔	기능 스위치를 못 받아옴
설치·판올림 직후	다음 세션부터 읽음
훅을 막아 둠	이 기능이 내장 확장이라서

셋째 줄이 은근히 헷갈립니다 — 판을 올린 바로 그 세션에서는 아직 안 읽고, 그다음 세션부터 읽습니다. 「분명 최신인데 왜 안 되지」 싶으면 세션을 한 번 새로 열어 보세요.

넷째 줄은 설계를 알려 줍니다. 이 기능이 내장 확장으로 구현돼 있어서, 훅을 전부 끄거나 관리자가 허용한 것만 돌게 해 두었거나 그 확장을 꺼 두면 공용 파일도 함께 안 읽힙니다. 보안상 훅을 잠가 둔 회사 환경이라면 예상 못 한 곳에서 걸릴 수 있는 셈이죠. 이런 세션에서는 예전처럼 불러오기를 적어 두는 방법이 여전히 답입니다.

4. 예전 요령 정리하기

문서가 기존 우회책별로 어떻게 하라고 따로 적어 두었습니다. 네 가지 경우가 있습니다.

불러오기를 적어 둔 전용 파일은 그냥 두셔도 됩니다 — 어떤 설정값이든 같은 내용을 두 번 읽는 일은 없습니다. 다른 내용이 없으면 지워도 되고, 일부 세션에서 직접 못 읽는 환경이라면 남겨 두는 편이 안전합니다. 연결 고리로 만들어 둔 경우도 마찬가지로 둬도 지워도 결과가 같습니다.

고쳐야 하는 건 나머지 둘입니다. 「공용 파일을 읽어라」라고 말로 적어 둔 경우는 클로드가 그 파일을 열기로 마음먹어야만 반영되므로, 전용 파일을 지우거나 그 문장을 불러오기 표기로 바꿔야 합니다. 그리고 세션이 시작될 때 공용 파일 내용을 출력하도록 훅을 걸어 두셨다면 반드시 없애세요 — 이제 직접 읽으므로 맥락에 같은 내용이 두 벌 들어갑니다.

마지막으로 확인 방법입니다. 지시문이 어디서 오는지 따져 보던 자리에서도 그랬듯, 읽혔는지 눈으로 보는 게 중요한데 — ★이 파일은 기억 파일 목록에 안 뜹니다. 대신 대화형 세션이라면 시작할 때 「전용 파일이 없어 공용 파일을 불러왔다」는 줄이 경로와 함께 보이고, 아니면 클로드에게 지금 어떤 프로젝트 지시를 갖고 있는지 물어 보시면 됩니다.

자주 묻는 질문 (FAQ)

Q. 기존 불러오기를 지워야 하나요

안 지우셔도 됩니다. 두 번 읽히지 않습니다. 다른 내용이 없다면 지워도 되지만, 제3자 경유처럼 직접 못 읽는 세션이 섞여 있다면 남겨 두는 편이 안전합니다.

Q. 팀 규칙이 갑자기 안 먹습니다

개인용 지시 파일을 만드신 적이 있는지 보세요. 그 파일 하나가 공용 파일을 통째로 밀어냅니다. 둘 다 살리려면 설정에서 「둘 다 읽기」로 바꾸세요.

Q. 읽었는지 어떻게 확인하나요

기억 파일 목록에는 안 나옵니다. 세션 시작 줄에서 불러온 경로를 확인하거나, 클로드에게 지금 어떤 프로젝트 지시를 갖고 있는지 직접 물어보세요.

Q. 하위 에이전트에도 전달되나요

전용 파일과 같은 취급입니다. 즉 프로젝트 지시문을 건너뛰도록 만든 하위 에이전트는 이것도 건너뜁니다. 반드시 닿아야 할 규칙은 맡길 때 문장에 직접 적어 주세요. 일꾼에게 따로 기억을 쥐여 주는 방법은 별개 장치입니다.

정리하면

• 이제 그냥 읽습니다.
• 전용 파일이 우선입니다.
• 개인용 파일이 막습니다.
• 훅을 잠그면 같이 멈춥니다.
• 출력하던 훅은 지우세요.

※ 2.1.277·2.1.278 변경 기록과 공식 기억 문서의 해당 절을 읽고 정리했습니다. 설정 항목과 값 이름은 우리말로 풀어 적었으니 실제 표기는 원문에서 확인하세요.

※ 2026년 9월 21일 기준입니다. 판올림에 따라 기본값과 지원 범위가 달라질 수 있습니다.