Claude Code가 이제 AGENTS.md를 읽습니다: CLAUDE.md와 AGENTS.md 비교 및 .claude 디렉터리

claude.md란 무엇이며, 무엇을 작성해야 할까요?

CLAUDE.md 은 Claude Code가 세션 컨텍스트로 읽어 들이는 지침을 담은 일반 텍스트 Markdown 파일입니다. 빌드 및 테스트 명령, 코딩 규칙, 프로젝트 아키텍처, 워크플로 규칙처럼 매번 반복해서 알려 줘야 할 정보를 기록할 수 있는 공간을 제공합니다.

필수 문서 형식은 없습니다. 일반적인 Markdown 제목과 목록으로 구성하고, 프로젝트 지침을 이해하기 쉬운 구조를 선택하면 됩니다. Claude Code의 /init 명령은 다음 문서에 설명된 대로 프로젝트를 기반으로 시작용 파일을 생성합니다. 공식 모범 사례 문서.

다음 네 가지 영역을 다루는 것이 좋은 출발점입니다.

• 빌드 및 테스트 명령: 기여자가 프로젝트를 빌드하고 변경 사항을 확인할 때 사용해야 하는 명령입니다.
• 코딩 규칙: 저장소에 적용되는 이름 지정, 서식 및 기타 규칙입니다.
• 프로젝트 아키텍처: 주요 구성 요소와 이들이 서로 연결되는 방식입니다.
• 워크플로 규칙: Claude가 변경 사항을 적용하고 확인할 때 따르도록 할 단계입니다.

이를 지속적으로 적용되는 지침으로 취급하세요. 지침은 Claude의 컨텍스트에 들어가지만, 강제로 적용되는 설정은 아닙니다. Claude Code 자체를 구성해야 한다면 적절한 설정 파일을 사용하세요. 다음 파일의 서술형 지침이 CLAUDE.md 설정값처럼 작동할 것으로 기대해서는 안 됩니다.

저장소를 구성할 때는 이 구분이 중요합니다. 프로젝트 지식은 지침 파일에, 애플리케이션 구성은 설정에 담아야 합니다. 다음 Claude Code 가이드 허브 는 관련 워크플로를 살펴보는 출발점을 제공합니다.

CLAUDE.md를 둘 위치

Claude Code는 여러 위치에서 공유 프로젝트 지침과 개인 지침을 지원합니다. 다음 지침 파일 문서 는 이러한 지원 위치와 지침 검색 방식을 설명합니다.

상위 디렉터리의 지침 파일은 시작 시 로드됩니다. 하위 디렉터리의 파일은 필요할 때 로드되므로, Claude가 프로젝트의 해당 부분에서 작업할 때 관련 지침이 적용됩니다.

공유 지침은 팀에 적합한 위치에 두세요. 루트 수준의 CLAUDE.md 파일은 저장소의 다른 최상위 파일과 함께 지침을 배치합니다. .claude/CLAUDE.md 파일은 프로젝트의 Claude 전용 파일과 함께 지침을 배치합니다.

개인 지침은 파일 구성 외에도 영향을 미칩니다

CLAUDE.local.md 파일은 공유 프로젝트 파일과 다른 용도로 쓰이며, 해당 프로젝트에 대한 개인 지침을 담습니다. 버전 2.1.277에서는 이 파일의 존재 여부가 Claude Code가 대체 수단으로 다음 파일을 사용하는지에도 영향을 줍니다. AGENTS.md.

즉, 로컬 지침 파일을 추가하면 어떤 공유 지침이 컨텍스트에 들어가는지가 달라질 수 있습니다. 다음 파일에 의존하는 저장소에 로컬 지침 파일을 만들기 전에 AGENTS.md, 아래에 설명된 프로젝트 지침 설정을 확인하세요.

