Claude Code AGENTS.md 사용법: CLAUDE.md 우선순위와 프로젝트 지침 설정

같은 저장소를 여러 AI 코딩 도구로 작업한다면 “테스트는 어떤 명령으로 돌리는지”, “자동 생성 파일은 어디인지”, “변경하면 안 되는 경로는 무엇인지”를 도구마다 다시 적게 됩니다. AGENTS.md는 이런 공통 프로젝트 지침을 한곳에서 관리할 때 쓰기 좋습니다. Claude 전용 설명은 CLAUDE.md에 남기고 공통 규칙만 공유하는 구성도 가능합니다.

Claude Code는 v2.1.277 릴리스에서 AGENTS.md 지원을 발표했습니다. 다만 발표 버전과 모든 실행 환경의 활성화 시점은 같다고 볼 수 없습니다. 2026년 10월 2일 격리 실험에서는 2.1.277이 AGENTS.md를 초기 요청에 넣지 않았고, 설치된 2.1.285와 당시 npm-current 2.1.287에서는 넣었습니다.

또 하나 알아둘 점은 기본 동작입니다. 현재 작업 폴더나 상위 경로에 CLAUDE.md, .claude/CLAUDE.md 또는 CLAUDE.local.md가 있으면 AGENTS.md를 자동으로 함께 읽지 않습니다. 두 종류를 모두 쓰려면 로딩 모드를 선택하고 실제 적용 여부까지 확인해야 합니다.

AGENTS.md에 무엇을 적을까

매번 설명하는 저장소 규칙부터 적습니다. “좋은 코드를 작성해”보다 작업자가 확인할 수 있는 문장이 낫습니다.

다음은 작성 예시입니다. 실험에서 사용한 지시나 제품 출력은 아닙니다.

# 프로젝트 지침

## 검증
- 변경한 기능과 관련된 테스트를 실행한다.
- 빌드 명령은 package.json의 scripts를 확인한다.

## 변경 범위
- 자동 생성 파일을 직접 수정하지 않는다.
- 새 의존성을 추가하면 목적을 설명한다.
- 요청하지 않은 이미지 교체는 하지 않는다.

## 설명
- 최종 답변에는 변경 이유와 검증 결과를 간단히 적는다.

공통 지침에는 실제 저장소의 명령과 경로를 넣으세요. Claude에서만 필요한 기능 설명까지 공통 파일로 옮기면 다른 도구에서 의미가 흐려질 수 있습니다. 파일을 합치기 전에 공통 규칙과 도구별 규칙을 나누는 것이 먼저입니다.

지원 발표와 실제 활성화 구분하기

공식 2.1.277 릴리스는 CLAUDE.md가 없는 프로젝트에서 AGENTS.md를 대신 읽고, /config의 Project instructions에서 바꿀 수 있다고 안내합니다. 당시 발표에는 Bedrock·Vertex·Foundry는 아직 제외라고 명시돼 있습니다. 이 제한을 현재 모든 버전의 제한으로 확대해서 읽으면 안 됩니다. 공식 릴리스

아래는 모델의 답변이 아니라 Claude Code가 실제로 보낸 초기 요청을 비교한 결과입니다.

2.1.277 바이너리에는 새 옵션과 기본값이 들어 있었지만, 요청 캡처에서는 관련 설정이 효과를 내지 못했습니다. 내장 기능 활성화 조건인 tengu_agents_md_mod가 해당 실행에서 꺼져 있거나 이용할 수 없었던 상황과 일치합니다. 이 조건의 영향으로 추정할 수는 있지만 원인을 확정한 것은 아닙니다.

이번 비교로 정확한 활성화 릴리스를 찾을 수는 없습니다. 관찰한 실행에서는 2.1.277 이후, 늦어도 설치된 2.1.285에서 활성화됐다는 범위까지만 확인했습니다. “2.1.277 설치만 하면 모두 된다”거나 “2.1.285에서 처음 생겼다”는 설명은 둘 다 근거를 넘습니다.

실제로 사용할 때는 현재 제공되는 버전으로 업데이트한 뒤 새 세션에서 확인하세요. 설치 경로가 여러 개라면 먼저 어떤 실행 파일을 쓰는지 살핍니다.

