Claude Code가 이제 AGENTS.md를 읽습니다: 2.1.277에서 달라진 점

2026년 9월 18일, Claude Code 2.1.277에 AGENTS.md 지원이 추가되었습니다. 세션과 작업 디렉터리에서 이 기능을 사용할 수 있고, 작업 디렉터리부터 상위 디렉터리까지 어느 곳에도 CLAUDE.md, .claude/CLAUDE.md 또는 CLAUDE.local.md가 없으면 Claude Code는 수동 import 없이 기본적으로 AGENTS.md를 읽습니다. 이전에는 CLAUDE.md에서 @AGENTS.md를 import하거나 CLAUDE.md를 AGENTS.md의 심볼릭 링크로 만들어야 했습니다. 자세한 내용은 여러 에이전트가 함께 사용하는 단일 지침 파일에 관한 글을 참고하세요.

같은 저장소에서 Claude Code와 다른 도구 한두 개를 사용한다면, 선택한 Project instructions 모드에 따라 Claude Code가 읽는 지침 파일이 달라집니다. 아래에서 네 가지 모드의 조건과 기존 설정에서 전환하는 방법을 설명합니다.

도구 설정에 관한 더 많은 자료는 Ailoot 문서에서 확인할 수 있습니다.

버전 2.1.277에서 무엇이 달라졌나요?#

GitHub의 공식 Claude Code 프로젝트 CHANGELOG.md에는 다음과 같이 나와 있습니다.

번역: AGENTS.md 지원이 추가되어 CLAUDE.md가 없는 프로젝트에서 Claude Code가 이제 AGENTS.md를 대신 읽습니다. /config의 “Project instructions”에서 설정을 변경할 수 있습니다(Bedrock, Vertex, Foundry에서는 아직 사용할 수 없음).

이 버전 이전에는 작업 폴더와 상위 디렉터리에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없다는 사실만으로 AGENTS.md가 읽히지는 않았습니다. 명시적 import, 심볼릭 링크 또는 수동 hook이 필요했습니다. 이제 기능을 사용할 수 있으면 에이전트가 파일을 자동으로 불러옵니다.

AGENTS.md 자동 읽기를 막는 파일#

코딩 스타일 설정이 담긴 개인용 ~/.claude/CLAUDE.md가 있어도 Claude Code가 프로젝트의 AGENTS.md를 읽는 데 방해가 되지 않습니다. 하지만 Git에 추가되지 않았고 개인 메모용으로 사용하는 파일이라도 작업 폴더에 CLAUDE.local.md가 있으면 기본 모드에서 AGENTS.md 자동 읽기가 차단됩니다. 명시적 import는 계속 작동합니다. 두 파일을 직접 읽게 하려면 모드를 전환해야 합니다.

Project instructions에서 직접 읽기 모드를 선택했고(아래 “4가지 Project instructions 모드: 어떤 것을 선택할까요?” 참고), 작업 디렉터리와 상위 디렉터리에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없다면 세션 시작 시 Claude Code가 해당 디렉터리의 모든 AGENTS.md와 .claude/AGENTS.md를 읽습니다. 차단 파일이 없는 경우에 대해 문서에는 대화형 세션에 다음과 같은 줄이 표시되는 예가 나와 있습니다.

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

하위 디렉터리의 AGENTS.md는 Claude가 Read 도구로 해당 디렉터리의 파일을 열 때 로드됩니다. claude-md-or-agents-md 모드에서는 그 하위 디렉터리에 자체 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없을 때만 로드됩니다. claude-md-and-agents-md 모드에 대해서 문서는 일반 규칙을 설명합니다. 각 디렉터리에서 CLAUDE.md를 먼저 읽고, 이어서 AGENTS.md를 읽습니다. AGENTS.local.md, AGENTS.override.md, .agents/ 디렉터리 안의 항목은 자동으로 읽히지 않습니다.

프로젝트 맥락이 담긴 지침 파일을 포함해 AI 에이전트의 작업 공간을 설정하는 자료는 Ailoot 문서에서 확인할 수 있습니다.

