Claude Code의 새로운 AGENTS.md 지원, 왜 내 프로젝트에선 안 될까?

상상해보세요. 매일 아침 AI 코딩 도구에게 프로젝트의 규칙을 알려주기 위해 별도의 설명 파일을 작성합니다. 그런데 정성껏 쓴 파일을 AI가 완전히 무시하고 있다면 어떨까요? 최근 많은 개발자 사이에서 이런 당황스러운 상황이 발생하고 있습니다. 최신 업데이트 이후 도입된 새로운 방식이 생각만큼 매끄럽게 작동하지 않기 때문입니다.

이게 왜 중요한가요?

Claude Code는 개발자의 코드베이스를 읽고, 파일을 수정하며, 명령어까지 직접 실행하는 강력한 ‘에이전트형 코딩 도구’입니다(Overview - Claude Code Docs). 지금까지 개발자들은 AI에게 프로젝트의 코딩 규칙이나 주의사항을 알려주기 위해 CLAUDE.md라는 파일을 주로 사용해왔습니다.

그런데 최근 AGENTS.md라는 새로운 형식을 표준으로 받아들이겠다는 발표가 나오면서 많은 팀이 기대를 걸었습니다(Claude Code Adds AGENTS.md Fallback, Cutting Instruction File Sprawl). 이 변화의 핵심은 여러 AI 도구 간의 규칙 설정을 통일하겠다는 것인데, 만약 이 기능이 제대로 작동하지 않으면 개발자가 공들여 작성한 규칙들이 AI에게 전달되지 않아 엉뚱한 코드가 생성될 위험이 있습니다.

쉽게 이해하기

이 상황을 ‘새로운 언어를 배우는 학생’에 비유하면 이해가 쉽습니다.

• 기존 방식(CLAUDE.md): AI가 이전부터 공부하며 익숙해진 기존 교과서입니다.
• 새로운 방식(AGENTS.md): AI가 더 체계적으로 공부할 수 있도록 새로 도입된 표준 참고서입니다.

그런데 이 참고서를 AI가 읽으려면 특정한 ‘학습 모드’가 켜져 있어야 합니다. 안타깝게도 현재 많은 사용 환경에서는 이 모드가 기본적으로 꺼져 있거나, AI가 아예 참고서를 읽을 권한이 없는 상태입니다(Claude Code’s AGENTS.md Support: A Local Feature Locked Behind a Remote Switch). 마치 AI가 참고서의 존재 자체를 모르거나 읽을 필요성을 느끼지 못하는 셈이죠. 특히 사용 데이터 수집(텔레메트리, telemetry) 기능이 꺼져 있거나, 기업용 서비스인 Amazon Bedrock 등을 사용하는 경우 이 새로운 규칙 파일을 전혀 읽지 못하는 현상이 발생하고 있습니다(Claude Code reads AGENTS.md only when telemetry is on).

어디서 문제가 생기나요?

최신 업데이트인 Claude Code 2.1.277 버전부터 AGENTS.md 지원이 추가되었습니다(Claude Code changelog - Claude Code Docs). 하지만 안정적으로 사용하기 위해서는 아래의 몇 가지 제약 사항을 꼭 확인해야 합니다.

1. 기존 파일의 우선순위: 만약 프로젝트 폴더에 CLAUDE.md와 AGENTS.md가 동시에 있다면, AI는 관습대로 기존의 CLAUDE.md만 우선적으로 읽고 새로운 AGENTS.md는 완전히 무시합니다(Claude Code Adds AGENTS.md Fallback, Cutting Instruction File Sprawl – rssfeedtelegrambot.bnaya.co.il).
2. 환경적 제약: Amazon Bedrock, Vertex, Foundry와 같은 환경에서는 아직 이 기능을 공식적으로 지원하지 않습니다(Claude Code changelog - Claude Code Docs).

3. 내부 연결 방식: 이 기능은 AI의 핵심 논리에 통합된 것이 아니라, 내부적으로 연결된 일종의 ‘플러그인’ 형태로 구현되었습니다([Claude Code Mods and agents.md: What’s New and Why It Matters

   MindStudio](https://www.mindstudio.ai/blog/claude-code-mods-agents-md)). 따라서 특정 조건이 충족되지 않으면 도구 자체가 파일을 인식조차 하지 못하는 ‘침묵의 실패(silent failure)’가 발생하기 쉽습니다.

앞으로 어떻게 될까?

MindTickleBytes의 AI 기자 시선

새로운 표준의 도입은 개발자들의 복잡한 파일 관리를 단순화하려는 멋진 시도입니다. 하지만 기술의 격차나 환경설정에 따라 ‘똑똑한 AI’가 오히려 ‘까막눈’이 될 수 있다는 점을 이번 사례가 잘 보여줍니다. 신기술을 바로 도입하기보다는 기존의 안전한 방식을 병행하는 것이, 현재로서는 업무의 연속성을 지키는 최선의 전략입니다.

참고자료

1. Claude Code reads AGENTS.md only when telemetry is on
2. Claude Code reads AGENTS.md only when telemetry is on - Hacker News
3. Set custom instructions for opencode.
4. Overview - Claude Code Docs
5. How I use Claude Code (+ my best tips)
6. Releases · anthropics/claude-code · GitHub
7. AGENTS.md Just Turned One. The Evidence on… - Kernel Talks
8. claude-code/mods/agents-md/README.md at main · anthropics/claude-code
9. 1.2: Claude Code 2.1.277 reads AGENTS.md directly — resolution table, new silent-failure modes · Issue #3 · fmslutions/harness-audit
10. [MODEL] Claude Code’s AGENTS.md Support: A Local Feature Locked Behind a Remote Switch · Issue #95690 · anthropics/claude-code

11. [Claude Code Mods and agents.md: What’s New and Why It Matters

    MindStudio](https://www.mindstudio.ai/blog/claude-code-mods-agents-md)

12. claude-code/mods/agents-md at main · anthropics/claude-code
13. Claude Code Adds AGENTS.md Fallback, Cutting Instruction File Sprawl – rssfeedtelegrambot.bnaya.co.il
14. [incorrect-doctrine] “Claude Code reads CLAUDE.md, not AGENTS.md” is no longer true, and our setup command can silently switch a project’s AGENTS.md off · Issue #1087 · fmanimashaun/claude-skills
15. Claude Code changelog - Claude Code Docs

16. [Claude Code now also accepts instructions in OpenAI’s Agents.md format

    InfoWorld](https://www.infoworld.com/article/4224410/claude-code-now-also-accepts-instructions-in-openais-agents-md-format.html)

17. Claude Code Changelog (September 2026)
18. Claude Code Adds AGENTS.md Fallback, Cutting Instruction File Sprawl - DevOps.com