Claude Code AGENTS.md 지원: CLAUDE.md와 함께 사용하는 방법

Claude Code가 AGENTS.md를 지원하기 시작한 버전은 v2.1.277입니다. CLAUDE.md가 없는 프로젝트에서는 Claude Code가 이제 AGENTS.md를 프로젝트 지침으로 읽어옵니다. import, 심볼릭 링크, 별도 설정이 전혀 필요하지 않습니다. 저장소에 두 파일이 모두 있으면 Claude는 CLAUDE.md만 읽으며, /config에서 Project instructions 설정을 바꿔야 두 파일을 모두 불러옵니다.

팀에서 여러 코딩 에이전트를 섞어 쓴다면, Codex와 Cursor가 이미 읽고 있는 그 AGENTS.md 하나로 이제 Claude Code까지 제어할 수 있습니다. 이 가이드에서는 파일 우선순위, 마이그레이션 방법, 그리고 Apidog CLI로 모든 에이전트가 API를 테스트하도록 가르치는 AGENTS.md 작성법을 다룹니다.

Claude Code에서 AGENTS.md란 무엇인가?

AGENTS.md는 코딩 에이전트를 위한 지침을 담은 일반 Markdown 파일입니다. 빌드 명령어, 테스트 명령어, 코드 스타일, 프로젝트 규칙 등이 여기에 들어갑니다. v2.1.277부터 Claude Code는 내장 플러그인을 통해 이 파일을 읽기 때문에, 다른 에이전트를 위해 구성된 저장소도 추가 파일 없이 Claude Code에서 바로 동작합니다. 필수 필드나 특별한 문법도 필요하지 않습니다.

이 포맷 자체는 오픈입니다. AGENTS.md 공식 사이트는 이를 "코딩 에이전트를 안내하기 위한 간단하고 개방된 포맷"이라고 소개하며, 60,000개가 넘는 오픈소스 프로젝트가 사용하고 있고 현재는 Linux Foundation 산하 Agentic AI Foundation이 관리하고 있습니다. OpenAI Codex와 Cursor는 모두 AGENTS.md 지원을 문서화해 왔고, Claude Code는 이번 릴리스까지 유일하게 빠져 있던 사례였습니다.

이 포맷이 처음이라면 API 개발 팀을 위한 AGENTS.md 파일 작성법부터 시작해 보세요.

공식 Claude Code 변경 로그에서 확인할 수 있는 릴리스 이력은 다음과 같습니다:

이 기능을 사용하기 전에 먼저 claude --version으로 버전을 확인하세요. 2.1.277 미만 버전에서는 Claude Code가 CLAUDE.md 파일만 읽습니다.

CLAUDE.md vs AGENTS.md: 어떤 파일이 우선하나?

기본값은 CLAUDE.md가 우선입니다. Claude Code는 작업 디렉터리와 그 상위 디렉터리 어디에도 CLAUDE.md가 존재하지 않을 때만 AGENTS.md를 읽습니다. Claude Code 메모리 문서는 다음 세 가지 경우를 설명합니다:

이 검사에서 모든 파일이 해당되는 것은 아닙니다. 다음 세 가지가 AGENTS.md 로드를 차단합니다:

• 작업 디렉터리 또는 상위에 있는 CLAUDE.md
• 작업 디렉터리 또는 상위에 있는 .claude/CLAUDE.md
• 작업 디렉터리 또는 상위에 있는 CLAUDE.local.md

다음 파일들은 차단하지 않으며 AGENTS.md와 함께 계속 로드됩니다: ~/.claude/CLAUDE.md에 있는 사용자 파일, 조직이 관리하는 CLAUDE.md, .claude/rules/ 아래의 파일들입니다.

CLAUDE.local.md 함정을 주의하세요. 커밋하지 않을 개인 메모용으로 하나 만드는 순간, Claude는 팀의 AGENTS.md를 읽지 않습니다.

Claude Code가 무엇을, 언제 로드하는가

아무것도 차단하지 않는다면 Claude Code는 다음을 읽습니다:

1. 세션 시작 시: 작업 디렉터리와 그 상위 디렉터리에 있는 모든 AGENTS.md와 .claude/AGENTS.md. 대화형 세션에서는 no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md 같은 메시지가 출력됩니다.
2. 하위 디렉터리에서: Claude가 Read 도구로 해당 폴더의 파일을 열었고 그 폴더에 자체 CLAUDE.md가 없을 때, 해당 하위 디렉터리의 AGENTS.md를 읽습니다.
3. Import: AGENTS.md 안의 @path import는 확장되며, claudeMdExcludes 패턴이 적용됩니다.

