Claude Code 사용법: AGENTS.md를 프로젝트 지침으로 불러오기

Claude Code 사용법: AGENTS.md를 읽히는 가장 짧은 절차

다음 순서대로 진행합니다.

1. claude --version을 실행합니다. v2.1.277 이상이어야 합니다.
2. 필요하면 업데이트합니다. 네이티브 설치는 claude update를 사용할 수 있고, Homebrew와 WinGet은 각 패키지 관리자의 업그레이드 명령을 사용합니다.
3. 현재 세션에서 Anthropic 기능 플래그를 가져올 수 있는지 확인합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 같은 서드파티 제공업체 세션에서는 네이티브 AGENTS.md 로드를 사용할 수 없습니다. 텔레메트리 또는 비필수 트래픽 설정이 기능 플래그 수신을 막을 때도 마찬가지입니다.
4. 프로젝트 경로에 AGENTS.md 또는 .claude/AGENTS.md를 둡니다. 기본 모드에서는 작업 디렉터리와 그 상위 경로에 프로젝트 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없어야 합니다.
5. 두 파일 계열을 모두 써야 한다면 /config를 열고 Project instructions를 claude-md-and-agents-md로 설정합니다.
6. 새 세션에서 테스트합니다. 설치 또는 업그레이드 직후의 첫 세션은 예외이므로, 그다음 세션을 열어 결과를 판단해야 합니다.

이것이 네이티브 방식입니다. /config에 Project instructions가 보이지 않는다면 CLAUDE.md에 문서화된 @AGENTS.md 가져오기를 계속 사용합니다.

Claude Code는 실제로 어떤 지침 파일을 선택하나

새 동작은 모든 지침 파일을 무조건 훑는 방식이 아니라 선택 스위치에 가깝습니다. 기본값인 claude-md-or-agents-md 모드에서 Claude Code는 먼저 프로젝트 수준의 Claude 지침을 확인합니다. 작업 디렉터리나 그 상위 경로에 조건을 충족하는 Claude 파일이 하나도 없을 때만 AGENTS.md로 폴백합니다.

주의할 부분은 적용 범위입니다. 상위 디렉터리에 있는 CLAUDE.local.md도 폴백을 막습니다. 반면 개인용 ~/.claude/CLAUDE.md, 조직에서 관리하는 CLAUDE.md, .claude/rules/는 폴백을 막지 않습니다. 같은 저장소를 연 두 개발자에게서 동작이 다르게 보인다면 대개 이 차이로 설명할 수 있습니다.

폴백 조건이 충족되면 Claude Code는 세션 시작 시 작업 디렉터리와 상위 디렉터리의 AGENTS.md 및 .claude/AGENTS.md를 읽습니다. 하위 디렉터리에 자체 조건 충족 Claude 파일이 없다면, Claude가 그곳의 파일을 읽는 시점에 해당 하위 디렉터리의 AGENTS.md가 나중에 로드될 수 있습니다. AGENTS.local.md, AGENTS.override.md, .agents/ 아래의 파일은 직접 읽지 않습니다.

이 동작은 폴더 검색보다 건물의 전기 회로 선택기에 가깝습니다. 선택기가 먼저 활성 지침 회로를 고르기 때문에, 다른 회로의 파일이 아무리 유효해도 연결되지 않은 채 남을 수 있습니다.

Project instructions 모드는 의도에 맞게 선택합니다

/config를 열고 Project instructions를 찾은 뒤, 저장소에서 무엇을 단일 기준으로 삼을지에 따라 선택합니다.

