Claude Code AGENTS.md 사용법: 여러 코딩 에이전트 지침 하나로 관리하기
Claude Code 2.1.277부터 프로젝트에 CLAUDE.md 가 없으면 AGENTS.md 를 대신 읽을 수 있다. Codex, Cursor, Gemini CLI처럼 AGENTS.md를 쓰는 도구와 Claude Code를 함께 사용하는 팀이라면 비슷한 지침 파일을 두 벌 유지하던 부담을 줄일 수 있는 변화다. 다만 “파일 이름만 바꾸면 모든 환경에서 똑같이 작동한다”는 뜻은 아니다. 어떤 파일이 우선하는지, 하위 폴더 지침이 언제 붙는지, 직접 로드가 지원되지 않는 환경은 무엇인지 알아야 안전하게 옮길 수 있다. 이 글은 2026년 9월 19일 확인한 공식 릴리스·메모리 문서·내장 플러그인 설명을 바탕으로 설정과 이전 방법을 정리한다. 기능은 9월 18일 v2.1.277에 포함됐다. 관련 Hacker News 토론은 확인 시점에 605점과 214개 댓글을 기록했지만, 이는 관심의 근거이지 품질 평가는 아니다. 무엇이 바뀌었나: AGENTS.md가 기본 대체 파일이 됐다 AGENTS.md 는 빌드 명령, 테스트 순서, 코드 스타일, 보안 주의사항처럼 코딩 에이전트가 작업 전에 알아야 할 내용을 적는 일반 Markdown 파일이다. 사람용 소개 문서인 README를 길게 만들지 않으면서 여러 코딩 에이전트가 같은 저장소 규칙을 읽도록 하는 것이 목적이다. AGENTS.md 공개 사이트는 6만 개가 넘는 오픈소스 프로젝트가 이 형식을 사용한다고 안내한다. Claude Code의 새 기본값은 CLAUDE.md 또는 CLAUDE.local.md가 프로젝트 경로에 있으면 기존 파일만 읽고, 둘 다 없을 때 AGENTS.md를 읽는 방식 이다. 따라서 기존 Claude Code 프로젝트의 동작을 갑자기 바꾸지 않으면서, AGENTS.md만 있는 저장소에 들어갔을 때 별도 복사본 없이 지침을 받을 수 있다. 이는 CLAUDE.md 폐지나 완전한 파일 병합이 아니라 ‘우선순위가 있는 대체 읽기’다. CLAUDE.md가 있으면 우선하고, 없을 때 AGENTS....