위의 위치 정보는 지속적으로 갱신되는 문서를 바탕으로 하며, 19년 9월 당시의 정확한 문구는 검증하지 않았습니다. 다음 섹션의 대체 동작은 태그가 지정된 2.1.277 릴리스에 대해 구체적으로 문서화되어 있습니다.

Claude Code는 AGENTS.md를 자동으로 읽나요?

예, 조건에 따라 읽습니다. 다음 Claude Code 2.1.277 릴리스 노트 에는 다음과 같이 명시되어 있습니다. “AGENTS.md 지원 추가: CLAUDE.md가 없는 프로젝트에서는 Claude Code가 대신 AGENTS.md를 읽습니다.”

기본 동작은 대체 동작이므로, AGENTS.md 파일이 있다는 사실만으로 로드된다는 뜻은 아닙니다. 이 릴리스에서는 루트 수준의 파일 외에도 다음 파일을 확인합니다. CLAUDE.md.

어떤 경우에 기본 대체 동작이 비활성화되나요?

파일 시스템 루트부터 작업 디렉터리까지의 경로 어디에든 다음 파일 중 하나가 있으면 기본 AGENTS.md 대체 동작이 비활성화됩니다.

• CLAUDE.md
• .claude/CLAUDE.md
• CLAUDE.local.md

관리형 지침, 다음 위치의 개인 지침 ~/.claude/CLAUDE.md및 .claude/rules/ 은 아닙니다. 해당 대체 동작을 비활성화합니다.

예를 들어, 공유 AGENTS.md 파일이 있고 상위 디렉터리 경로에 조건에 해당하는 Claude 지침 파일이 없는 저장소를 생각해 보세요. 기본 모드에서는 AGENTS 지침을 읽습니다. 이후 다음 파일을 추가하면 CLAUDE.local.md, 새 파일에 팀의 공유 지침이 아닌 개인 지침이 들어 있더라도 기본 대체 동작이 비활성화됩니다.

AGENTS.md 검색 방식

내장 지원은 다음 agents-md 플러그인에서 제공하며, 버전은 0.1.0입니다. 이 플러그인은 다음 두 파일을 모두 검색합니다. AGENTS.md 및 .claude/AGENTS.md 검색은 상위 디렉터리 경로를 따라 이루어지며, Claude가 프로젝트 루트 아래의 파일을 읽을 때 중첩된 지침을 첨부합니다.

가져오기나 링크를 통해 이미 로드된 콘텐츠는 중복 제거됩니다. Claude 지침 파일이 이미 동일한 AGENTS 콘텐츠를 가져오는 경우에는 이 점이 중요합니다.

19년 9월 발행 마감 시점 기준으로, 릴리스 발표에 따르면 이 지원은 아직 Bedrock, Vertex 또는 Foundry에서 제공되지 않습니다.

Claude Code가 한 파일 또는 두 파일을 모두 읽도록 구성하기

열기 /config 에서 다음 설정을 변경하세요. 프로젝트 지침 설정으로 지침 로드 동작을 선택할 수 있습니다. 다음 태그가 지정된 v2.1.277 플러그인의 README 에는 정확한 네 가지 값이 문서화되어 있습니다.

README에는 다음 값에 대한 중요한 단서가 포함되어 있습니다. managed-only: 중첩된 CLAUDE.md 첨부 콘텐츠는 여전히 들어올 수 있습니다. 이 값을 중첩된 Claude 지침 콘텐츠가 대화에 전혀 들어오지 않는다는 보장으로 해석해서는 안 됩니다.

버전 2.1.277의 정확한 구성

두 종류의 지침을 모두 로드하려면 다음 구성을 사용하세요.

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

이 릴리스에서는 다음 위치의 사용자 설정에 넣으세요. ~/.claude/settings.json, 다음을 통해 제공되는 파일 --settings또는 관리형 설정에 넣을 수도 있습니다. 프로젝트 .claude/settings.json 는 아닙니다. 이러한 플러그인 옵션을 제공합니다.