• Fallback, claude-md-or-agents-md: 이미 AGENTS.md를 쓰고 있고 프로젝트 Claude 파일은 없는 저장소에 적합합니다. 기본값입니다.
• Both, claude-md-and-agents-md: AGENTS.md에는 공통 규칙을 두고 CLAUDE.md에는 Claude 전용 지침을 추가할 때 적합합니다.
• Claude only, claude-md: 팀이 아직 공용 에이전트 지침을 Claude Code에 제공할 준비가 되지 않았을 때 적합합니다.
• Managed only, managed-only: 조직 정책과 자동 메모리는 로드하되, 저장소 지침은 시작 시 불러오지 않아야 하는 통제된 실행 환경에 적합합니다.

Both 모드에서는 각 디렉터리의 Claude 내용을 AGENTS 내용보다 먼저 읽습니다. CLAUDE.md가 같은 AGENTS.md를 이미 가져오거나 심볼릭 링크로 가리키고 있으면 중복 로드도 피합니다.

선택한 설정은 다음 메시지부터 적용되고 새 세션에도 유지됩니다. 사용자 설정의 기본 제공 agents-md@builtin 플러그인, --settings 파일 또는 관리형 설정에도 지정할 수 있습니다. Claude Code는 프로젝트 및 로컬 설정 파일에 있는 이 옵션을 무시하므로, 저장소가 모든 개발자에게 같은 선택을 몰래 강제할 수는 없습니다. 관리자는 관리형 설정을 통해 조직 전체에 선택을 적용할 수 있습니다.

새 세션이 어떤 파일을 읽었는지 확인하는 방법

위험한 지침 대신 무해한 확인 문구를 사용합니다. 테스트할 파일에 다음 줄을 추가합니다.

Project probe: BASALT-HERON.

그런 다음 세션을 닫고 저장소에서 다음 새 세션을 시작한 뒤 What is the project probe?라고 묻습니다. BASALT-HERON이라는 답이 정확히 나오면 해당 내용이 세션 컨텍스트에 전달된 것입니다. 확인이 끝나면 이 줄을 삭제합니다.

/context만으로 결론을 내리면 안 됩니다. 직접 로드된 AGENTS.md는 Memory files 목록에 나타나지 않습니다. 기본 폴백을 쓰는 대화형 세션에서는 시작 시 AGENTS.md loaded 문구가 표시될 수 있습니다. 무해한 확인 문구를 질문하는 방법은 다른 선택 모드에서도 통합니다.

확인에 실패하면 다음 순서로 점검합니다.

1. 버전: v2.1.277 이상인지 확인합니다.
2. 세션 횟수: 설치 또는 업그레이드 후 첫 세션이 아닌지 확인합니다.
3. 제공업체: Anthropic 기능 플래그 수신을 막는 제공업체의 세션이 아닌지 확인합니다.
4. 환경: 텔레메트리 또는 비필수 트래픽 변수가 기능 플래그 수신을 비활성화하지 않았는지 확인합니다.
5. 플러그인 및 정책: 기본 제공 agents-md 플러그인이 활성화돼 있고 disableAllHooks와 allowManagedHooksOnly 중 어느 것도 플러그인을 차단하지 않는지 확인합니다.
6. 파일 계층: 기본 모드일 때 현재 경로나 상위 경로에 조건을 충족하는 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없는지 확인합니다.
7. 모드: /config가 의도한 동작을 가리키는지 확인합니다.

/config에 Project instructions가 없다면 그 자체가 진단 신호입니다. 지원하지 않는 버전이거나 해당 세션에서 이 기능을 사용할 수 없다는 뜻입니다.

네이티브 지원이 작동하지 않는 환경에서는 가져오기를 유지합니다

기존 가져오기 방식은 Bedrock, Vertex, Foundry, 기타 서드파티 제공업체 세션, 텔레메트리가 제한된 환경, 여러 버전이 섞인 팀에서 가장 안전한 호환 계층입니다. AGENTS.md 옆의 CLAUDE.md에 다음 내용을 넣습니다.

@AGENTS.md

