Section 1.10.32 of "de Finibus Bonorum et Malorum", written by Cicero in 45 BC
"Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?"

1914 translation by H. Rackham
"But I must explain to you how all this mistaken idea of denouncing pleasure and praising pain was born and I will give you a complete account of the system, and expound the actual teachings of the great explorer of the truth, the master-builder of human happiness. No one rejects, dislikes, or avoids pleasure itself, because it is pleasure, but because those who do not know how to pursue pleasure rationally encounter consequences that are extremely painful. Nor again is there anyone who loves or pursues or desires to obtain pain of itself, because it is pain, but because occasionally circumstances occur in which toil and pain can procure him some great pleasure. To take a trivial example, which of us ever undertakes laborious physical exercise, except to obtain some advantage from it? But who has any right to find fault with a man who chooses to enjoy a pleasure that has no annoying consequences, or one who avoids a pain that produces no resultant pleasure?"

Section 1.10.33 of "de Finibus Bonorum et Malorum", written by Cicero in 45 BC
"At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga. Et harum quidem rerum facilis est et expedita distinctio. Nam libero tempore, cum soluta nobis est eligendi optio cumque nihil impedit quo minus id quod maxime placeat facere possimus, omnis voluptas assumenda est, omnis dolor repellendus. Temporibus autem quibusdam et aut officiis debitis aut rerum necessitatibus saepe eveniet ut et voluptates repudiandae sint et molestiae non recusandae. Itaque earum rerum hic tenetur a sapiente delectus, ut aut reiciendis voluptatibus maiores alias consequatur aut perferendis doloribus asperiores repellat."

1914 translation by H. Rackham
"On the other hand, we denounce with righteous indignation and dislike men who are so beguiled and demoralized by the charms of pleasure of the moment, so blinded by desire, that they cannot foresee the pain and trouble that are bound to ensue; and equal blame belongs to those who fail in their duty through weakness of will, which is the same as saying through shrinking from toil and pain. These cases are perfectly simple and easy to distinguish. In a free hour, when our power of choice is untrammelled and when nothing prevents our being able to do what we like best, every pleasure is to be welcomed and every pain avoided. But in certain circumstances and owing to the claims of duty or the obligations of business it will frequently occur that pleasures have to be repudiated and annoyances accepted. The wise man therefore always holds in these matters to this principle of selection: he rejects pleasures to secure other greater pleasures, or else he endures pains to avoid worse pains."

안녕하세요? 정리하는 개발자 워니즈입니다. 프로젝트 폴더에 AGENTS.md를 두셨다면, 그 파일이 정말 읽혔는지는 어떻게 확인하고 계신가요.

클로드 코드가 2.1.277부터 이 파일을 공식으로 읽기 시작했는데요, 필자가 제 환경에서 그대로 따라 해보니 읽히지 않았습니다. 파일 이름도 위치도 맞았고 버전도 올렸는데 반응이 없었습니다. 원인을 찾는 데 시간이 좀 걸렸고, 범인은 문서 구석에 한 줄로 적힌 조건이었습니다.

이 글은 폴더 구성을 여섯 가지로 바꿔가며 무엇이 읽히고 무엇이 무시되는지 직접 잰 기록입니다. 동작 규칙은 공식 문서의 메모리 문서와 체인지로그를 근거로 적었고, 판정은 전부 제 맥북에서 2.1.274와 2.1.277 두 버전을 나란히 돌려 확인했습니다.

한 줄 요약. AGENTS.md가 안 읽히는 경우는 네 가지이고, 그중 눈에 안 보이는 것은 피처 플래그를 못 받는 세션입니다. 텔레메트리 관련 환경변수를 켜둔 상태였다면 값을 0으로 바꿔도 해제되지 않습니다. 그 변수는 값이 아니라 존재 여부만 보기 때문입니다.

이 글에서 알 수 있는 것

