레포 6만 개가 쓰는 파일을 Claude Code가 읽기 시작했다

같은 규칙을 파일 세 개에 적어 둔 팀이 흔하다. CLAUDE.md, AGENTS.md, .cursorrules. 내용은 거의 같은데 도구마다 읽는 파일이 달라서 생긴 중복이다. 2026년 9월 18일 나온 Claude Code 2.1.277이 그중 하나를 줄였다. 프로젝트에 CLAUDE.md가 없으면 AGENTS.md를 읽는다.

AGENTS.md는 OpenAI가 2025년 8월에 내놓은 규격이고 그해 말 Linux Foundation의 Agentic AI Foundation으로 넘어갔다. MCP와 Goose가 같이 간 그 재단이다. 지금 오픈소스 레포 6만 개가 이 파일을 두고 있고 Codex, Copilot, Cursor, Gemini CLI, Jules, Aider, Zed, Windsurf, Devin 등 30개 안팎의 에이전트가 읽는다. 끝까지 자기 이름을 쓰던 쪽이 Claude Code였다.

한 줄 정리

Claude Code가 CLAUDE.md 없는 프로젝트에서 AGENTS.md를 대신 읽으면서 에이전트 지시서가 특정 도구에서 떨어져 나왔다.

병합이 아니라 폴백이다

이 구분이 실무에서 전부다. CLAUDE.md가 있으면 Claude Code는 그쪽만 읽는다. 두 파일의 내용을 합치지 않는다. 이미 CLAUDE.md로 세팅된 레포에서는 어제와 오늘이 똑같다.

이 방식에는 이유가 있다. 이미 CLAUDE.md로 세팅한 레포에서 갑자기 두 파일이 합쳐지면 어제까지 잘 돌던 작업이 오늘 다르게 나온다. 무엇이 바뀌었는지 찾는 데 하루가 든다. 폴백은 지루한 대신 안전하다.

어느 파일을 볼지는 /config의 "Project instructions"에서 바꿀 수 있다. 다만 Bedrock, Vertex, Foundry를 거쳐 쓰는 경로에는 아직 안 들어갔다. 그쪽으로 붙은 팀원은 CLAUDE.md가 계속 필요하다.

함정은 표의 마지막 줄이다

세 번째 줄이 조용히 사고를 만든다. 대표는 Claude Code를 쓰고 개발 담당은 Codex를 쓰는 팀을 생각해 보자. 레포에 두 파일이 다 있고 내용이 8할쯤 같다. 각자 자기 파일만 고친다. 두 달이면 말투 규정이 갈리고 넉 달이면 배포 절차가 갈린다. 아무도 틀린 규칙을 쓰지 않았는데 결과물은 두 종류로 나온다.

지금까지는 이 문제를 우회로 막았다. CLAUDE.md 첫 줄에 @AGENTS.md를 적어 불러오는 방식이다. 우회가 필요 없어진 지금이 오히려 정리하기 좋은 시점이다. 정본을 한 개 정하고 나머지는 지운다. Bedrock을 거치는 팀원이 있으면 CLAUDE.md를 정본으로 남기고 AGENTS.md를 지운다. 없으면 반대로 하면 된다. 둘을 다 살려야 하는 사정이 있을 때만 예전 방식으로 한쪽이 다른 쪽을 불러오게 걸어 둔다.

코드를 안 짜는 팀에도 걸리는 이유

이 파일을 개발 설정으로만 보면 넘어가게 된다. 실제로는 에이전트가 붙는 모든 작업에 걸린다. 지난 1년 동안 이 도구들이 들어간 자리를 보면 코드보다 문서와 표가 많다. 제안서 초안, 고객사별 리포트, 상품 상세 문안, 광고 카피 변형, 주간 정산 시트 정리. 폴더를 열어 파일을 고치는 작업이면 다 같은 규칙 파일을 읽는다.

그래서 문장이 없는 팀에서 사고가 난다. 규칙을 적어 두지 않으면 에이전트는 매번 다르게 판단한다. 같은 고객사 이름을 어떤 문서에서는 줄여 쓰고 어떤 문서에서는 풀어 쓴다. 할인율을 본문에 적을지 각주로 내릴지도 매번 바뀐다. 사람이 하던 시절에는 옆자리에 물어서 맞췄다. 그 질문을 받을 옆자리가 없어진 게 지금 상황이다.

AGENTS.md가 표준이 됐다는 말은 그 규칙을 적어 둘 자리가 정해졌다는 뜻이다. 도구를 바꿀 때마다 파일을 새로 만들 이유가 사라졌으니 이제는 못 적은 게 이유로 남지 않는다.

이름이 표준이 되면 값은 안쪽으로 간다

6만 개 레포가 같은 파일 이름을 쓰는 상황에서 이름 자체에는 우위가 없다. 남는 건 그 안에 적힌 문장이다.

여기서 팀 규모가 아니라 축적이 갈린다. 코딩 컨벤션과 테스트 실행 명령만 적힌 파일은 어느 도구가 읽어도 값이 얇다. 반대로 콘텐츠 팀이라면 톤 규정, 절대 쓰지 않는 표현, 고객사별 호칭, 승인 전에 반드시 사람이 보는 항목이 들어간다. 커머스라면 상품명 표기 원칙과 환불 문구, 리뷰 인용 규칙이 들어간다. 이런 문장은 검색해서 붙일 수 없다. 사고가 한 번 난 다음에 적히는 종류다.

그래서 이 파일은 프롬프트 모음이 아니라 운영 규정에 가깝다. 신입이 읽어도 판단이 서는 문서면 에이전트도 같은 판단을 한다.

위시클레이 관점

6만 개 레포가 같은 이름을 쓰게 된 날, 이식성이라는 이점은 모두에게 동시에 생겼다. 경쟁자도 오늘부터 파일을 그대로 들고 도구를 옮긴다. 이식성이 우위가 아니라 기본값이 된 셈이다.

그다음 갈리는 자리가 파일의 두께다. 3년 동안 "이 경우는 이렇게 처리한다"를 사고가 날 때마다 한 줄씩 적어 온 팀과 어제 만든 팀의 파일은 이름이 같아도 내용이 다르다. 후자는 앞엣것을 복사할 수도 없다. 남의 팀 규정은 우리 고객·우리 실수 이력에 안 맞는다.

이번 주에 30분만 쓰면 되는 일이 하나 있다. 레포를 열어 CLAUDE.md와 AGENTS.md가 동시에 있는지 본다. 있으면 두 파일을 나란히 놓고 diff를 뜬다. 갈라진 줄이 나오면 그게 지난 몇 달 동안 도구별로 다르게 돌던 규칙이다. 정본을 정해 합치고 한쪽을 지운다. Bedrock·Vertex·Foundry 경로를 쓰는 팀원이 있는지도 같이 확인한다. 그 한 명 때문에 CLAUDE.md를 못 지운다면 그 사실을 파일 맨 위에 적어 두는 편이 낫다. 반년 뒤에 다시 헷갈린다.

참고

• Claude Code 2.1.277 릴리스 노트: AGENTS.md 폴백 동작
• AGENTS.md 규격과 이 파일을 읽는 도구 목록
• Anthropic 쪽 설명과 적용 범위를 인용한 메모 (Simon Willison)