변경 사항은 다음 턴이나 새 대화처럼 컨텍스트가 다음에 재구성될 때 적용됩니다. 설정 변경으로 로드된 지침이 달라졌는지 확인할 때는 이 적용 시점을 염두에 두세요.

공유 지침을 가져오는 방법도 여전히 사용할 수 있습니다

다음을 넣을 수도 있습니다. @AGENTS.md 인접한 다음 파일 안에 CLAUDE.md. 이렇게 하면 Claude 지침 파일을 통해 공유 지침을 명시적으로 가져옵니다.

Claude 지침 파일의 가져오기는 다음을 사용합니다. @path/to/file.md 이 기능은 v0.2.107에서 도입되었습니다. 버전 2.1.277에서는 다음을 통해 이미 가져온 AGENTS 콘텐츠의 중복을 제거합니다. CLAUDE.md.

따라서 공유 지침을 구성하는 방법은 두 가지입니다. Claude Code가 두 파일을 모두 로드하도록 구성하거나, 가져오기를 사용해 AGENTS 콘텐츠를 Claude 지침 파일에 포함할 수 있습니다. 저장소 기여자가 두 파일의 관계를 명확히 이해할 수 있는 구성을 선택하세요.

.claude 디렉터리에는 무엇을 두어야 하나요?

이 .claude 디렉터리에는 여러 종류의 프로젝트 파일이 들어갑니다. 각 파일은 용도가 다르므로, 지속적으로 적용되는 지침, 구성, 재사용 가능한 프롬프트, 하위 에이전트 정의 또는 절차 중 무엇을 작성하는지에 따라 위치를 선택하세요.

여러 프로젝트에 걸쳐 적용되는 개인 설정은 다음 위치에 있습니다. ~/.claude/settings.json. 개인 하위 에이전트 정의는 다음 위치를 사용합니다. ~/.claude/agents/, 개인용 스킬은 다음을 사용합니다 ~/.claude/skills/<name>/SKILL.md.

명령, 하위 에이전트, 스킬

다음과 같은 명령 파일은 .claude/commands/deploy.md 다음을 생성합니다 /deploy. 버전 2.1.3에서 슬래시 명령과 스킬이 통합되었으며, 기존 명령 파일은 스킬과 함께 계속 작동합니다.

하위 에이전트 정의는 YAML 프런트매터가 포함된 Markdown을 사용합니다. 필수 필드는 다음과 같습니다 name 및 description; 관련 선택적 필드는 다음과 같습니다 tools, model및 permissionMode. 다음으로 관리하세요 /agents, 그리고 다음을 참고하세요 하위 에이전트 가이드 프로젝트 설정의 해당 부분을 구성할 때 참고하세요.

스킬은 다음 파일이 포함된 폴더에 재사용 가능한 절차를 패키징합니다 SKILL.md, 선택적으로 스크립트와 참고 자료를 포함할 수 있습니다. Claude가 관련 스킬을 선택할 수도 있고, 다음으로 직접 호출할 수도 있습니다 /skill-name; 스킬 본문은 사용 시 로드됩니다. 다음 문서는 스킬 가이드 이 워크플로를 다룹니다.

이러한 구조는 AGENTS 폴백 릴리스 이전부터 존재했습니다. 다음 문서는 태그가 지정된 변경 로그 프로젝트 설정, 명령, 에이전트, 스킬이 v2.1.277 시점에 이미 존재했음을 확인해 줍니다. 자세한 디렉터리 설명은 지속적으로 갱신되는 문서를 바탕으로 하며, 기준일 당시의 정확한 문구는 검증하지 않았습니다.

CLAUDE.md와 자동 메모리 비교

CLAUDE.md 와 자동 메모리는 콘텐츠를 작성하는 주체가 다릅니다. 사용자는 프로젝트 지침을 정의하기 위해 지침 파일을 작성하고, Claude는 유용한 맥락을 자동 메모리에 저장합니다.

