Originally published at vinpatel.com

Claude Code의 새로운 AGENTS.md 폴백을 단순한 호환성 각주로만 읽는 사람들은 진짜 이야기를 놓치고 있습니다: Anthropic이 OpenAI의 파일 형식이 승리했음을 인정했습니다.

그 변화 자체는 사소합니다. Claude Code는 이제 프로젝트에 Claude.md가 없을 때 AGENTS.md를 읽게 됩니다. 변경 로그(changelog) 한 줄일 뿐입니다. 하지만 변경 로그 라인이 바로 포맷 전쟁이 실제로 끝나는 방식입니다—선언을 통해서가 아니라, 아무도 논쟁할 필요성을 느끼지 못하는 조용한 폴백 규칙으로요.

순서를 보세요.

2025년, OpenAI의 Codex 에이전트가 AGENTS.md를 레포지토리 수준의 코딩 에이전트 지침을 위한 표준 파일로 대중화시켰습니다—README와 동등하지만 인간이 아닌 모델을 위해 작성된 것입니다.

2025년 후반에, 다른 에이전트 기반 코딩 도구들이 자체 독점 설정 파일과 함께 AGENTS.md를 인식하기 시작했고, 이를 어떤 에이전트든 파싱할 수 있는 가장 낮은 공통 분모(lowest-common-denominator) 형식으로 취급했습니다.

2026년, Claude Code의 변경 로그가 그들을 따라잡으며, Claude.md가 없을 때 AGENTS.md를 폴백으로 추가했습니다.

핵심은

다중 에이전트 레포지토리(multi-agent repo)를 관리하는 모든 사람에게 — 여기서는 Claude Code, 저기 Codex, 그리고 다음 분기에 또 다른 도구가 있을 수 있습니다 — 이 내용은 변경 로그에 적힌 것보다 더 중요합니다. 이제 세 가지 형식을 가로질러 분산된 세 개의 지침 파일이 필요하지 않습니다. 하나의 AGENTS.md만 있으면 모든 것이 읽을 수 있으며, Claude-specific 오버라이드(override)가 필요한 경우에만 Claude.md를 사용하면 됩니다. 이는 실제 유지보수 비용을 절감합니다. 즉, 누군가 한 파일을 업데이트하고 나머지 두 개를 잊어버리는 순간 필연적으로 동기화에서 벗어나게 되는 설정 파일 간의 편차(drift) 문제입니다.

실무자들은 이렇게 읽을 수 있습니다: 이것은 진정한 표준이 될 수 있는 것에 생긴 첫 번째 균열입니다. 만약 Claude Code가 AGENTS.md를 기본값으로, CLAUDE.md를 오버라이드로 취급한다면, Anthropic 자체 문서도 2026년 말까지 단순히 폴백(fallback)으로 지원하는 것을 넘어 AGENTS.md 우선 설정을 권장하기 시작할 것으로 예상됩니다. 만약 대신 Claude.md가 1년 후에도 Anthropic의 자체 문서에서 주요 권장 사항으로 남아있다면, 이 분석은 잘못되었으며 해당 폴백은 단지 호환성 쇼(compatibility theater)에 불과했을 것입니다.

이미 스킬(skills), 서브 에이전트(subagents), 플러그인(plugins)을 사용하여 Claude Code를 운영하고 있다면, 파일 컨벤션 자체보다 그 안에 무엇을 넣느냐가 더 중요합니다. Claude Code를 일상적인 도구로 사용하기가 실제 출력 품질을 향상시키는 설정 선택 사항들을 다루고 있습니다. 그리고 만약 Claude Code의 내부적인 출력 변화를 추적해 왔다면, 모델이 변수라고 가정하기 전에 품질 보고서 분석을 읽어볼 가치가 있습니다.