AI 코딩 도구를 여러 개 사용해 보신 개발자라면 한 번쯤 이런 문제를 겪어보셨을 겁니다.


OpenAI Codex에서는 AGENTS.md, Claude Code에서는 CLAUDE.md, 다른 도구에서는 또 다른 설정 파일을 만들어야 합니다. 내용은 거의 비슷한데 사용하는 AI 도구에 따라 프로젝트 지침 파일을 따로 관리해야 했습니다.


그런데 드디어 변화가 생겼습니다.


Anthropic이 Claude Code에서 AGENTS.md를 공식 지원하기 시작했습니다.


Anthropic의 Claude Code v2.1.277 릴리스 노트에 따르면 2026년 9월 18일 AGENTS.md 지원이 추가됐습니다. 프로젝트에 CLAUDE.md가 존재하지 않을 경우 Claude Code가 AGENTS.md를 프로젝트 지침 파일로 읽습니다. 또한 /config의 Project instructions 설정을 통해 사용할 프로젝트 지침 파일을 변경할 수 있습니다. 다만 현재 이 기능은 Bedrock, Vertex AI, Foundry 환경에는 아직 적용되지 않았습니다.


이 변화는 단순히 “설정 파일 하나를 더 지원한다” 정도의 업데이트가 아닙니다. AI 코딩 에이전트 생태계가 특정 회사의 독자 규칙에서 벗어나 공통된 프로젝트 지침 표준으로 수렴하고 있다는 점에서 상당히 의미가 있습니다.


AGENTS.md가 무엇인가요?

AGENTS.md는 쉽게 설명하면 AI 개발자에게 보여주는 README.md입니다.


일반적인 README.md가 사람에게 프로젝트 사용 방법을 설명하는 문서라면 AGENTS.md는 AI 코딩 에이전트에게 프로젝트에서 지켜야 할 규칙을 알려주는 문서입니다.


예를 들어 다음과 같은 내용을 적을 수 있습니다.

AGENTS.md

- Node.js 24 이상을 사용합니다.
- 패키지 매니저는 pnpm만 사용합니다.
- 새로운 기능을 추가하면 반드시 테스트를 작성합니다.
- src/services 디렉터리에서는 Repository Pattern을 사용합니다.
- DB 스키마를 직접 변경하지 말고 migration 파일을 생성합니다.
- 작업 완료 후 pnpm test를 실행합니다.


Claude Code나 Codex 같은 AI에게 매번 채팅으로 이런 내용을 설명하지 않아도 프로젝트에 AGENTS.md 하나만 넣어두면 AI가 작업 전에 프로젝트의 규칙을 파악할 수 있는 구조입니다.


공식 AGENTS.md 사이트 역시 README는 사람에게 필요한 내용을 간결하게 유지하고, AI 에이전트에 필요한 구체적인 작업 지침은 AGENTS.md에 작성하는 방식을 설명하고 있습니다.


원래 Claude Code에는 CLAUDE.md가 있었습니다


물론 Claude Code에도 오래전부터 비슷한 기능이 있었습니다.


바로 CLAUDE.md입니다.


Claude Code 프로젝트 루트에 CLAUDE.md를 만들면 Claude가 프로젝트를 작업할 때 해당 파일에 적힌 지침을 참고합니다.


문제는 CLAUDE.md가 사실상 Claude 전용 규칙이라는 점입니다.


예를 들어 한 개발팀이 Claude Code와 OpenAI Codex를 함께 사용한다고 가정해 보겠습니다.

기존에는 다음과 같이 파일을 관리하는 경우가 많았습니다.

my-project/
├── CLAUDE.md
├── AGENTS.md
├── package.json
└── src/


두 파일에는 대부분 비슷한 내용이 들어갑니다.

CLAUDE.md
- TypeScript strict mode를 유지한다.
- 테스트를 반드시 작성한다.
- pnpm을 사용한다.

AGENTS.md
- TypeScript strict mode를 유지한다.
- 테스트를 반드시 작성한다.
- pnpm을 사용한다.


처음에는 별문제 없어 보이지만 프로젝트가 커지면 문제가 발생합니다.


한 파일만 수정하고 다른 파일을 수정하지 않으면 AI마다 서로 다른 개발 규칙을 적용할 수 있기 때문입니다.

