Claude Code, 드디어 AGENTS.md 지원: 에이전트 설정 파일 표준화의 마지막 퍼즐

AGENTS.md는 무엇이고, 왜 표준이 됐나?

AGENTS.md는 "에이전트를 위한 README"다. 사람용 README에 넣기엔 잡다한 것들(빌드 명령, 테스트 실행법, 코드 컨벤션, PR 규칙)을 AI 코딩 에이전트가 읽을 수 있게 프로젝트 루트에 두는 마크다운 파일이다. 2025년 중반 OpenAI(Codex)가 주도하고 Google(Jules), Cursor, Sourcegraph Amp, Factory 등이 협력해 만들어졌다.

표준이 된 이유는 단순하다. 도구가 너무 많아졌기 때문이다. Codex, Gemini CLI, Cursor, GitHub Copilot, Zed, Warp, Devin, Windsurf, Aider 등 20개 이상의 도구가 각자 설정 파일을 요구하면, 팀은 같은 내용을 여러 파일에 복붙해야 한다. AGENTS.md는 그 중복을 하나로 모았고, agents.md 공식 사이트 기준 6만 개 이상의 오픈소스 프로젝트가 채택했다. 단 하나의 예외가 있었다. Claude Code. CLAUDE.md라는 자체 파일만 읽었다.

Anthropic은 왜 마지막까지 버텼고, 왜 지금 합류했나?

Claude Code 이슈 트래커의 "Support AGENTS.md"(#6235)는 2025년 8월부터 열려 있던 역대 최대 규모의 피처 리퀘스트였다(커뮤니티 집계 기준 반응 5,200개 이상). 심지어 2026년 8월 17일 한 차례 "워크어라운드를 쓰라"며 닫혔다가, 한 달 만에 정식 지원으로 뒤집혔다.

그 사이 사용자들은 눈물겨운 우회로를 썼다. CLAUDE.md 안에 @AGENTS.md 한 줄만 넣어 임포트하거나, 심볼릭 링크(ln -s AGENTS.md CLAUDE.md)를 걸었다. 윈도우에서는 개발자 모드 없이 링크가 깨지는 문제까지 감수하면서. 컨설팅 회사가 "심링크 거는 법"을 공식 룰 문서로 만들 정도였다면, 표준 부재의 비용이 이미 충분히 증명된 것이다.

CLAUDE.md를 고수하던 Anthropic의 입장에도 논리는 있었다. @임포트, .claude 계층 구조 등 자체 파일만의 기능이 있었다. 하지만 생태계의 답은 명확했다. GeekNews 댓글의 표현을 빌리면 "CLAUDE.md 고집하면 버려진다." 개별 도구의 기능 우위보다 생태계 호환이 이긴 것이다. MCP가 도구 연결의 표준이 됐던 것과 같은 패턴이 설정 파일에서 반복됐다.

에이전트 생태계의 규칙이 다시 확인됐다. 표준은 가장 좋은 규격이 아니라 가장 많이 깔린 규격이 이긴다. 그리고 마지막 홀드아웃의 합류가 표준의 완성 신호다.

AGENTS.md, 그냥 AI에게 만들어달라고 하면 안 되나?

이 글에서 가장 중요한 반전이다. 138개 레포를 대상으로 한 연구에서, LLM이 일괄 생성한 일반적 AGENTS.md 파일은 8개 실험 설정 중 5개에서 오히려 에이전트의 작업 성공률을 떨어뜨렸다. 파일이 있다고 좋은 것이 아니라, 무엇이 적혔는가가 전부다.

이유를 생각해보면 당연하다. LLM이 코드베이스를 훑고 쓴 일반론("이 프로젝트는 TypeScript를 사용합니다. 테스트를 실행하세요.")은 에이전트가 이미 아는 정보에 토큰만 보태는 노이즈다. 반대로 사람이 시행착오 끝에 적은 한 줄("이 레포의 e2e 테스트는 반드시 순차 실행(병렬로 돌리면 DB 락 걸림")은 에이전트가 절대 스스로 알 수 없는 정보다. GeekNews 댓글에서도 같은 통찰이 나왔다)"수동 요약의 가치가 자동화보다 높다."

비판론도 알아둘 가치가 있다. Sonar는 "AGENTS.md는 해결책이 아니라 임시방편"이라고 지적한다. 스키마도 필수 필드도 없는 자유 텍스트라서 강제력이 없고, 코드가 바뀌어도 파일은 낡은 채 남는다는 것이다. 맞는 말이다. 그래서 AGENTS.md는 규정집이 아니라 살아 있는 문서로 관리해야 한다.

팀은 지금 무엇을 하면 되나: 실무 가이드 4가지

순서는 이렇다. ①심링크·복붙 워크어라운드 제거 ②AGENTS.md로 단일화(Claude 전용 기능이 필요하면 CLAUDE.md에 그것만) ③자동 생성 대신 "사고 로그" 방식으로 축적 ④분기마다 낡은 항목 청소.

• 단일화: 여러 도구를 쓰는 팀은 AGENTS.md 하나로 모으고, Claude 전용 설정(@임포트 등)이 필요할 때만 CLAUDE.md를 따로 둔다. 같은 내용의 파일 두 개는 반드시 어긋난다
• 축적 방식: 처음부터 완벽한 파일을 쓰려 하지 말고, 에이전트가 실수할 때마다 그 교정을 한 줄씩 추가한다. "에이전트가 몰라서 틀린 것"만 쌓인 파일이 최고의 AGENTS.md다. JetBrains의 go-modern-guidelines가 정확히 이 원리(에이전트의 체계적 실수를 교정 규칙으로 만든 것)의 대규모 버전이다
• 다이어트(설정 파일도 컨텍스트를 먹는다. 모든 세션에 로드되는 파일인 만큼, 낡은 항목과 일반론은 분기마다 지운다. 컨텍스트는 공짜가 아니다)context-mode류 도구가 존재하는 이유를 기억하라
• 위치 설계: 표준의 관례상 파일은 폴더 단위로 동작하므로, 모노레포라면 루트에 공통 규칙, 하위 디렉터리에 영역별 규칙을 나눠 두는 구성이 자연스럽다

하네스 엔지니어링(Prompt → Context → Harness → Loop)의 언어로 정리하면, AGENTS.md는 Context 단계의 표준 그릇이다. 그릇이 표준화됐으니 이제 경쟁력은 그릇에 무엇을 담느냐로 넘어왔다. 그리고 그 내용물은 자동 생성이 아니라 팀의 축적된 시행착오에서 나온다.