# Claude Code가 이제 AGENTS.md를 읽습니다: 2.1.277에서 달라진 점
> 2026년 9월 18일, Claude Code 2.1.277에 AGENTS.md 직접 지원이 추가되었습니다. 파일이 로드되는 조건, 4가지 모드 중 하나를 선택하는 방법, import 처리 방법을 알아봅니다.
Source: https://ailoot.ai/blog/ko/claude-code-agents-md-support/
Canonical: https://ailoot.ai/blog/ko/claude-code-agents-md-support/
Language: ko
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-041
Revision: sha256-a295bb0d6eaaaf4f303bfb39a3dac4ea1a3d3fe35cc23b7fb7ab0425d01b2388
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`의 심볼릭 링크로 만들어야 했습니다. 자세한 내용은 [여러 에이전트가 함께 사용하는 단일 지침 파일에 관한 글](https://ailoot.ai/blog/ko/agents-md-claude-md-one-instruction-file/)을 참고하세요.
같은 저장소에서 Claude Code와 다른 도구 한두 개를 사용한다면, 선택한 Project instructions 모드에 따라 Claude Code가 읽는 지침 파일이 달라집니다. 아래에서 네 가지 모드의 조건과 기존 설정에서 전환하는 방법을 설명합니다.
도구 설정에 관한 더 많은 자료는 [Ailoot 문서](https://ailoot.ai/docs/)에서 확인할 수 있습니다.
[Ailoot 가이드](https://ailoot.ai/docs/)
## 버전 2.1.277에서 무엇이 달라졌나요?
핵심 요점
2026년 9월 18일부터 작업 폴더와 그 상위 디렉터리 전체에 `CLAUDE.md`, `.claude/CLAUDE.md` 또는 `CLAUDE.local.md`가 없으면 Claude Code가 기본적으로 `AGENTS.md`를 읽습니다. 이 가운데 하나라도 있으면 Project instructions를 통한 `AGENTS.md` 자동 읽기가 활성화되지 않습니다. `CLAUDE.md`에서 `@AGENTS.md`를 명시적으로 import하는 방법은 계속 사용할 수 있습니다. 사용자 수준의 `~/.claude/CLAUDE.md`, 조직에서 관리하는 `CLAUDE.md`, `.claude/rules/`는 프로젝트 파일 선택과 관계없이 로드됩니다. `/config`에서 모드를 변경할 수 있습니다. 아직 Bedrock, Vertex, Foundry에서는 이 기능을 사용할 수 없습니다.
GitHub의 공식 Claude Code 프로젝트 CHANGELOG.md에는 다음과 같이 나와 있습니다.
AGENTS.md 지원 추가: CLAUDE.md가 없는 프로젝트에서 Claude Code는 대신 AGENTS.md를 읽습니다. "Project instructions"에서 /config를 통해 변경할 수 있습니다(Bedrock, Vertex, Foundry에서는 아직 사용할 수 없음).
— Anthropic, claude-code CHANGELOG.md 커밋, ca02e7d, https://github.com/anthropics/claude-code/commit/ca02e7deeb0707f558b0afd7e9e5d67a382e12b3
번역: `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.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`를 확인합니다. 개인용 `~/.claude/CLAUDE.md`, 조직에서 관리하는 `CLAUDE.md`, `.claude/rules/` 파일은 `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 문서](https://ailoot.ai/docs/)에서 확인할 수 있습니다.
[Ailoot 가이드](https://ailoot.ai/docs/)
## 4가지 Project instructions 모드: 어떤 것을 선택할까요?
핵심 요점
`/config` 명령의 Project instructions 섹션에는 네 가지 값이 있습니다. `claude-md-or-agents-md`(기본값: 두 파일 중 하나), `claude-md-and-agents-md`(두 파일 모두), `claude-md`(프로젝트에 `AGENTS.md`만 있어도 `CLAUDE.md`만 자동으로 읽음), `managed-only`(시작할 때 조직에서 관리하는 `CLAUDE.md`와 자동 메모리만 읽고 프로젝트 파일이나 개인 파일은 읽지 않음)입니다. 변경 사항은 다음 메시지부터 적용되며 모든 새 세션에도 적용됩니다.
표에 나온 모드별 동작은 Anthropic 문서에 설명되어 있습니다. 오른쪽 열에서는 모드를 선택하는 기준을 안내합니다.
| 값 | Claude Code가 읽는 항목 | 사용 시점 |
|----|----|----|
| `claude-md-or-agents-md` | `CLAUDE.md`, 또는 작업 디렉터리와 상위 디렉터리에 `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`가 없을 때 `AGENTS.md` | 저장소가 두 파일 중 하나만 사용하고 상위 디렉터리에 차단 파일이 없을 때 사용하는 기본값 |
| `claude-md-and-agents-md` | 두 파일을 함께 읽음: 각 디렉터리에서 먼저 `CLAUDE.md`, 이어서 `AGENTS.md` | 모든 도구가 공유하는 `AGENTS.md`와 Claude 전용의 짧은 `CLAUDE.md`가 필요하거나, `CLAUDE.local.md`가 있어도 `AGENTS.md`를 읽어야 할 때 |
| `claude-md` | `CLAUDE.md`만 읽음. `AGENTS.md`만 있는 경우에도 Project instructions를 통한 `AGENTS.md` 자동 읽기가 비활성화됨(`CLAUDE.md`에서 `@AGENTS.md`를 명시적으로 import하는 방법은 계속 작동함) | `AGENTS.md`가 다른 도구를 위해 작성되어 Claude를 혼란스럽게 할 수 있을 때 |
| `managed-only` | 세션 시작 시 조직에서 관리하는 `CLAUDE.md`와 자동 메모리만 읽습니다. 프로젝트, 로컬 및 사용자 `CLAUDE.md`, `.claude/rules/`, 모든 `AGENTS.md` 파일은 초기 파일 집합에서 제외됩니다. 하지만 하위 디렉터리의 `CLAUDE.md`와 `.claude/rules/` 파일은 Claude가 해당 위치의 파일을 열 때 나중에 로드됩니다. 이 모드는 초기 파일 집합을 제한하며 프로젝트 파일을 완전히 격리하지는 않습니다. | 프로젝트에 `CLAUDE.md`나 `AGENTS.md`가 있는지와 관계없이, Claude Code가 세션을 시작할 때 사용하는 지침 파일 집합을 통제하려는 조직에 적합합니다. |
인터페이스를 사용하지 않고 `settings.json`에서 모드를 선택할 수도 있습니다.
```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 이전 버전용 안내](https://ailoot.ai/blog/ko/agents-md-claude-md-one-instruction-file/)에서 `@` import가 어떻게 작동하는지 설명합니다. 이 방법은 지금도 사용할 수 있습니다.
## /config에 Project instructions가 없는 이유
핵심 요점
Anthropic 문서에 따르면 다음과 같은 이유로 Project instructions 섹션이 표시되지 않을 수 있습니다.
- Claude Code 버전이 2.1.277보다 낮습니다.
- 세션이 Anthropic의 기능 플래그를 받지 않습니다. 예를 들어 Bedrock이나 다른 타사 제공자를 사용하거나 텔레메트리가 비활성화된 경우입니다.
- 이전 버전에서 설치하거나 업데이트한 직후의 첫 세션입니다. 이것이 유일한 이유라면 다음 세션에서 기능이 표시됩니다. `AGENTS.md`는 선택한 모드의 조건이 충족될 때만 로드됩니다.
- 내장 `agents-md` 플러그인이 `/plugin`에서 비활성화되어 있습니다.
먼저 `claude --version` 명령으로 버전을 확인하세요. 2.1.277보다 낮으면 Claude Code를 업데이트하세요. 버전이 충분히 높은데도 섹션이 나타나지 않으면 위에 나온 다른 이유를 확인하세요. 기능을 사용할 수 없는 동안에는 `CLAUDE.md`에서 `@AGENTS.md`를 import하는 방법이 계속 작동하는 대안입니다.
## 기존 @AGENTS.md import는 어떻게 할까요?
핵심 요점
`CLAUDE.md`의 `@AGENTS.md` import와 심볼릭 링크는 그대로 유지해도 됩니다. 어떤 모드에서도 파일을 두 번 읽지 않습니다. `CLAUDE.md`를 유지한다면 “AGENTS.md를 읽어라”라는 텍스트 요청을 import로 바꿔야 합니다. 파일을 삭제하기 전에 필요한 지침을 모두 저장하고 선택한 모드의 조건을 확인하세요. 직접 읽기 방식으로 전환한다면 `AGENTS.md` 내용을 수동으로 출력하던 `SessionStart` hook을 제거하세요. 그렇지 않으면 파일 내용이 컨텍스트에 한 번 더 들어갑니다. 그다음 새 세션에서 로드 여부를 확인하세요. 확인 방법은 버전과 차단 파일의 유무에 따라 달라집니다.
다음 단계는 기존 설정에 따라 달라집니다. 먼저 이전 섹션의 설명에 따라 세션에서 이 기능을 사용할 수 있는지 확인하세요.
- **`@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가 로드되었는지 확인하는 방법
핵심 요점
버전 2.1.280부터 Project instructions를 통해 로드된 `AGENTS.md`가 `/memory`와 `/context` 명령의 Memory files 목록에 표시됩니다. 버전 2.1.277~2.1.279에서는 명령이 정상 작동하고 로드된 `CLAUDE.md` 및 다른 메모리 파일을 보여주더라도 `AGENTS.md`는 표시되지 않습니다. 이 버전에서 차단 파일이 없다면 세션 시작 때 `AGENTS.md loaded` 줄을 확인하세요. Claude에게 지침 내용을 물어보는 것은 신뢰도가 낮은 확인 방법입니다. 답변으로는 직접 읽기와 `@` import를 구분할 수 없으며 `SessionStart` hook이 추가한 텍스트를 바탕으로 답할 수도 있습니다. 따라서 이런 hook을 제거한 뒤 새 세션에서만 물어보는 것이 좋습니다.
일반 `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를 비대하게 만들지 않고 설정하는 방법에 관한 별도 분석](https://ailoot.ai/blog/ko/claude-md-template/)을 참고하세요. 해당 글은 지침의 구조를 다루며, `AGENTS.md`를 로드하는 조건은 위에서 설명했습니다. 세션 간 작업 메모에 관해서는 프로젝트 지침에 개인 메모리를 덧붙이는 방법을 다룬 [Claude Code의 세컨드 브레인 분석](https://ailoot.ai/blog/ko/claude-code-second-brain/)을 참고하세요.
## 다음 단계
이 기능은 2026년 9월 18일 버전 2.1.277에서 출시되었습니다. Anthropic이 향후 릴리스에서 모드의 세부 사항을 명확히 할 수 있으므로, 중요한 프로젝트의 설정을 변경하기 전에 이 글을 현재 `/config` 옵션 및 공식 변경 기록과 비교하세요.
### 출처
- [Claude Code, 2.1.277 항목이 포함된 GitHub CHANGELOG.md 커밋(2026년 9월 18일)](https://github.com/anthropics/claude-code/commit/ca02e7deeb0707f558b0afd7e9e5d67a382e12b3)
- [Claude Code 문서: Claude가 프로젝트를 기억하는 방식 - AGENTS.md 섹션](https://code.claude.com/docs/en/memory)
[Ailoot 가이드](https://ailoot.ai/docs/)
[Ailoot 바로가기](https://ailoot.ai/)
## Claude Code가 이제 AGENTS.md를 읽습니다: 2.1.277에서 달라진 점: 자주 묻는 질문
### AGENTS.md 파일이 있는데도 로드되지 않는 이유는 무엇인가요?
기본 모드에서는 작업 디렉터리나 상위 디렉터리에 CLAUDE.md, .claude/CLAUDE.md 또는 CLAUDE.local.md가 있으면 AGENTS.md 자동 선택이 차단됩니다. Claude Code 버전, 기능 제공 여부, /config의 Project instructions 모드도 확인하세요.
### 수동 훅을 제거한 뒤 직접 로드를 어떻게 확인하나요?
기존 SessionStart 출력이 없는 새 세션을 여세요. 2.1.280 이상에서는 /memory 또는 /context의 Memory files 목록을 확인하세요. 2.1.277-2.1.279에서는 차단하는 CLAUDE.md 파일이 없을 때 시작 로드 문구를 확인할 수 있습니다. Claude의 말로 된 설명만으로는 충분한 증거가 아닙니다.
## Ailoot · 회사와 그 프로젝트 포트폴리오
Ailoot는 축적된 운영 경험, 폭넓은 고객 기반, 안정적인 서비스, 지속적인 KPI 관리를 바탕으로 합니다.
회사와 그 프로젝트 포트폴리오: 수백만 고객, 매월 수십억 규모의 매출.
Ailoot는 이러한 운영 경험을 고객의 제품, 에이전트, 애플리케이션, 자동화에서 AI 기능을 이용할 수 있는 API 접근에 활용합니다.