태그가 지정된 변경 로그에는 다음을 통한 자동 저장 및 관리 기능이 기록되어 있습니다 /memory 버전 2.1.59에서 제공됩니다. 따라서 자동 메모리는 사용자가 다음 파일에서 의도적으로 관리하는 지침과는 별도의 역할을 합니다 CLAUDE.md 또는 AGENTS.md.

정보를 어디에 둘지 결정할 때는 작성 주체의 차이를 기준으로 삼으세요. 명시적인 빌드 명령, 규칙, 아키텍처 메모, 워크플로 규칙은 지침 파일에 넣으세요. 다음을 사용하세요 /memory Claude가 자동으로 저장하는 유용한 맥락을 관리할 때 사용하세요.

핵심 요점

• CLAUDE.md 에는 Claude Code가 컨텍스트로 읽어 들이는 지속적인 Markdown 지침이 포함되며, 구성을 강제하지는 않습니다.
• Claude Code 2.1.277에는 조건부로 적용되는 다음 기능이 추가되었습니다 AGENTS.md 폴백이며, 릴리스 당시 Bedrock, Vertex, Foundry는 제외되었습니다.
• 상위 디렉터리에 있는 CLAUDE.md, .claude/CLAUDE.md, 또는 CLAUDE.local.md 은 기본 폴백을 비활성화합니다.
• 프로젝트 지침을 다음으로 설정하세요 claude-md-and-agents-md 두 지침 계열을 모두 로드하려면 이 설정을 사용하세요.
• v2.1.277에서는 플러그인 옵션을 사용자 설정이나 다음 파일에 넣어야 합니다 --settings 파일 또는 관리형 설정에 넣어야 하며, 프로젝트의 다음 파일에는 넣지 않습니다 .claude/settings.json.
• 이 .claude 디렉터리에는 설정, 명령, 하위 에이전트, 스킬도 저장됩니다. 자동 메모리에는 Claude가 저장한 맥락이 포함됩니다.

자주 묻는 질문

CLAUDE.md란 무엇인가요?

CLAUDE.md 는 빌드 명령, 코딩 규칙, 아키텍처 메모, 워크플로 규칙 등 Claude Code를 위한 지속적인 지침을 담은 일반 텍스트 Markdown 파일입니다. Claude는 이 파일을 세션 컨텍스트로 읽어 들이며, /init 은 프로젝트를 바탕으로 초기 파일을 생성할 수 있습니다.

CLAUDE.md와 AGENTS.md가 모두 있으면 어떤 파일이 로드되나요?

Claude Code 2.1.277의 기본 claude-md-or-agents-md 모드에서는 조건에 맞는 Claude 지침 파일이 AGENTS 폴백을 비활성화합니다. 다음을 선택하세요 claude-md-and-agents-md 두 파일을 모두 로드하거나, 다음을 사용해 인접한 AGENTS 지침을 가져오세요 @AGENTS.md 다음 파일 안에서 CLAUDE.md.

CLAUDE.local.md를 추가하면 왜 AGENTS 폴백이 중지되나요?

버전 2.1.277에서는 다음 파일이 포함됩니다 CLAUDE.local.md 파일 시스템 루트부터 작업 디렉터리까지 탐색할 때 발견되면 기본 폴백을 비활성화하는 파일에 포함됩니다. 따라서 이 파일의 목적은 개인용 프로젝트 지침이지만, 파일의 존재 여부에 따라 공유 AGENTS 지침이 로드되는지가 달라질 수 있습니다.

프로젝트의 .claude/settings.json에서 두 파일을 모두 활성화할 수 있나요?

v2.1.277에서는 프로젝트의 .claude/settings.json 에서 다음을 제공하지 않습니다 agents-md 플러그인 옵션입니다. 다음을 사용하세요 /config, 또는 문서에 명시된 다음을 넣으세요 pluginConfigs 구성을 사용자 설정이나 다음 파일에 넣으세요 --settings 파일 또는 관리형 설정에 넣으세요.