4가지 Project instructions 모드: 어떤 것을 선택할까요?#

표에 나온 모드별 동작은 Anthropic 문서에 설명되어 있습니다. 오른쪽 열에서는 모드를 선택하는 기준을 안내합니다.

인터페이스를 사용하지 않고 settings.json에서 모드를 선택할 수도 있습니다.

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

Claude Code는 project 및 local 설정에서 이 값을 무시합니다. Anthropic 문서에 따르면 ~/.claude/settings.json, --settings 파일 또는 조직에서 관리하는 설정에 지정할 수 있습니다.

같은 저장소에서 여러 AI 도구가 공유하는 지침 파일을 이미 설정했다면, 2.1.277 이전 버전용 안내에서 @ import가 어떻게 작동하는지 설명합니다. 이 방법은 지금도 사용할 수 있습니다.

/config에 Project instructions가 없는 이유#

먼저 claude --version 명령으로 버전을 확인하세요. 2.1.277보다 낮으면 Claude Code를 업데이트하세요. 버전이 충분히 높은데도 섹션이 나타나지 않으면 위에 나온 다른 이유를 확인하세요. 기능을 사용할 수 없는 동안에는 CLAUDE.md에서 @AGENTS.md를 import하는 방법이 계속 작동하는 대안입니다.

기존 @AGENTS.md import는 어떻게 할까요?#

다음 단계는 기존 설정에 따라 달라집니다. 먼저 이전 섹션의 설명에 따라 세션에서 이 기능을 사용할 수 있는지 확인하세요.