• 클로드 코드가 AGENTS.md를 읽는 조건과 무시하는 조건
• 폴더 구성 여섯 가지를 직접 돌려 확인한 결과표
• 환경변수 하나 때문에 기능이 통째로 꺼지는 경우와 그 해제 방법
• 두 파일을 같이 읽히게 하는 설정값
• 버전을 못 올리는 환경에서 쓰는 우회로

1. AGENTS.md 지원은 2.1.277부터입니다

AGENTS.md는 코딩 에이전트에게 프로젝트 규칙을 알려주는 파일입니다. 특정 도구 전용이 아니라 여러 도구가 같이 읽는 공용 파일로 자리를 잡아가고 있는데요, 클로드 코드는 그동안 자기 이름이 붙은 CLAUDE.md만 읽었습니다.

체인지로그에 적힌 문장은 짧습니다. CLAUDE.md가 없는 프로젝트에서는 그 파일을 대신 읽고, 동작은 /config의 Project instructions에서 바꾼다는 내용입니다. 베드락과 버텍스, 파운드리에서는 아직 안 된다는 단서도 같이 붙어 있습니다.

여기서 이미 함정이 하나 보입니다. 대신 읽는다는 말은 둘 다 있으면 하나는 버린다는 뜻입니다. 두 파일을 같이 쓰려는 분이 기본 설정으로 두면 한쪽이 조용히 무시됩니다.

이 파일에는 무엇을 적나요?

형식이 정해져 있지는 않습니다. 평범한 마크다운 문서이고, 저장소를 처음 받은 사람에게 설명하듯 적으면 됩니다. 빌드와 테스트를 돌리는 명령, 디렉터리 구조에서 어디에 무엇을 두는지, 커밋 메시지나 브랜치 규칙처럼 이 저장소에서만 통하는 약속이 주로 들어갑니다.

다른 파일을 끌어오는 것도 됩니다. 문서 안에 @ 를 붙여 경로를 적으면 그 파일이 같이 펼쳐집니다. 규칙이 길어지면 주제별로 쪼개두고 이 파일에서 모아 부르는 방식이 관리하기 편한 것 같습니다. 반대로 제외 패턴을 걸어둔 것이 있다면 그 규칙도 그대로 적용됩니다.

2. 필자 환경에서는 읽히지 않았습니다

먼저 증상부터 적겠습니다. 테스트용 폴더를 하나 만들고 AGENTS.md만 넣었습니다. 파일 안에는 누가 봐도 티가 나는 지시를 하나 적어뒀습니다.

어떤 질문을 받든 응답 맨 첫 줄에 CODEWORD=AGENTS-ALPHA 를 출력한다.

이 상태로 클로드 코드를 띄우고 아무 질문이나 던지면, 파일이 읽혔을 때는 응답 첫 줄에 약속한 문자열이 나와야 합니다. 나오지 않으면 안 읽힌 것입니다. 지시문 내용을 물어보는 방식보다 이쪽이 확실한데요, 물어보는 방식은 다른 지시문이 섞여 있을 때 엉뚱한 답을 받기 쉽기 때문입니다.

결과는 그냥 질문에 대한 답만 돌아왔습니다. 약속한 문자열은 없었습니다. 버전은 2.1.277이 맞았고 파일 위치도 작업 폴더 바로 아래였습니다.

왜 제 AGENTS.md는 안 읽혔을까요?

공식 문서에 지원이 안 되는 경우가 네 가지로 적혀 있는데, 그중 세 번째가 원인이었습니다. 피처 플래그를 받아 오지 않는 세션에서는 이 기능이 통째로 꺼집니다. 문서는 그 예로 베드락 같은 제3자 제공자나 텔레메트리를 끈 경우를 듭니다.

필자는 예전에 불필요한 외부 트래픽을 줄여두려고 설정 파일에 CLAUDECODEDISABLENONESSENTIALTRAFFIC을 넣어둔 상태였습니다. 몇 달 전에 넣어두고 잊고 있던 한 줄이 새 기능을 막고 있었습니다.