Claude Code는 AGENTS.local.md, AGENTS.override.md, .agents/ 아래의 어떤 파일도 읽지 않습니다. AGENTS.override.md를 문서화하고 있는 Codex와 저장소를 공유한다면 이 점을 염두에 두세요.

Claude Code가 로드하는 지침 파일을 변경하는 방법

세션에서 /config를 입력하고 Project instructions를 네 가지 값 중 하나로 설정하세요:

에이전트를 섞어 쓰는 대부분의 팀이라면 claude-md-and-agents-md 설정이 적합합니다. 개인적인 CLAUDE.local.md는 그대로 유지하면서 공유된 AGENTS.md도 로드합니다.

설정 파일에서 지정할 수도 있습니다. Claude Code는 이 항목을 ~/.claude/settings.json, --settings 파일 또는 관리 설정에서 읽으며, 프로젝트 및 로컬 설정 파일에서는 무시합니다:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

v2.1.285 이전에는 플러그인 ID가 agents-md@builtin이었습니다. 2.1.285부터는 두 ID 모두 인식하므로, 구버전 설치 환경과 설정 파일을 공유한다면 기존 ID를 사용하세요. 변경 사항은 다음 메시지부터 적용됩니다.

/config에 Project instructions 항목이 보이지 않는다면 해당 세션에서는 AGENTS.md를 로드할 수 없습니다. 2.1.277 미만 버전을 쓰고 있거나, /plugin으로 내장 플러그인을 비활성화했거나, 업그레이드 후 첫 세션인 경우입니다(다음 세션부터는 정상 동작합니다).

기존 AGENTS.md 우회 방법 마이그레이션하기

이번 릴리스 이전에 많은 팀이 AGENTS.md를 Claude Code에 수동으로 연결해 사용했습니다. 공식 문서가 권장하는 조치는 다음과 같습니다:

팀에 여전히 2.1.277 미만 버전을 쓰는 사람이 있다면 @AGENTS.md import는 유지하세요. 모든 버전에서 동작하는 유일한 구성 방식입니다.

Import와 심볼릭 링크 중 무엇을 쓸까?

공유 파일 위에 Claude 전용 규칙을 추가해야 한다면 import를 사용하세요. Claude는 import된 파일을 먼저 읽은 후 나머지 내용을 읽습니다:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Claude 전용 내용이 필요 없다면 심볼릭 링크로도 충분합니다:

ln -s AGENTS.md CLAUDE.md

주의할 점 두 가지: Claude의 Edit과 Write 도구는 심볼릭 링크를 통한 쓰기를 지원하지 않으며, Windows의 Git은 core.symlinks가 켜져 있지 않으면 커밋된 심볼릭 링크를 한 줄짜리 텍스트 파일로 체크아웃합니다. 팀원 중 Windows 사용자가 있다면 import를 선택하세요.

어느 쪽이든 다음 세션에서 /context all을 실행해 CLAUDE.md가 Memory files 아래에 표시되는지 확인하세요.

Codex, Cursor, Claude Code를 위한 하나의 AGENTS.md

이 기능의 핵심 가치는 단일 진실 공급원(single source of truth)입니다. 빌드 명령어, 테스트 명령어, 컨벤션을 저장소 루트의 AGENTS.md에 넣으면 Codex, Cursor, Claude Code가 모두 이를 읽습니다.

실무에서 통하는 구성 방식은 다음과 같습니다:

• 루트의 AGENTS.md: 모든 에이전트에게 필요한 내용 전부. 명령어, 폴더 구조, 스타일 규칙, 건드리면 안 되는 항목.
• 큰 하위 폴더의 AGENTS.md: 해당 폴더에만 적용되는 규칙. 예: services/payments/AGENTS.md. Claude Code는 그 폴더의 파일을 읽을 때 이를 필요에 따라 로드합니다.
• 선택적인 CLAUDE.md: 계획 모드나 훅처럼 Claude 전용 동작이 필요할 때만. 첫 줄은 @AGENTS.md로 시작하세요.

한 가지 주의점: 설정을 통해 로드된 AGENTS.md는 InstructionsLoaded 훅을 발동하지 않고, --add-dir 디렉터리에서도 로드되지 않습니다. 이 중 하나에 의존한다면 @AGENTS.md import 방식을 사용하세요.

AGENTS.md에서 Apidog CLI로 API 테스트를 가르치기

API 테스트 규칙을 한 번만 작성해 두면, 어떤 에이전트가 저장소를 열든 같은 방식으로 테스트를 실행합니다. Apidog CLI는 에이전트가 읽을 수 있는 구조화된 JSON 출력을 제공하므로, 전체 루프가 터미널 안에서 유지됩니다.

먼저 머신별로 한 번 설정하세요:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