• @AGENTS.md를 import하는 CLAUDE.md. 그대로 둘 수 있습니다. Project instructions 값과 관계없이 Claude Code는 파일을 두 번 읽지 않습니다. CLAUDE.md를 삭제해도 됩니다. import만으로 Claude가 이미 AGENTS.md 내용을 읽을 수 있기 때문입니다. /memory를 통해 import에 따른 로드를 계속 확인하세요. 지침 내용을 Claude에게 직접 물어보는 것은 신뢰도가 낮은 확인 방법입니다.
• AGENTS.md를 읽으라고 말로 요청하는 CLAUDE.md. 이런 요청은 import가 아니며 그 자체로 파일이 로드된다고 보장하지 않습니다. 다른 도구도 CLAUDE.md를 읽도록 유지하려면 해당 문구를 @AGENTS.md import로 바꾸세요. CLAUDE.md를 완전히 삭제하고 claude-md-or-agents-md 모드를 선택하려면, 먼저 CLAUDE.md에만 있는 고유 지침이 없는지, 작업 디렉터리와 상위 디렉터리에 다른 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없는지 확인하세요. 그렇지 않으면 Claude Code는 AGENTS.md 대신 남아 있는 파일을 계속 읽습니다. 삭제한 다음에는 전환이 완료되었는지 확인하세요. 차단 파일이 남아 있지 않으면 대화형 세션에 AGENTS.md loaded라는 줄이 표시됩니다. CLAUDE.md를 유지하고 claude-md-and-agents-md 모드에서 두 파일을 모두 읽는다면 /memory를 확인하세요(버전 2.1.280 이상). Claude에게 직접 물어봐서는 직접 로드와 import를 구분할 수 없습니다.
• AGENTS.md를 가리키는 CLAUDE.md 심볼릭 링크. 그대로 유지할 수 있습니다. 어떤 모드에서도 중복으로 읽히지 않습니다. claude-md-or-agents-md 모드에서 링크를 삭제하기 전에 필요한 지침이 보존되었는지, 작업 디렉터리와 상위 디렉터리에 다른 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없는지 확인하세요. 로드 여부는 같은 방법으로 확인하세요. 차단 파일이 없으면 세션 시작 때 AGENTS.md loaded 줄을 확인하고, 버전 2.1.280 이상에서는 /memory도 확인할 수 있습니다. CLAUDE.md를 유지하고 claude-md-and-agents-md 모드를 사용한다면 Claude에게 직접 묻는 것만으로는 신뢰도가 낮습니다. 오류가 없다는 사실만으로는 로드를 확인할 수 없습니다.
• AGENTS.md 내용을 수동으로 출력하는 SessionStart hook. 파일을 직접 읽으면 이런 hook이 같은 내용을 컨텍스트에 한 번 더 추가합니다. hook이 실행 중일 때 “내 지침에는 무엇이 있지?”라고 물어도 직접 로드를 확인할 수 없습니다. Claude가 hook에서 추가한 텍스트를 바탕으로 답할 수 있기 때문입니다. 다음 순서로 전환하세요.
  1. 기능을 사용할 수 있는지 확인하세요. 버전은 2.1.277 이상이어야 하고, 세션이 기능 플래그를 받아야 하며, 플러그인이 활성화되어 있어야 합니다. 설치 또는 업데이트 후 첫 세션도 완료되어야 합니다. 직접 읽기 모드를 선택하세요. claude-md와 managed-only는 해당하지 않습니다. 기본 모드에서는 차단 파일이 없는지도 확인하세요.
  2. hook을 제거하세요.
  3. 세션을 닫고 새 세션을 여세요. SessionStart hook은 시작할 때 텍스트를 추가하므로 이미 열린 세션의 컨텍스트에는 그 내용이 남아 있습니다. 그런 세션에서 Claude가 지침 내용을 답하더라도 직접 읽기를 확인할 수 없습니다.
  4. 새 세션에서 로드를 확인하세요. 버전 2.1.280 이상에서는 /memory에서 AGENTS.md 경로를 확인할 수 있습니다. 버전 2.1.277~2.1.279에서는 차단 파일이 없다면 시작 시 AGENTS.md loaded 줄을 찾으세요. 문서는 CLAUDE.md를 찾지 못한 경우에 이 줄이 표시된다고 구체적으로 설명합니다. CLAUDE.md를 유지하고 claude-md-and-agents-md 모드를 사용한다면 확인에 한계가 있습니다. 이 버전들에서는 /memory에 AGENTS.md가 표시되지 않고, 문서에도 이 경우에 대한 로드 메시지가 설명되어 있지 않으며, 지침을 바꾸어 말해도 CLAUDE.md 안의 @ import와 직접 읽기를 구분할 수 없습니다. 이 경우 2.1.280 이상으로 업데이트하고 /memory를 확인하세요.

AGENTS.md가 로드되었는지 확인하는 방법#

일반 CLAUDE.md와 다른 점이 두 가지 더 있습니다. 이러한 방식으로 읽은 AGENTS.md에는 InstructionsLoaded hook이 실행되지 않습니다(CLAUDE.md에서 @ 문법으로 import하거나 CLAUDE.md 심볼릭 링크로 연결한 AGENTS.md에는 작동함). --add-dir 플래그와 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 변수를 함께 사용해 추가한 디렉터리에서는 해당 디렉터리의 CLAUDE.md만 로드되며 AGENTS.md는 포함되지 않습니다.

대규모 프로젝트 지침 파일의 내용을 검토해야 한다면 CLAUDE.md를 비대하게 만들지 않고 설정하는 방법에 관한 별도 분석을 참고하세요. 해당 글은 지침의 구조를 다루며, AGENTS.md를 로드하는 조건은 위에서 설명했습니다. 세션 간 작업 메모에 관해서는 프로젝트 지침에 개인 메모리를 덧붙이는 방법을 다룬 Claude Code의 세컨드 브레인 분석을 참고하세요.

다음 단계#

이 기능은 2026년 9월 18일 버전 2.1.277에서 출시되었습니다. Anthropic이 향후 릴리스에서 모드의 세부 사항을 명확히 할 수 있으므로, 중요한 프로젝트의 설정을 변경하기 전에 이 글을 현재 /config 옵션 및 공식 변경 기록과 비교하세요.