쇼피파이(Shopify) CEO 토비 뤼트케는 8월 25일 공개적으로, Anthropic이 방침을 바꿔 Claude Code가 AGENTS.md와 .agents/skills 같은 파일을 읽도록 하지 않는 한 사내에서 Claude Code 사용을 금지하는 방안을 검토 중이라고 밝혔다. 그가 든 이유는, Claude Code가 CLAUDE.md만 고집해서 읽다 보니 서로 다른 도구를 쓰는 팀원 사이에 '인지 분열'이 생긴다는 것이었다. 그는 이를 굳이 치르지 않아도 될 복잡성 비용이라고 표현했다.
쟁점은 마크다운 파일 하나
AGENTS.md는 OpenAI가 2025년 8월 도입한 관례다. 프로젝트의 빌드 명령, 테스트 방법, 보안 규칙을 저장소 루트의 마크다운 파일 하나에 정리해 두면 코딩 에이전트가 이를 읽어 코드베이스를 이해하는 방식이다. 2025년 말까지 공개된 데이터에 따르면 6만 개가 넘는 오픈소스 프로젝트가 이 파일을 도입했고, 표준 자체는 이후 리눅스 재단 산하 Agentic AI Foundation으로 이관됐다. Codex, Cursor, Gemini CLI, GitHub Copilot, Jules, VS Code 모두 이를 인식한다.
반면 Claude Code는 자체 CLAUDE.md를 사용한다. 개인 프로젝트라면 파일을 하나 더 쓰는 정도의 문제지만, 수천 명이 하나의 대형 저장소를 함께 쓰는 쇼피파이 같은 조직에서는 문제의 성격이 달라진다. 같은 디렉터리에 둘 중 하나만 있으면, 다른 도구를 쓰는 동료가 받는 맥락 정보는 그만큼 불완전해진다.
1년째 열려 있는 요청
Claude Code가 AGENTS.md를 네이티브로 지원하도록 요구하는 GitHub 이슈는 2025년 8월부터 있었고, 거의 5000개의 추천을 받아 해당 저장소에서 가장 많은 지지를 받은 호환성 요청 중 하나가 됐다. 이후 비슷한 이슈 몇 건이 잇달아 닫혔고, 그중 하나는 '현재로서는 계획 없음'이라는 결론이 달렸다. 개발자들은 그 밑에 수백 개의 댓글을 남겼지만, 공식적인 입장은 끝내 나오지 않았다.
커뮤니티의 우회 방법은 이미 자리를 잡은 지 오래였다. CLAUDE.md를 AGENTS.md를 가리키는 심볼릭 링크로 만들거나, CLAUDE.md 안에 'AGENTS.md를 읽으라'는 한 줄을 적어두는 식이다. 효과는 있지만, 저장소마다 매번 다시 해줘야 한다.
Anthropic, 마침내 이유를 밝히다
뤼트케가 발언한 당일, Anthropic의 Thariq가 답글을 달아 팀이 Claude Code를 더 커스터마이징하기 쉽게 만들고 있으며, 이후 AGENTS.md를 손쉽게 쓰거나 시스템 프롬프트를 직접 수정할 수 있게 될 것이고 준비되면 다시 알리겠다고 밝혔다. 그는 또 그동안 거절해 온 이유도 처음으로 설명했다. 서로 다른 모델 계열이 상호 교체 가능하다고 보지 않으며, 시스템 프롬프트가 성능에 미치는 영향이 커서 Claude Code 내부적으로 모델별로 시스템 프롬프트를 따로 관리하고 있고, 이 유지보수 부담이 작지 않다는 것이었다.
이 논리는 기술적으로는 성립한다. 같은 지시문을 서로 다른 제조사의 모델에 넣어도 결과에는 확실히 차이가 나며, 특정 모델에 맞춰 다듬은 프롬프트는 눈에 띄는 성능 차이를 만들어낸다. 다만 이는 CLAUDE.md가 별도로 존재해야 하는 이유를 설명할 뿐, 겸사겸사 AGENTS.md도 함께 읽지 못할 이유는 설명하지 못한다. 둘은 서로 충돌하는 문제가 아니기 때문이다.
컨텍스트 파일, 새로운 격전지가 되다
GitHub 저장소 2926개를 대상으로 한 조사에 따르면, 컨텍스트 파일은 이미 개발자가 코딩 에이전트에 지시를 내리는 가장 흔한 방식이다. 이 자리를 한 회사의 독점 포맷이 차지해버리면 이전 비용은 고스란히 사용자 몫이 된다. 오늘은 파일 하나를 더 관리하는 정도지만, 내일은 스킬, 서브 에이전트, 권한 설정까지 통째로 한 회사의 디렉터리 구조 안에 묶여버릴 수도 있다.
공수 측면에서 보면 이번 대치는 다소 균형이 맞지 않는다. CLAUDE.md를 찾지 못했을 때 Claude Code가 AGENTS.md로 폴백하도록 만드는 것은 수십 줄짜리 파일 탐색 로직에 불과해, '모델별로 시스템 프롬프트를 유지하는 것'과는 완전히 다른 차원의 작업이다. 범용 지시문이 성능을 떨어뜨릴까 정말 우려된다면 주의 문구 한 줄만 추가하면 될 일이다. 지난 1년간 커뮤니티가 거듭 제안해 온 것도 바로 이 절충안이었다. 기본으로는 CLAUDE.md를 읽고, 없으면 AGENTS.md를 읽으며, 둘 다 있으면 CLAUDE.md를 우선한다는 방식이다.
뤼트케의 공개 압박이 통한 이유도 단순하다. 쇼피파이는 Claude Code를 대규모로 쓰는 고객이고, 상장기업 CEO가 공개적으로 퇴출을 언급하는 무게는 익명 추천 5000개보다 훨씬 크다. Anthropic 입장에서 Claude Code의 현재 우위는 제품 경험에서 나오는 것이지 포맷 종속에서 나오는 게 아니다. 개발자들이 이미 여러 도구를 함께 쓰는 것이 일상이 된 지금, 호환성을 스위치 하나로 만드는 쪽이 파일 이름 하나를 지키는 것보다 남는 장사라는 판단으로 보인다.
참고 출처: The New Stack, GitHub, CocoLoop, Hacker News. AGENTS.md 채택 규모, 이슈 추천 수, Anthropic 측 발언은 모두 공개된 페이지를 근거로 확인했다.