3. 직접 확인 1: 폴더 구성 여섯 가지로 쟀습니다

원인을 짐작만 하면 다음에 또 헤매니까, 조건을 하나씩 바꿔가며 전부 확인했습니다. 각 폴더에 서로 다른 코드워드를 심어두고 어느 것이 응답에 나오는지를 판정 기준으로 삼았습니다.

네 번째 줄과 다섯 번째 줄이 실무에서 제일 자주 걸릴 조합인 것 같습니다. 특히 다섯 번째가 그렇습니다. 팀이 공용 파일을 쓰기로 했는데 개인이 커밋하지 않는 CLAUDE.local.md를 하나 두고 있으면, 그 사람만 팀 규칙을 못 받는 상태가 됩니다. 에러도 경고도 없어서 본인은 모릅니다.

무엇이 이 파일을 막는지도 갈립니다. 작업 폴더나 그 위쪽에 있는 CLAUDE.md와 .claude/CLAUDE.md, CLAUDE.local.md는 막습니다. 반면 홈 디렉터리의 개인 설정 파일과 조직 관리자가 배포한 파일, 그리고 .claude/rules/ 아래 파일들은 막지 않고 같이 로드됩니다.

직접 재보시려면

같은 확인을 자기 환경에서 하는 데는 오래 걸리지 않습니다. 빈 폴더를 하나 만들고 공용 파일에 코드워드 지시 한 줄만 적어둡니다. 그 폴더에서 클로드 코드를 띄운 다음 아무 질문이나 던져서 응답 첫 줄을 봅니다.

코드워드가 나오면 읽힌 것이고, 안 나오면 이 글의 원인 네 가지를 위에서부터 짚으면 됩니다. 폴더를 새로 만드는 이유는 상위 폴더에 있는 규칙 파일까지 같이 딸려 오기 때문인데요, 홈 디렉터리 아래에서 시험하면 개인 설정 파일이 섞여서 판정이 흐려집니다.

한 가지 주의할 점은 지시문 내용을 직접 물어보는 방식은 피하는 편이 낫다는 것입니다. 필자도 처음에는 규칙에 적힌 값을 물어봤는데, 홈 디렉터리의 개인 설정 파일에 있던 비슷한 단어를 끌어다 그럴듯한 답을 만들어냈습니다. 읽지도 않은 파일의 내용을 아는 것처럼 보이는 답이 나오니 판정이 되지 않았습니다.

4. 직접 확인 2: 버전이 첫 번째 갈림길입니다

같은 폴더를 2.1.274로 열었을 때는 코드워드가 나오지 않았습니다. 지원이 들어간 것이 2.1.277이니 당연한 결과인데요, 이 확인을 굳이 한 이유는 버전 확인이 제일 싸기 때문입니다.

claude --version

여기서 277보다 낮으면 뒤의 조건을 아무리 맞춰도 읽히지 않습니다. 필자는 전역 설치본을 그대로 두고 최신 버전을 따로 실행해서 두 버전을 나란히 비교했습니다. 설치본을 바꾸면 돌아가고 있던 다른 작업까지 같이 영향을 받으니, 확인 목적이라면 격리해서 돌려보는 편이 안전한 것 같습니다.

한 가지 더 있습니다. 설치나 업그레이드 직후 첫 세션에서는 아직 안 읽힙니다. 다음 세션부터 적용되는데요, 이걸 모르면 버전을 막 올린 사람이 “올렸는데 안 되네”라고 판단하고 되돌리기 쉽습니다. 한 번 더 켜보는 것으로 갈립니다.

5. 직접 확인 3: 진짜 범인은 환경변수 하나였습니다

가장 오래 걸린 부분입니다. 설정 파일에서 CLAUDECODEDISABLENONESSENTIALTRAFFIC을 찾아내고 값을 0으로 바꿨습니다. 껐으니 이제 되겠거니 했는데 결과는 같았습니다. 코드워드는 여전히 안 나왔습니다.