그 아래에 Claude 전용 지침을 추가할 수 있습니다. Claude는 가져온 공용 파일을 먼저 읽고, 그다음 Claude 전용 추가 내용을 읽습니다. 이 브리지를 유지해도 지원되는 사용자가 Both 모드를 선택했을 때 중복 로드되지 않습니다.

CLAUDE.md에서 AGENTS.md로 연결하는 심볼릭 링크도 작동하지만, 여러 플랫폼을 함께 쓴다면 가져오기 방식이 더 안전합니다. Windows에서는 심볼릭 링크 생성에 관리자 권한이나 Developer Mode가 필요할 수 있고, Git에도 올바른 심볼릭 링크 설정이 필요합니다. 직접 로드가 작동한 뒤에는 AGENTS.md를 출력하는 SessionStart 훅을 제거해야 합니다. 그대로 두면 같은 내용이 중복 주입될 수 있습니다.

이번 릴리스로 유지관리 방식이 달라집니다. 이전에는 여러 에이전트가 함께 쓰는 정책 하나를 관리하려고 두 파일이나 가져오기용 보조 장치, 또는 훅을 유지하는 경우가 많았습니다. 이제 지원되는 세션의 기본 경로에서는 커밋된 지침 파일 하나로 충분할 수 있습니다. Claude 라이선스 비용은 줄지 않습니다. Anthropic은 월 $20 Pro 요금제에 Claude Code가 포함된다고 안내합니다. 절감되는 것은 동기화 지점과 오래된 규칙을 참조하는 세션의 수입니다.

나머지 설정은 Claude Code 전체 사용 가이드에서 설치, 프로젝트 컨텍스트, 일상적인 명령 흐름까지 설명합니다. 저장소에서 전문 에이전트도 정의한다면 서브에이전트 가이드에서 별도의 시작 컨텍스트를 확인할 수 있습니다.

효과가 큰 일곱 가지 활용 상황

새 선택기가 해결하는 협업 문제의 규모가 큰 순서대로 정리했습니다.

앞의 세 가지는 실패가 여러 사람과 저장소에 걸쳐 증폭되므로 투자 대비 효과가 가장 큽니다. 한 사람이 하나의 에이전트만 쓰는 저장소라면 편리함은 분명하지만 효과는 작습니다.

이 기능을 바탕으로 만들 수 있는 것

1. 여러 에이전트의 지침 로드 상태를 진단하는 도구

각 코딩 에이전트가 어떤 지침 파일을 읽을지 정확히 설명하는 로컬 CLI와 CI 검사를 만들 수 있습니다. 저장소 전체에 적용하기 전에 확실한 답이 필요한 플랫폼 팀과 컨설팅 회사가 고객이 될 수 있습니다.

수요는 이미 검색량에 드러납니다. claude code setup은 미국에서 월 약 1,900회 검색되고, claude md vs agents md는 480회 검색되며 전년 대비 1,500% 성장했습니다. 판매 가능한 최소 버전은 파일 트리를 스캔하고 Claude Code 버전과 제공업체 설정을 읽은 뒤, 가리는 파일을 표시하고 로드 순서 계획을 출력하는 형태입니다. 유료 팀 기능에서는 여러 저장소에 같은 정책을 적용할 수 있습니다.

단순한 템플릿이 아니라 진단 문제를 해결한다는 점에서 가장 강한 기회입니다. 다만 플랫폼 의존 위험은 있습니다. Anthropic이 이 검사를 claude doctor에 포함할 수 있으므로, 지속 가능한 제품이 되려면 Claude 명령 하나에 머물지 않고 여러 코딩 에이전트를 지원하며 정책 변경 이력까지 다뤄야 합니다.

2. AGENTS.md 정책 스타터와 린터

빌드 명령, 테스트 규칙, 디렉터리 경계, 리뷰 요구사항을 간결한 AGENTS.md로 정리하고 충돌이나 모호한 표현을 검사하는 안내형 편집기를 만들 수 있습니다. 여러 에이전트를 도입하는 소규모 엔지니어링 팀이 구매 대상입니다.