command -v claude
claude --version
claude update

설치 방식부터 헷갈린다면 Claude Code 설치 가이드에서 시작하면 됩니다. 2.1.287은 이 글의 검증 당시 npm-current이며, 이후에도 최신 버전이라는 뜻은 아닙니다.

기본값은 CLAUDE 계열 우선 선택

현재 기본 모드는 claude-md-or-agents-md입니다. 실험에서 활성화가 확인된 두 버전은 다음처럼 동작했습니다.

여기서 “우선순위”는 우선 어떤 파일을 선택해 로딩하는가의 문제입니다. 기본 모드는 CLAUDE 계열을 읽은 뒤 AGENTS.md로 보완하는 방식이 아닙니다. 현재 작업 폴더나 상위 경로에 이 세 종류 중 하나가 있으면 AGENTS.md의 자동 fallback이 일어나지 않습니다.

특히 CLAUDE.local.md가 놓치기 쉽습니다. 개인 설정을 넣으려고 이 파일 하나를 추가했는데, 팀이 공유하는 AGENTS.md가 초기 컨텍스트에서 빠질 수 있습니다. 이 조합도 실제 캡처에서 확인됐습니다.

로딩 흐름을 설명하는 개념도이며 실제 제품 UI가 아닙니다. 기본 모드에서는 CLAUDE.local.md도 AGENTS.md fallback을 막습니다. 이미지를 누르면 확대할 수 있습니다.

공식 문서상 선택 검사는 현재 폴더와 상위 경로의 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md를 포함합니다. 사용자 ~/.claude/CLAUDE.md와 관리 지침, .claude/rules/는 이 fallback을 막는 파일이 아닙니다. 하위 폴더 지침은 해당 파일을 읽을 때 로딩될 수 있습니다. 공식 메모리 문서

따라서 루트만 보고 판단하기보다 Claude를 시작한 폴더와 그 위의 경로까지 확인하세요. AGENTS.md를 보완하려고 만든 개인 파일이 오히려 공통 지침을 빠뜨리는 구성이라면 함께 읽기 모드가 맞습니다.

instructionFiles 네 가지 모드

파일을 합치기 전에 원하는 구성을 고릅니다. 아래 초기 요청 결과는 2.1.285와 2.1.287에서 동일했습니다.

managed-only의 공식 범위는 시작 시 관리 CLAUDE.md와 auto memory만 남기는 것입니다. 사용자·프로젝트·로컬 지침과 rules, AGENTS는 제외하지만, 이후 하위 폴더의 CLAUDE.md나 rules는 읽힐 수 있습니다. 모든 파일 읽기를 차단하는 보안 모드가 아닙니다. 공식 모드 설명

네 모드의 차이를 정리한 개념도이며 실제 제품 UI가 아닙니다. managed-only 그림은 시작 시 로딩 범위를 나타내며, 이후 파일 접근 전체를 차단한다는 뜻은 아닙니다.

설정 JSON과 저장 위치

두 종류를 함께 읽는 정확한 설정은 다음과 같습니다. 실험에서도 이 구조를 명시적인 --settings 파일로 전달했습니다.

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

다른 모드를 쓰려면 instructionFiles의 문자열만 앞의 표에 있는 값으로 바꿉니다. 기존 설정이 있다면 파일 전체를 덮어쓰지 말고 pluginConfigs 아래에 병합하세요.

공식 문서는 이 옵션을 사용자·관리 설정 또는 --settings 파일에서 받으며, 프로젝트·로컬 설정에서는 무시한다고 명시합니다. 공식 설정 안내

예를 들어 위 JSON을 별도 instruction-settings.json에 저장했다면 다음처럼 시작할 수 있습니다.

claude --settings ./instruction-settings.json

“Project instructions”라는 이름 때문에 저장소의 .claude/settings.json에 넣기 쉽지만, 프로젝트 지침을 고르는 옵션이라는 뜻이지 프로젝트 설정에서 허용된다는 뜻은 아닙니다. 사용자 설정을 바꾸면 다른 저장소에도 영향을 줄 수 있으므로 선택한 모드를 기록해 두세요.

