Claude Code의 AGENTS.md 거부가 개발자 반발을 부른 이유

들어가며

AI 코딩 도구의 호환성을 둘러싼 논쟁에서 한 개의 Markdown 파일이 핵심 쟁점으로 떠올랐다. Shopify CEO Tobi Lütke는 Anthropic이 Claude Code의 AGENTS.md 읽기를 지원하지 않으면 사내에서 이 도구를 비활성화할 수 있다고 공개적으로 밝혔다. 개인 개발자에게는 파일 이름을 하나 바꾸는 문제처럼 보일 수 있지만, 수천 명의 개발자가 대형 monorepo를 관리하는 기업에서는 지속적인 ‘복잡성 세금’이 될 수 있다.

무엇이 문제인가

AGENTS.md와 CLAUDE.md는 코딩 에이전트에 저장소의 규칙을 전달하는 지침 파일이다. 빌드 명령, 테스트 조건, 코딩 규칙, 작업 제한 등을 기록할 수 있다. 에이전트는 작업 중인 디렉터리와 연결된 파일을 디렉터리 트리에서 읽고, 일반적으로 현재 위치에 가까운 규칙을 더 구체적인 지침으로 적용한다.

OpenAI가 2025년 선보인 AGENTS.md는 Codex, Cursor, Gemini CLI, GitHub Copilot, Jules, VS Code 등 여러 도구에서 채택됐다. 이후 이 형식은 Linux Foundation 산하 Agentic AI Foundation으로 넘어갔다. 반면 Claude Code는 CLAUDE.md를 사용하며 AGENTS.md를 기본적으로 읽지 않는다. 따라서 같은 디렉터리라도 다른 도구에는 충분한 프로젝트 맥락이 제공되지만, Claude Code에는 중요한 규칙이 빠질 수 있다.

대규모 코드베이스에서는 이 차이를 수작업으로 해결하기 어렵다. 팀은 CLAUDE.md에서 AGENTS.md를 불러오거나, 심볼릭 링크와 재귀 검색 스크립트, 파일 감시기, 시작 프로그램 설정, Git 무시 규칙 등을 조합해야 한다. 소재에는 fswatch와 launchd를 이용한 Mac 자동화 사례도 등장한다. 이런 방법은 당장의 문제를 줄여 주지만, 제품이 기본 지원하지 않는 형식을 보완하기 위해 별도의 운영 기반을 유지해야 한다는 뜻이기도 하다.

Anthropic의 답변이 논란을 끝내지 못한 이유

Claude Code 팀의 Thariq는 제품의 커스터마이징 기능을 강화해 향후 AGENTS.md 사용이나 관련 시스템 프롬프트 수정을 쉽게 만들겠다고 설명했다. 현재는 CLAUDE.md에 “@AGENTS.md”를 적어 불러오는 방식이 제시돼 있다. 그러나 다른 도구처럼 AGENTS.md를 자동으로 찾고 읽을 것인지는 분명히 하지 않았다.

Anthropic은 모델마다 필요한 컨텍스트, Skill, 시스템 프롬프트가 다를 수 있다고 설명한다. 개발자들은 기업이 이미 여러 모델을 함께 사용하고 있으며, 모델마다 별도의 지침 파일을 관리하면 적응 비용이 사용자에게 전가된다고 반박한다. 모델별 최적화는 도구 내부의 하니스가 담당하고, 저장소에는 공통 규칙을 두는 편이 현실적이라는 주장이다.

산업적 의미

핵심은 어떤 파일 이름이 더 우수한지가 아니다. 호환성 부족으로 생긴 비용을 누가 부담할지에 있다. 개인 사용자는 링크나 import로 대응할 수 있지만, 기업에서 지침 파일은 여러 팀이 공유하는 엔지니어링 자산이다. 어떤 규칙이 적용됐는지 보여 주는 기능, 디렉터리 트리의 재귀 로딩, 도구 간 일관성은 플랫폼이 제공해야 할 기능에 가깝다.

Claude Code 전용 확장을 위해 CLAUDE.md를 유지하더라도, 공통 규칙의 기본 계층으로 AGENTS.md를 지원하는 것이 마찰을 줄이는 방법일 수 있다. 그렇지 않으면 이 문제는 단순한 파일 형식 논쟁을 넘어, 하나의 도구를 위해 별도의 생태계를 계속 유지할 것인지에 대한 논쟁으로 커질 가능성이 있다.

출처: InfoQ 中文