바뀐 것: CLAUDE.md가 없으면 AGENTS.md를 대신 읽습니다

AGENTS.md는 코딩 에이전트에게 주는 프로젝트 설명서입니다. 어떤 폰트를 쓰는지, 클래스 이름은 어떻게 붙이는지, 배포는 어디로 하는지 같은 규칙을 마크다운으로 적어 둡니다. agents.md 공식 사이트에는 Cursor, OpenAI Codex, Google Gemini CLI와 Jules, GitHub Copilot 코딩 에이전트, Windsurf, Zed 등 20종이 넘는 도구가 지원 도구로 올라 있고, GitHub에서 이 파일을 쓰는 오픈소스 프로젝트는 6만 개가 넘습니다. Claude Code만 자기 파일인 CLAUDE.md를 따로 고집해 왔는데, 2.1.277에서 AGENTS.md도 읽게 됐습니다. 세션을 시작할 때 한 번 읽는 방식은 CLAUDE.md와 같습니다. 단, Amazon Bedrock, Google Vertex AI, Microsoft Foundry를 거쳐 Claude Code를 쓰는 환경에서는 아직 지원하지 않습니다.

놓치기 쉬운 점: '상위 폴더'까지 봅니다

Claude Code 공식 문서에 따르면 기본값은 "CLAUDE.md 또는 AGENTS.md" 중 하나만 읽습니다. 작업 폴더나 그 위 폴더에 CLAUDE.md(또는 CLAUDE.local.md)가 있으면 CLAUDE.md만 읽고, AGENTS.md는 건너뜁니다. 에이전시 작업 폴더는 대개 맨 위에 공통 CLAUDE.md를 두고, 그 아래에 클라이언트별 폴더를 만듭니다. 이 구조에서 클라이언트 폴더에 AGENTS.md만 새로 만들어 두면 Cursor와 Codex는 그 파일을 읽지만, Claude Code는 상위의 CLAUDE.md를 찾았기 때문에 AGENTS.md를 읽지 않습니다. 도구마다 다른 규칙으로 작업하게 되는데, 어느 쪽에서도 경고가 나오지 않습니다. 파일을 만든 뒤에는 Claude Code에게 "지금 읽은 프로젝트 지침 파일 목록을 알려 달라"고 한 번 물어서 확인하는 편이 안전합니다.

해결 방법 세 가지: 가져오기, 설정 변경, 파일 정리

첫째, 공식 문서가 권하는 방법은 CLAUDE.md 맨 위에 @AGENTS.md 한 줄을 넣는 것입니다. Claude Code가 AGENTS.md를 먼저 읽고 그 아래 CLAUDE.md 내용을 이어서 읽습니다. 공통 규칙은 AGENTS.md에, 스킬이나 훅처럼 Claude에만 해당하는 내용은 그 아래에 둡니다. 설정을 바꾸지 않아도 되고, 지침 파일을 읽을 때 실행되는 훅(InstructionsLoaded)도 평소처럼 동작합니다.

둘째, /config의 'Project instructions' 항목을 바꾸는 방법입니다. 선택지는 네 가지입니다. 기본값인 CLAUDE.md 또는 AGENTS.md(claude-md-or-agents-md), 둘 다 읽기(claude-md-and-agents-md), CLAUDE.md만 읽기(claude-md), 조직 관리 지침만 읽기(managed-only)입니다. 둘 다 읽기로 바꾸면 폴더마다 CLAUDE.md를 먼저, AGENTS.md를 그다음에 읽습니다. 다만 이 경로로 읽은 AGENTS.md에는 InstructionsLoaded 훅이 실행되지 않습니다.

셋째, CLAUDE.md를 없애고 AGENTS.md 하나만 두는 방법입니다. 가장 단순하지만 CLAUDE.md에 쌓아 둔 Claude 전용 설정을 다른 곳으로 옮겨야 합니다. 이미 CLAUDE.md를 많이 써 온 작업 폴더라면 첫째 방법이 바꿀 것이 가장 적습니다.

제작자 폴더에 적용하기: 클라이언트마다 AGENTS.md 한 장

누끼토끼는 아임웹·식스샵·카페24 작업을 하면서 Claude Code, Cursor, Codex를 한 작업 폴더에서 번갈아 씁니다. 그동안은 폰트, CSS 클래스 접두사, 이탤릭 금지처럼 똑같은 규칙을 CLAUDE.md와 Cursor 규칙 파일에 각각 적고 두 곳을 따로 고쳐 왔습니다. 이제는 클라이언트 폴더마다 AGENTS.md 한 장에 브랜드 컬러, 폰트, 클래스 규칙, 배포 경로, 건드리면 안 되는 파일을 적어 두면 됩니다. agents.md 규약은 폴더 안에서 가장 가까운 AGENTS.md를 우선하도록 정하고 있어서, 클라이언트별 규칙을 따로 두는 폴더 구조와 잘 맞습니다. 이 규칙은 코드 작업뿐 아니라 클라이언트에게 결과물을 넘길 때도 쓸 수 있습니다. AGENTS.md를 함께 넘기면, 나중에 다른 AI 도구로 사이트를 고치는 사람도 같은 규칙으로 작업을 시작할 수 있습니다.

Claude Code 2.1.277부터 여러 AI 도구가 하나의 규칙 파일을 함께 쓸 수 있게 됐습니다. 다만 기본 설정에서는 CLAUDE.md가 있으면 AGENTS.md를 읽지 않으니, CLAUDE.md 맨 위에 @AGENTS.md 한 줄을 넣는 것부터 시작하시길 권합니다. 파일을 만든 뒤에는 실제로 어떤 지침 파일을 읽었는지 한 번 확인해야 합니다.

누끼토끼가 운영하는 Claude Code 강의와 칼럼에서 클라이언트 폴더 구조, 규칙 파일 설계, 무인 자동화 운영 방식을 실제 작업 기준으로 계속 다루고 있습니다.