간단한 방법도 있습니다. 에이전트에게 "Read https://apidog.com/apidog-cli-installation-guide.md and set up Apidog CLI"라고 지시하세요. 이 가이드는 에이전트를 위해 작성된 문서로, 설치, 로그인, 스킬 설정까지 다룹니다.

그다음 AGENTS.md에 다음과 같은 섹션을 추가하세요:

## API testing (Apidog CLI)

- Apidog project ID: 123456. Staging environment ID: 7890.
- Never build Apidog JSON payloads from memory. Run
  `apidog cli-schema get <key>` first, then
  `apidog cli-schema validate <key> --file <path>`, and write only after it passes.
- After changing any handler under `src/routes/`, find its endpoint with
  `apidog endpoint list --project 123456` and its cases with
  `apidog test-case list --project 123456 --endpoint <endpointId>`.
- If a route has no test case, create one with
  `apidog test-case create --project 123456 --file case.json`.
- Run cases with
  `apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json`
  and summarize every failure before you say the task is done.
- Do not edit or delete endpoints in Apidog unless the task asks for it.

이제 하나의 프롬프트만으로 Claude Code, Codex, Cursor 어디에서든 작업이 진행됩니다:

I changed POST /orders to require a currency field. Update the Apidog test
case for it and run it against staging, following AGENTS.md.

에이전트는 여러분의 규칙에 따라 다음과 같은 명령어를 실행합니다:

apidog endpoint list --project 123456
apidog test-case list --project 123456 --endpoint <endpointId>
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123456 --file case.json
apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json

위의 모든 플래그는 Apidog CLI 2.2.12의 apidog <cmd> --help에서 확인한 것입니다. 같은 apidog run 명령에 -r junit을 붙이면 CI에 바로 넣을 수 있고, --upload-report를 사용하면 실행 요약이 앱으로 전송되어 팀 전체가 확인할 수 있습니다. Claude Code 측의 자세한 내용은 Claude Code에서 Apidog CLI 사용법을, Codex 사용자는 Codex에서 Apidog CLI 사용법을 참고하세요. Apidog Free는 최대 4명까지 사용할 수 있어 소규모 팀도 오늘 바로 시도해 볼 수 있습니다.

문제 해결: AGENTS.md가 로드되지 않을 때

1. 경로에 CLAUDE.md가 있는지 확인하세요. 작업 디렉터리 또는 상위에 있는 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md는 기본적으로 우선합니다. ~/.claude/CLAUDE.md는 해당되지 않습니다.
2. 버전을 확인하세요. claude --version을 실행하세요. 2.1.277 이상이 필요하고, Bedrock, Vertex AI, Foundry, 게이트웨이 사용 시 또는 텔레메트리가 꺼져 있을 때는 2.1.281 이상이 필요합니다.
3. 설정을 확인하세요. /config를 열어 Project instructions가 claude-md나 managed-only로 되어 있지 않은지 확인하세요.
4. 로드 여부를 확인하세요. /memory를 실행하고 목록에 AGENTS.md 경로가 있는지 확인하세요.

자주 묻는 질문

Claude Code가 이제 AGENTS.md를 읽나요? 네, v2.1.277부터 읽습니다. 작업 디렉터리 및 상위에 CLAUDE.md가 없으면 Claude Code가 AGENTS.md를 프로젝트 지침으로 자동 읽어옵니다.

CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code는 무엇을 사용하나요? 기본값은 CLAUDE.md만 사용합니다. /config에서 Project instructions를 claude-md-and-agents-md로 설정하면 두 파일을 모두 로드하며, 이때 CLAUDE.md가 먼저 읽힙니다.

@AGENTS.md를 import하는 CLAUDE.md를 삭제해야 하나요? 삭제할 필요가 없습니다. 이 import로 인해 AGENTS.md가 두 번 로드되는 일은 없고, 2.1.277 미만 버전을 쓰는 팀원에게도 여전히 필요합니다. 파일에 다른 내용이 전혀 없고 모든 팀원이 업그레이드를 마쳤을 때만 삭제하세요.

Claude Code도 Codex처럼 AGENTS.override.md를 읽나요? 아니요. Claude Code는 AGENTS.override.md, AGENTS.local.md, .agents/ 아래의 모든 파일을 무시합니다.

AGENTS.md는 Amazon Bedrock이나 Google Vertex AI에서도 동작하나요? 네, v2.1.281부터 동작합니다. Bedrock, Vertex AI, Foundry, 게이트웨이 환경이나 텔레메트리가 꺼진 상태의 이전 버전에서는 CLAUDE.md만 읽으므로, 그런 경우 @AGENTS.md import를 사용하세요.