그래서 개발자 커뮤니티에서는 오랫동안 Claude Code도 AGENTS.md를 지원해 달라는 요구가 있었습니다.


개발자들은 거의 1년 동안 요청해 왔습니다


Anthropic의 Claude Code GitHub 저장소에는 2025년부터 AGENTS.md 지원 요청이 지속적으로 올라왔습니다.


대표적인 요청에서는 Claude Code가 CLAUDE.md만 읽기 때문에 Codex 등 다른 AI 코딩 도구와 함께 사용하는 프로젝트에서 CLAUDE.md와 AGENTS.md를 중복 관리해야 한다는 문제가 제기됐습니다.


2026년 7월에 올라온 또 다른 이슈에서는 최초의 대표적인 AGENTS.md 지원 요청이 4,400개 이상의 추천을 받았다고 언급됐을 정도로 개발자들의 요구가 컸습니다.


당시 개발자들이 사용하던 우회 방법도 있었습니다.


예를 들어 CLAUDE.md에서 AGENTS.md를 읽도록 지시하거나 두 파일을 심볼릭 링크로 연결하는 방식입니다.

CLAUDE.md

Read AGENTS.md before starting any task.


하지만 결국 Claude Code를 위해 별도의 파일을 하나 유지해야 한다는 점은 변하지 않았습니다.

이번 공식 지원으로 이런 불편이 상당 부분 줄어들게 됐습니다.


AGENTS.md는 이미 사실상 업계 표준으로 커지고 있습니다

AGENTS.md의 시작은 OpenAI Codex였습니다.


OpenAI는 Codex가 코딩 규칙, 빌드 절차, 테스트 방법 등 프로젝트별 지침을 예측 가능한 위치에서 찾을 수 있도록 AGENTS.md라는 형식을 만들었습니다.


그런데 이 방식이 여러 AI 개발 도구로 빠르게 확산됐습니다.


OpenAI에 따르면 AGENTS.md는 2025년 8월 공개된 이후 6만 개 이상의 오픈소스 프로젝트에서 채택됐으며 Codex뿐 아니라 Cursor, Gemini CLI, GitHub Copilot, Jules, Devin, Factory, Amp 등의 도구와 프레임워크가 이를 지원하게 됐습니다.


그리고 2025년 12월에는 더욱 중요한 변화가 있었습니다.


OpenAI가 AGENTS.md를 특정 회사의 독점 규격으로 유지하는 대신 Linux Foundation 산하 Agentic AI Foundation, 즉 AAIF에 기부했습니다.


AAIF에는 Anthropic 역시 창립 멤버로 참여하고 있으며 Anthropic의 MCP(Model Context Protocol), OpenAI의 AGENTS.md, Block의 goose가 초기 핵심 프로젝트로 들어갔습니다.


즉 AGENTS.md는 이제 단순한 “OpenAI의 설정 파일”이라기보다 여러 AI 코딩 에이전트가 함께 사용할 수 있는 벤더 중립적인 프로젝트 지침 규격으로 발전하고 있습니다.


이런 상황에서 Claude Code가 AGENTS.md를 지원하지 않는다는 점이 오히려 점점 어색해지고 있었습니다.


Anthropic 역시 AAIF의 창립 멤버인데 정작 자사의 대표적인 AI 개발 도구인 Claude Code가 AGENTS.md를 읽지 못하는 상황이었기 때문입니다.


이번 업데이트로 그 간극이 마침내 줄어들었습니다.


다만 현재 지원 방식에는 중요한 조건이 있습니다


여기에서 한 가지 주의해야 합니다.


현재 Claude Code의 AGENTS.md 지원을 “CLAUDE.md와 AGENTS.md를 모두 자동으로 읽는다”고 이해하면 안 됩니다.


Claude Code v2.1.277의 공식 릴리스 설명은 명확합니다.


프로젝트에 CLAUDE.md가 없을 경우 AGENTS.md를 읽습니다.


즉 기본 동작은 다음에 가깝습니다.

CLAUDE.md 존재
│
├─ YES → CLAUDE.md 사용
│
└─ NO → AGENTS.md 사용

예를 들어 프로젝트에 다음 두 파일이 모두 존재한다고 해서

CLAUDE.md
AGENTS.md

두 파일의 내용이 자동으로 합쳐져 적용된다고 생각하면 안 됩니다.