변수를 0으로 두면 꺼지는 것 아닌가요?

이 변수는 아닙니다. 공식 환경변수 문서에 토글 변수 목록이 따로 있는데, 거기 적힌 설명은 설정했는지 여부만 읽는다입니다. 0을 포함해 비어 있지 않은 값이면 전부 켜진 것으로 봅니다. 끄려면 변수를 지우거나 빈 값으로 둬야 합니다.

값을 빈 문자열로 바꾸고 다시 돌리자 그때 응답 첫 줄에 코드워드가 나왔습니다. 조건을 하나만 바꿨고 결과가 뒤집혔으니 이 변수가 원인인 것이 확정됐습니다.

토글 변수는 값이 아니라 존재 여부로 판단합니다. 끈다고 0을 넣으면 오히려 켜진 상태로 남습니다.

이 실패가 흔할 것 같은 이유가 있습니다. 끄는 방법으로 0을 넣는 것은 거의 반사적인 동작인데요, 그렇게 하면 화면상으로는 꺼둔 것처럼 보이면서 실제로는 켜져 있습니다. 게다가 이 변수는 이 기능 하나만 막는 것이 아니라 피처 플래그로 배포되는 기능들을 같이 막습니다. 새 기능이 유독 나만 안 된다는 느낌이 들 때 한 번 볼 자리인 것 같습니다.

6. AGENTS.md 안 읽힐 때 원인 4가지

지금까지 확인한 것을 확인 순서대로 정리하면 이렇게 됩니다. 위에서부터 확인하는 것이 빠릅니다.

3번은 지워서 해결하는 것이 정답이 아닐 때가 많습니다. 개인 규칙을 CLAUDE.local.md에 담아두고 있다면 그건 그대로 쓰면서 팀의 공용 파일도 받아야 하는데요, 그럴 때 쓰는 설정이 다음 절입니다.

4번에는 변수 말고도 경로가 있습니다. 훅을 전부 막는 설정을 켜두었거나 관리자 훅만 허용하도록 잠가둔 경우, 그리고 내장 플러그인을 직접 끈 경우에도 같은 증상이 납니다. 이 기능이 내부적으로 플러그인과 훅 위에 얹혀 있기 때문입니다.

7. 두 파일을 같이 읽게 하려면

Project instructions 설정값은 세 가지입니다. 기본값이 둘 중 하나만 읽는 쪽이라 명시적으로 바꿔줘야 합니다.

/config 화면에서 바꿀 수도 있고 설정 파일에 직접 적을 수도 있습니다. 파일에 적을 때는 내장 플러그인 아래에 넣습니다.

{ "pluginConfigs": {
  "agents-md@builtin": {
    "options": { "instructionFiles": "claude-md-and-agents-md" } } } }

이 값은 홈 디렉터리 설정과 관리 설정에서만 먹습니다. 프로젝트 폴더의 설정 파일에 적으면 무시되는데요, 저장소에 커밋해두고 팀원 전부에게 같은 동작을 강제하는 방식은 안 된다는 뜻입니다.

필자 환경에서 이 값을 넣고 돌려보니 CLAUDE.md가 요구한 문장과 공용 파일이 요구한 문장이 응답에 같이 나왔습니다. 한쪽이 다른 쪽을 덮지 않고 둘 다 살아 있었습니다.

8. 버전을 못 올리는 환경에서 쓰는 우회로

베드락이나 버텍스를 쓰고 있거나, 조직 정책 때문에 훅이 막혀 있거나, 사정상 버전을 올릴 수 없는 경우가 있습니다. 이럴 때 예전부터 쓰던 방법이 그대로 유효합니다. CLAUDE.md를 한 줄짜리로 두고 그 파일을 가져오는 것입니다.

@AGENTS.md