구형 옵션인 projectInstructions도 비교했습니다. 활성화된 두 버전에서 agents-fallback은 새 기본 모드와, both는 함께 읽기 모드와 같은 결과였습니다. 다만 2.1.276과 2.1.277의 격리 실행에서는 구형 설정을 지정해도 AGENTS.md가 들어오지 않았습니다. 새로 설정한다면 네 가지 instructionFiles 값으로 통일하는 편이 관리하기 쉽습니다.

/config와 실제 로딩 확인

대화형 설정은 /config의 Project instructions에서 선택합니다. 변경 후에는 새 세션으로 다시 확인하는 편이 비교하기 쉽습니다. 공식 설정 안내

아래 명령은 터미널 셸이 아니라 Claude Code 대화 안에서 입력합니다.

/config
/context
/context all
/memory

/context all은 지시 파일 본문을 그대로 보여주는 요청 캡처 명령이 아닙니다. 컨텍스트 구성 확인에 쓰고, 실제 파일 내용은 별도로 열어 비교하세요. 공식 저장소 변경 이력도 /context와 /context all의 상세 항목 및 토큰 표시를 다룹니다. 공식 CHANGELOG

파일이 있다고 해서 로딩됐다고 가정하지 마세요. /context의 Memory files에서 선택한 모드에 맞는 파일이 로딩됐는지 확인합니다. /memory에는 아직 없는 파일의 위치도 표시되므로, 목록에 있다는 사실만으로 로딩을 판단하면 안 됩니다. 공식 메모리 문서

함께 읽는 순서와 충돌은 별개

함께 읽기 모드의 실측 순서는 다음과 같습니다.

CLAUDE.md → CLAUDE.local.md → AGENTS.md

이는 초기 요청의 한 <system-reminder> 블록 안에 세 파일의 식별 문구가 나열된 순서입니다. 이 블록을 시스템 프롬프트와 혼동하거나, “마지막 AGENTS.md가 앞의 모든 지시를 덮어쓴다”고 해석하면 안 됩니다.

예를 들어 CLAUDE.local.md에는 “테스트를 생략한다”, AGENTS.md에는 “항상 테스트한다”라고 쓰여 있다면 둘 다 모델에 전달될 수 있습니다. 순서에 기대기보다 하나의 일관된 규칙으로 고치세요. 무엇이 공통 정책이고 어떤 조건에서 예외를 허용하는지 같은 파일 안에서 명확하게 적는 편이 낫습니다.

오래된 명령이나 상충 지시가 많다면 Claude Code /doctor prompt-audit 사용법에 나온 감사 절차로 점검할 수 있습니다. 로딩 확인과 지시문 정리는 따로 진행하세요. 파일이 들어갔다는 사실만으로 지시의 품질까지 보장되지는 않습니다.

격리 실험은 어떻게 확인했나

“AGENTS.md의 규칙을 말해 봐”라고 실제 모델에 물으면 로딩 여부와 모델의 기억·준수 여부가 섞입니다. 이번 실험은 파일마다 구별되는 식별 문구를 넣고, 모델에 보낼 요청 본문에 그 문구가 있는지 확인했습니다.

각 사례는 독립된 HOME, CLAUDE_CONFIG_DIR, settings 파일과 Git 저장소를 사용했습니다. 실제 인증키 대신 의도적으로 가짜 키를 넣고, ANTHROPIC_BASE_URL을 로컬 모의 Anthropic SSE 서버로 연결했습니다. 서버는 정확한 /v1/messages 요청을 저장하고 고정 응답을 반환했습니다.

버전, 기본 모드, 구형 모드, 새 네 모드와 파일 조합을 비교했습니다. 2.1.276은 별도의 세션 제목 요청도 보냈으므로 더 큰 본 추론 요청을 골라 분석했고, 2.1.277 이후 사례에서는 추론 요청이 하나씩 캡처됐습니다.

이 방식은 어떤 지침이 초기 요청에 들어갔는지를 직접 확인합니다. 실제 모델이 충돌을 어떻게 해결하는지, 하위 경로의 모든 지침이 언제 로딩되는지, 모든 계정·프로바이더에서 같은지까지 증명하지는 않습니다. 그래서 버전별 결과와 기능 활성화 추정도 이번 격리 실행의 범위로 한정합니다.