agents md는 미국에서 월 약 2,900회 검색됩니다. 더 구체적인 agents md best practices 검색어는 210회이며 전년 대비 750% 성장했습니다. MVP에는 저장소 스캐너, 짧은 질문 과정, 초안 생성, 중복되거나 모순된 지침을 찾는 린트 규칙이 필요합니다. 거대한 정책 문서를 만드는 대신, 간결한 프로젝트 파일을 권장하는 제공업체 지침 안에서 작동해야 합니다.

약점은 방어력이 낮다는 점입니다. 어떤 코딩 에이전트든 Markdown 초안은 만들 수 있습니다. 실제 로드 순서를 검증하고 지원 대상 코딩 툴이 결과를 읽었다는 사실까지 증명해야 제품으로서 가치가 생깁니다.

3. 혼합 에이전트 환경 마이그레이션 감사

CLAUDE.md, AGENTS.md, 가져오기, 심볼릭 링크, 훅, 중첩 규칙, 제공업체 예외를 파악한 뒤 단일 원본으로 안전하게 옮기는 계획을 보고서로 제공할 수 있습니다. 여러 에이전트 툴을 쓰는 에이전시와 규모가 큰 팀이 주요 고객입니다.

claude md vs agents md의 월 480회 검색과 전년 대비 1,500% 성장은 혼란이 실제로 크다는 매우 직접적인 증거입니다. MVP는 읽기 전용 저장소 분석기와 풀 리퀘스트 계획만으로도 만들 수 있습니다. 지원되지 않는 세션에서 브리지가 계속 필요할 수 있으므로 자동으로 삭제해서는 안 됩니다.

단점은 최신성이 중요한 기간이 짧다는 것입니다. 팀들이 안정적인 공용 파일 관례에 합의하면 일회성 마이그레이션 수요는 줄어듭니다. 반복적인 정책 감사와 제공업체 호환성 검사를 핵심 서비스로 전환해야 합니다.

한계와 현실적인 판단

네이티브 폴백은 브리지를 없애줄 뿐입니다. 프로젝트 지침을 강제 정책으로 바꾸거나, 모든 제공업체를 호환되게 만들거나, 충돌하는 규칙을 해결해 주지는 않습니다. Anthropic은 지침 파일을 컨텍스트로 설명합니다. 반드시 차단해야 하는 명령이 있다면 권한 규칙이나 PreToolUse 훅을 사용해야 합니다.

또한 AGENTS.md가 CLAUDE.md와 같은 진단 화면에 표시되도록 바뀌는 것도 아닙니다. 직접 로드된 파일은 /memory와 /context의 Memory files 목록에 나타나지 않습니다. 이 불일치 때문에 마이그레이션 체크리스트에 무해한 확인 문구를 남겨둘 가치가 있습니다.

한 대의 노트북에서 네이티브 테스트를 통과했다고 해서 여러 제공업체가 섞인 환경의 정상 작동 중인 가져오기를 지우면 안 됩니다. 서로 충돌하는 내용이 없는지 검토하지 않은 채 Both 모드를 선택해서도 안 됩니다. 같은 디렉터리에서는 Claude 내용이 AGENTS 내용보다 먼저 읽히지만, 컨텍스트 순서가 강제력 있는 정책 우선순위를 뜻하지는 않습니다.

그래도 이번 릴리스는 운영 측면에서 의미 있는 개선입니다. 이미 AGENTS.md를 공용 원본으로 쓰는 저장소라면 이제 두 번째 파일명을 원본인 것처럼 다루지 않고도 Claude Code와 함께 사용할 수 있습니다. 작은 기능이지만 협업에는 큰 영향을 줍니다.

저장소에 맞는 안정적인 다중 에이전트 지침 체계를 구축하려면 에이전트 아키텍처 설계와 도입을 도와드릴 수 있습니다.