필자가 구버전인 2.1.274에서 이 구성을 시험해봤는데요, 공용 파일에 심어둔 코드워드가 응답에 정상으로 나왔습니다. 직접 읽기 기능이 없는 버전에서도 가져오기는 동작합니다.

이미 이렇게 쓰고 계셨다면 굳이 걷어낼 이유는 없습니다. 어떤 설정값을 쓰든 같은 파일을 두 번 읽지는 않게 되어 있어서, 남겨두는 쪽이 오히려 안전합니다. CLAUDE.md에 그 한 줄밖에 없고 모든 환경이 새 버전이라면 그때 지우면 됩니다.

9. 하위 폴더의 AGENTS.md는 언제 읽히나요?

세션을 시작할 때 읽는 것은 작업 폴더와 그 위쪽의 파일들입니다. 하위 폴더의 파일은 시작 시점에 안 읽힙니다.

대신 클로드가 그 폴더의 파일을 실제로 열 때 따라 들어옵니다. 시험해보니 하위 폴더의 텍스트 파일 하나를 읽게 시켰더니 그 폴더의 AGENTS.md가 요구한 문장이 그때부터 응답에 붙었습니다. 모노레포처럼 폴더마다 규칙이 다른 구조에서는 이 동작이 편한데요, 반대로 세션 초반에는 하위 규칙이 안 들어와 있다는 뜻이기도 합니다.

읽히지 않는 파일 이름도 정해져 있습니다. AGENTS.local.md와 AGENTS.override.md, 그리고 .agents/ 폴더 아래 파일은 대상이 아닙니다. 개인 규칙을 로컬 파일로 분리하는 습관이 있다면 이름을 그렇게 지어도 안 읽힙니다.

한 가지 알아둘 것은 확인 경로가 CLAUDE.md와 다르다는 점입니다. 같은 지시문 역할을 하지만 도구에서 다뤄지는 방식은 세 군데에서 갈립니다.

첫 줄이 특히 헷갈리는 자리입니다. 목록에 없다고 안 읽힌 것으로 판단하면 오판입니다. 대화형 세션이라면 시작할 때 나오는 로드 안내 줄을 보거나, 이 글에서 쓴 것처럼 코드워드를 심어서 확인하는 편이 확실합니다. 규칙 파일을 어떤 구조로 나눠 쓰는지는 클로드 코드 에이전틱 코딩 서평에도 정리해두었습니다.

10. 지금 옮겨야 할까요

정리하면 이렇습니다. 여러 도구를 같이 쓰고 계시고 규칙 파일을 하나로 합치고 싶으셨다면 지금이 적기인 것 같습니다. 별도의 가져오기 설정 없이도 읽히니까 저장소가 깔끔해집니다.

반대로 클로드 코드만 쓰고 계시다면 굳이 바꿀 이유는 없어 보입니다. CLAUDE.md는 계속 지원되고 /memory 같은 도구도 그쪽이 더 잘 붙습니다. 이 글에 적은 함정들도 대부분 두 파일이 섞일 때 생기는 것입니다.

필자는 두 파일을 같이 읽는 설정으로 두기로 했습니다. 공용 규칙은 그 파일에 두고 클로드 코드에만 해당하는 것은 CLAUDE.md에 남기는 편이 나눠서 관리하기 좋다고 봤습니다. 다만 그 전에 환경변수부터 걷어냈습니다. 몇 달 전에 넣어둔 한 줄이 새 기능을 조용히 막고 있었다는 게 이번 건의 실제 교훈이었습니다.

도구 규칙 파일을 쌓다 보면 어느 순간 무거워지는데요, 무엇을 남기고 무엇을 버릴지는 AI 코딩 하네스를 절반 걷어낸 기록에 따로 적어뒀습니다. 사용량이 어디서 새는지 확인하는 방법은 클로드 코드 사용량 확인 3가지에 정리해두었습니다.

The post [AI 코딩] AGENTS.md 안 읽힐 때 원인 4가지 appeared first on WONIZZ.LOG.