AGENTS.md가 안 읽힐 때

먼저 현상을 두 가지로 나눕니다. 파일이 컨텍스트에 없는 것인지, 파일은 들어갔지만 지시를 따르지 않는 것인지에 따라 확인할 곳이 다릅니다.

현재 공식 문서는 2.1.277 이전 버전, 내장 agents-md 플러그인을 끈 세션, 2.1.276 이하에서 업그레이드한 직후의 일부 첫 세션을 직접 로딩 예외로 안내합니다. 또한 2.1.281 이전에는 Bedrock이나 텔레메트리를 끈 환경 등 일부 세션에서 CLAUDE 계열만 읽었다고 설명합니다. /config에 항목이 없다면 버전과 /plugin 상태를 확인하고, 업그레이드 직후라면 새 세션에서 다시 확인하세요. 공식 예외 안내

파일을 새로 만드는 것으로 해결하려고 서두르지 마세요. 연결용 CLAUDE.md를 추가하면 기본 fallback의 조건도 달라집니다. 기존 파일과 설정을 먼저 확인한 다음, 직접 로딩을 쓸지 import를 유지할지 결정하는 편이 낫습니다.

기존 CLAUDE.md를 안전하게 이전하기

공통 지침을 AGENTS.md로 옮기더라도 팀원 전체가 같은 버전과 같은 설정을 쓰는 것은 아닙니다. 한 번에 파일을 없애기보다 다음 순서로 확인하세요.

1. CLAUDE.md와 AGENTS.md의 내용을 비교해 공통 규칙과 Claude 전용 규칙을 나눕니다.

2. 팀원의 Claude Code 버전과 직접 로딩 여부를 확인합니다.

3. 두 파일을 유지한다면 함께 읽기 모드를 선택하고 상충 지시를 정리합니다.

4. 기존 import나 연결 구성을 바꾸기 전에 새 세션에서 로딩을 비교하고, InstructionsLoaded 훅·외부 파일 import·추가 디렉터리 지침에 의존하는지 확인합니다.

5. 연결용 파일만 제거할 수 있는지 판단하고, 변경 후 diff와 프로젝트 검증 결과를 확인합니다.

직접 로딩이 확인되지 않은 환경에서는 기존 CLAUDE.md의 명시적인 import를 유지하는 방법이 있습니다.

@AGENTS.md

공식 문서는 이 import를 유지해도 중복 로딩하지 않으며, “AGENTS.md를 읽어라”라는 문장만 적는 것과는 다르다고 설명합니다. 기존 SessionStart 훅이 파일 내용을 출력한다면 직접 로딩과 중복될 수 있습니다. 공식 이전 안내

직접 로딩된 AGENTS.md는 InstructionsLoaded 훅을 실행하지 않습니다. 외부 경로의 @import는 해당 프로젝트에서 이미 승인한 경우에만 로딩되며 승인 창을 띄우지 않습니다.

--add-dir로 넣은 디렉터리도 예외입니다. 다음 환경 변수를 켜도 추가한 디렉터리의 AGENTS.md는 로딩되지 않습니다.

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD

기존 구성에서 이런 기능을 썼다면 연결 파일을 제거하기 전에 확인하세요.

이전할 때는 파일 이름만 바꾸지 말고 도구별 기능과 경로도 확인하세요. Codex·Gemini·Cursor 지침을 가져오는 구체적인 정리 방법은 Claude Code에 다른 도구의 지침 가져오기에서 이어서 볼 수 있습니다.

참고 자료

• Claude Code v2.1.277 공식 릴리스 — AGENTS.md 지원 발표와 당시 프로바이더 제한

• Claude Code 메모리 공식 문서 — fallback, 네 모드, 설정 위치, 로딩 확인과 이전 안내

• anthropics/claude-code 공식 CHANGELOG — 컨텍스트·메모리 명령 관련 변경 이력

버전별 표와 초기 요청 순서는 2026년 10월 2일의 격리 실험 관찰값입니다. 공식 지원 발표와 구분해 읽어 주세요.