CLAUDE.md가 없을 때만 읽는다: Claude Code가 받아들인 AGENTS.md 폴백의 운영 기준

AGENTS.md, 20개 넘는 도구가 합의한 지침 파일

AGENTS.md는 프로젝트 루트에 두는 에이전트 전용 안내 파일로, 빌드·테스트 명령이나 코딩 규칙처럼 사람용 README에는 넣지 않는 실행 맥락을 담습니다. 2025년 8월 OpenAI·Google·Cursor·Factory·Sourcegraph가 함께 형식을 확정한 뒤 1년여 만에 2만 개 넘는 저장소가 채택했고, 지금은 Linux Foundation 산하 Agentic AI Foundation이 표준을 관리합니다. Codex·Cursor·GitHub Copilot 코딩 에이전트·Gemini CLI·Windsurf·Aider·Zed 등 20종 이상의 도구가 별도 설정 없이 이 파일을 읽습니다.

Claude Code의 선택: 병합이 아니라 폴백

9월 18일 배포된 Claude Code 2.1.277은 CLAUDE.md가 없을 때만 AGENTS.md를 읽는 지원을 추가했습니다. 두 파일을 합치지 않고 CLAUDE.md가 있으면 그 내용이 그대로 우선하며, 어느 파일을 먼저 볼지는 /config의 "Project instructions" 항목에서 바꿀 수 있습니다. 다만 이 폴백은 아직 Bedrock·Vertex·Foundry 경유 배포에는 적용되지 않아, 같은 저장소라도 접속 경로에 따라 지침이 다르게 동작할 수 있습니다.

표준 채택 이후: 여러 에이전트 CLI를 쓰는 팀의 지침 파일 운영 기준

여러 에이전트 CLI를 함께 쓰는 팀은 저장소당 지침 파일 수를 1개로 줄이는 것을 목표 지표로 삼아야 합니다. 이관 완료 저장소 비율 100%, 지침 변경 후 에이전트 동작 회귀 테스트 통과율 100%를 배포 기준으로 세우고, 어느 파일을 정본으로 둘지(대개 AGENTS.md 단일화, 남겨야 하면 CLAUDE.md에는 안내문만) 저장소마다 문서로 못 박습니다.

가장 흔한 실패는 최신 규칙을 AGENTS.md에만 반영하고 CLAUDE.md는 손대지 않는 경우입니다. Claude Code는 CLAUDE.md가 있으면 그것만 읽으므로, 팀이 최신이라 믿는 AGENTS.md 내용은 실제로는 하나도 반영되지 않습니다. 두 번째 실패는 Bedrock·Vertex처럼 폴백이 아직 없는 경로에서 CLAUDE.md를 지우고 AGENTS.md만 남긴 경우로, 해당 경로의 에이전트는 지침 없이 그대로 동작해 버립니다.

정본을 AGENTS.md로 정했다면 CLAUDE.md는 완전히 지워 폴백을 강제로 발동시키는 편이 안전합니다. 두 파일을 당분간 함께 둬야 하는 팀은 커밋 전 훅으로 두 파일의 내용 차이를 매번 검사해, 한쪽만 바뀐 채 넘어가는 커밋을 막습니다. 배포 경로별 지원 여부(로컬 CLI·Bedrock·Vertex·Foundry)는 표로 만들어 미지원 경로에는 별도 안내를 붙여 둡니다.

새 에이전트 도구를 팀에 들일 때마다 지침 파일 우선순위를 다시 확인하고, CI에 AGENTS.md·CLAUDE.md 동시 존재 여부와 최종 수정일 차이를 검사하는 단계를 넣습니다. /config의 Project instructions 설정값은 팀 문서에 그대로 옮겨 적어, 팀원마다 로컬 설정이 제각각으로 흩어지는 상황을 막습니다.

Agentic AI Foundation의 스펙 변경과 Claude Code 릴리스 노트는 매월 한 번 확인해 Bedrock·Vertex·Foundry 지원이 넓어지는 시점을 놓치지 않습니다. 지침 파일 때문에 생긴 장애는 원인을 별도 변경 로그에 남겨, 다음에 새 도구를 온보딩할 때 같은 실수를 반복하지 않도록 합니다.

한눈에 보는 적용 포인트

AGENTS.md는 이제 20종 넘는 도구가 공유하는 사실상 표준이고, Claude Code의 지원은 병합이 아닌 폴백이라 우선순위 관리가 곧 운영 과제입니다. 저장소당 지침 파일 1개, 배포 경로별 지원 표, 커밋 전 동기화 검사 세 가지만 갖추면 새 도구가 추가돼도 같은 기준으로 흡수할 수 있습니다.

참고 링크

AGENTS.md — 공식 표준 사이트

Claude Code Changelog — Anthropic