현재 발표된 기능만 놓고 보면 AGENTS.md는 우선 CLAUDE.md가 없을 때 사용할 수 있는 프로젝트 지침 파일의 성격에 가깝습니다.


이 부분은 향후 Anthropic이 지원 범위를 확대하는지 지켜볼 필요가 있습니다.


앞으로는 AGENTS.md 하나로 프로젝트 규칙을 관리할 수 있을까?


개인적으로 이번 변화에서 가장 중요한 부분은 파일 이름 자체가 아닙니다.


핵심은 AI 에이전트용 프로젝트 컨텍스트의 표준화입니다.


현재 개발 현장에서는 한 프로젝트에 하나의 AI만 사용하는 경우보다 여러 AI 개발 도구를 상황에 따라 함께 사용하는 경우가 늘고 있습니다.


예를 들어

기능 개발 → Claude Code
코드 리뷰 → Codex
IDE 자동완성 → GitHub Copilot
대규모 리팩터링 → Cursor

같은 형태가 가능합니다.


그런데 사용하는 AI마다 프로젝트 규칙 파일까지 따로 관리해야 한다면 상당히 비효율적입니다.


이상적인 구조는 다음과 같습니다.

프로젝트
│
├── README.md
│ └── 사람을 위한 설명
│
└── AGENTS.md
└── AI 에이전트를 위한 설명


그리고 어떤 AI 도구를 사용하더라도 동일한 AGENTS.md를 읽는 것입니다.

AGENTS.md
│
┌──────────┼──────────┐
│ │ │
Claude Code Codex Gemini CLI
│ │ │
└──────────┼──────────┘
│
동일한 프로젝트 규칙


이렇게 되면 개발팀은 AI 도구마다 규칙을 별도로 관리하지 않아도 됩니다.

그리고 특정 AI 서비스에 종속되는 문제 역시 줄어듭니다.


MCP 다음은 AGENTS.md일지도 모릅니다


AI 개발 생태계를 보면 최근 재미있는 흐름이 나타나고 있습니다.


LLM 자체의 성능 경쟁과 동시에 AI 에이전트를 둘러싼 인프라 표준 경쟁이 빠르게 진행되고 있습니다.


AI가 외부 도구와 연결되는 방법에는 Anthropic이 시작한 MCP가 널리 확산됐고, 프로젝트 작업 규칙을 전달하는 방법에서는 AGENTS.md가 빠르게 자리 잡고 있습니다.


Linux Foundation 산하 AAIF 역시 MCP와 AGENTS.md 등을 핵심적인 에이전트 상호운용성 프로젝트로 관리하고 있습니다.


결국 AI 개발 환경도 웹 개발 생태계처럼 점차 역할이 나뉘는 모습입니다.


README.md
→ 사람에게 프로젝트를 설명

AGENTS.md
→ AI에게 프로젝트 작업 규칙을 설명

MCP
→ AI와 외부 도구·데이터를 연결


앞으로 어떤 AI 모델이 가장 뛰어난지를 고르는 것만큼이나 여러 AI 도구가 동일한 프로젝트와 동일한 규칙을 공유할 수 있는가가 중요한 문제가 될 가능성이 높습니다.


그런 관점에서 이번 Claude Code의 AGENTS.md 지원은 작은 릴리스 노트 한 줄처럼 보이지만 의미는 꽤 큽니다.


그동안 Claude Code를 사용하기 위해 별도의 CLAUDE.md를 관리해야 했던 개발자들은 이제 AGENTS.md를 중심으로 프로젝트 규칙을 통합할 수 있는 길이 열렸습니다.


아직은 CLAUDE.md가 존재하면 AGENTS.md를 대신 읽는 구조가 아니고, 일부 클라우드 환경에도 적용되지 않았다는 제한이 있습니다. 따라서 “완전한 AGENTS.md 통합이 끝났다”고 표현하기에는 조금 이릅니다.


그럼에도 방향은 분명해 보입니다.


AI 코딩 도구마다 별도의 설정 파일을 관리하던 시대에서, 하나의 프로젝트 지침을 여러 AI 에이전트가 공유하는 시대로 이동하고 있습니다.


그리고 이번 Claude Code v2.1.277 업데이트는 그 흐름에서 상당히 상징적인 변화라고 볼 수 있겠습니다.