# 2026년 Claude Code, Codex, Cursor를 위한 하나의 지침 파일 > 2026년 Claude Code, Codex, Cursor를 위한 단일 진실 공급원: Claude Code가 AGENTS.md를 직접 읽는 경우, @AGENTS.md를 CLAUDE.md에 가져오는 방법, 심볼릭 링크, /init. Source: https://ailoot.ai/blog/ko/agents-md-claude-md-one-instruction-file/ Canonical: https://ailoot.ai/blog/ko/agents-md-claude-md-one-instruction-file/ Language: ko Publisher: Ailoot (https://ailoot.ai/) Translation: guide-004 Revision: sha256-507cec268aa48447cad06d971c39a88d1cee7dd636c589f3ff05a3d558db3825 서비스에 대한 자세한 내용은 [Ailoot 문서](https://ailoot.ai/docs/)를 참조하세요. ## Claude Code, Codex, Cursor를 함께 사용하면 무엇이 달라질까요?
핵심 요점 2026년 일반적인 바이브 코더의 설정에는 도구 하나가 아니라 3~5개가 들어갑니다. Claude Code는 주 도구, Codex는 장시간 자율 작업, Cursor는 IDE에서 빠르게 편집할 때 사용합니다. 각 도구에는 자체 지침 파일이 있습니다. `CLAUDE.md`, `AGENTS.md`, `.cursorrules`입니다. 이를 수동으로 동기화하면 한 줄을 다섯 군데에서 수정하고 Cursor 업데이트를 잊게 되며, 일주일 뒤에는 같은 프롬프트에 Claude와 Codex가 서로 다른 결과를 내놓습니다.
여기서 설명하는 예시에서는 Claude Code가 주 도구이고 Codex와 Cursor는 특정 작업에 사용합니다. 제 `CLAUDE.md`에는 무엇을 어떤 순서로 읽을지, 무엇을 건드리면 안 되는지, 배포에 어떤 명령을 사용할지, 커밋 형식 규칙 등 약 250줄의 지침이 있습니다. 처음 Codex CLI를 프로젝트에 사용했을 때는 어떤 규칙도 알지 못했습니다. `git push --force`를 실행하고 `.env`를 뒤지고 파일 이름을 부주의하게 바꿨습니다. 처음에는 `CLAUDE.md`를 `AGENTS.md`로 직접 복사했습니다. 2주 뒤 프로젝트에 같은 지침의 버전이 이미 네 개 있다는 사실을 발견했습니다. `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.windsurf/rules/`에 각각 있었고 모두 조금씩 달랐습니다. 이는 Claude나 Cursor의 문제가 아니라 진실 공급원이 여러 개인 모든 시스템에 있는 기본적인 함정입니다. 이 문제는 [멀티 에이전트 작업 가이드](https://ailoot.ai/blog/ko/claude-code-codex-together/)에서 더 자세히 다룹니다. 2026년 6월, Anthropic의 Claude Code 메모리 문서는 공유 파일과 가져오기를 조합하는 해결책을 제시했습니다. 2026년 9월부터는 프로젝트에 `CLAUDE.md`가 없으면 Claude Code가 `AGENTS.md`를 직접 읽습니다. Claude 전용 규칙이 있을 때는 가져오기가 필요합니다. 아래에서 `AGENTS.md` 하나만으로 충분한 경우, 가져오기를 설정하는 방법, 공유 규칙과 Claude 전용 규칙을 분리하는 방법을 설명합니다. ## Claude Code는 AGENTS.md를 직접 읽나요?
핵심 요점 네. 2026년 9월 18일 출시된 버전 2.1.277부터 가능합니다. 다만 작업 디렉터리나 상위 디렉터리에 `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`가 없어야 합니다. `CLAUDE.md`가 있으면 기본적으로 해당 파일만 읽으며, `CLAUDE.md` 안에 `@AGENTS.md` 행을 넣거나 심볼릭 링크를 사용해야 `AGENTS.md`가 포함됩니다. 동작은 `/config`의 Project instructions 설정에 따라 달라집니다. 9월 전에는 Claude Code가 `AGENTS.md`를 전혀 읽지 않았고, 가져오기가 유일한 방법이었습니다.
2026년 9월 전까지 답은 “아니요”였습니다. AGENTS.md 지원을 요청한 이슈 \#6235는 2025년 8월부터 열려 있었고 2026년 8월 17일에 종료되었습니다. 그동안 메모리 문서는 한 가지 해결책을 제시했습니다. CLAUDE.md를 만들고 AGENTS.md를 가져오기로 포함하는 방법입니다. 버전 2.1.277부터 문서 내용이 달라졌습니다.

Claude Code는 AGENTS.md를 프로젝트 지침으로 읽을 수 있으므로, 다른 에이전트를 위해 이미 설정된 저장소는 CLAUDE.md, 가져오기, 설정 없이 작동합니다.

— Anthropic, https://code.claude.com/docs/en/memory#agents-md
프로젝트에 어떤 파일이 있는지에 따라 Claude Code가 읽는 내용이 정확히 달라집니다. | 프로젝트의 파일 | Claude Code가 읽는 내용 | |----|----| | 작업 디렉터리나 상위 디렉터리에 `CLAUDE.md` 또는 `CLAUDE.local.md`가 없고 `AGENTS.md`만 있음 | `AGENTS.md` | | 작업 디렉터리나 상위 디렉터리에 `AGENTS.md`와 `CLAUDE.md`(또는 `CLAUDE.local.md`)가 있음 | `CLAUDE.md`만 | | `@AGENTS.md` 행이 있는 `CLAUDE.md` | `CLAUDE.md` 및 가져오기를 통해 그 안에 포함된 `AGENTS.md` | 이 확인에서는 작업 디렉터리와 모든 상위 디렉터리에 있는 `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`가 모두 고려됩니다. 개인 `~/.claude/CLAUDE.md`, 기업 관리 파일, `.claude/rules/`의 규칙은 여기에 해당하지 않습니다. 이들은 `AGENTS.md`와 함께 로드됩니다. `CLAUDE.md`가 없으면 Claude Code는 시작할 때 작업 디렉터리와 상위 디렉터리에 있는 모든 `AGENTS.md` 및 `.claude/AGENTS.md` 파일을 읽고, 하위 디렉터리의 파일을 열 때는 해당 하위 디렉터리의 `AGENTS.md`도 읽습니다. `AGENTS.md` 안의 `@path` 가져오기도 작동합니다. Claude Code는 `AGENTS.local.md`, `AGENTS.override.md` 또는 `.agents/` 디렉터리의 내용을 읽지 않습니다. 주의할 점은 개인 `CLAUDE.local.md`도 영향을 준다는 것입니다. 커밋하지 않은 규칙을 보관하려고 이 파일을 만들면 Claude Code는 조용히 `AGENTS.md` 읽기를 중단합니다. 아래 설정이 해결책입니다. 동작은 `/config`의 Project instructions 설정에 따라 달라집니다. | 설정 | Claude Code가 읽는 내용 | |----|----| | `claude-md-or-agents-md` (기본값) | `CLAUDE.md`, 또는 `CLAUDE.local.md`도 존재하지 않으면 `AGENTS.md` | | `claude-md-and-agents-md` | 두 파일 모두: 각 디렉터리에서 `CLAUDE.md`를 먼저 읽고 그다음 `AGENTS.md`를 읽음 | | `claude-md` | `CLAUDE.md`만 | | `managed-only` | 기업에서 관리하는 `CLAUDE.md`와 자동 메모리만 | `CLAUDE.local.md`를 유지하면서 `AGENTS.md`도 읽게 하려면 `claude-md-and-agents-md`로 설정하세요. 중복해서 읽지는 않습니다. `AGENTS.md`가 이미 `@AGENTS.md` 행이나 심볼릭 링크를 통해 포함되어 있으면 설정과 관계없이 Claude Code는 두 번째로 로드하지 않습니다. `/memory` 명령으로 파일을 불러왔는지 확인할 수 있습니다. 버전 2.1.280부터 목록에 `AGENTS.md` 경로가 표시됩니다. 버전 2.1.277 이전 및 내장 `agents-md` 플러그인을 비활성화한 세션에서는 Claude Code가 `CLAUDE.md`만 읽으며, `/config`에 Project instructions 항목도 없습니다. 버전 2.1.281 전에는 Amazon Bedrock을 통한 세션과 텔레메트리를 비활성화한 세션도 같은 방식으로 동작했습니다. 이전 버전에서 업데이트한 뒤 첫 세션에서는 `AGENTS.md`가 로드되지 않을 수도 있습니다. 다음 세션부터 작동합니다. 파일 하나만 사용하는 설정에서는 이것이 무엇을 의미할까요? Claude 전용 규칙이 없다면 `CLAUDE.md`를 생략해도 됩니다. `AGENTS.md`만으로 충분하며 Claude Code, Codex, Cursor가 모두 읽습니다. 그런 규칙(위험한 디렉터리의 plan mode, skills, hooks)이 있다면 `CLAUDE.md`가 필요하고, Claude Code는 `AGENTS.md`를 직접 읽지 않게 됩니다. 이때 `CLAUDE.md` 안에 `@AGENTS.md` 행을 넣어 `AGENTS.md`를 포함하세요. 이 설정은 9월 전과 똑같이 작동합니다. 이전 버전의 Claude Code에도 도움이 됩니다. 아래에서 자세히 설명합니다. ## @AGENTS.md를 CLAUDE.md 안에 어떻게 가져오나요?
핵심 요점 프로젝트에 `CLAUDE.md`가 있으면 가져오기가 필요합니다. `CLAUDE.md`가 있으면 Claude Code는 기본적으로 `AGENTS.md`를 직접 읽지 않습니다. 설정하려면 `CLAUDE.md` 파일 맨 위에 `@AGENTS.md` 행을 작성하세요. Claude Code가 세션을 시작하면 그 행을 `AGENTS.md`의 내용으로 대체하고 결과를 하나의 텍스트로 읽습니다. 가져오기 아래에는 Claude에만 적용되는 규칙을 담은 “Claude Code” 섹션을 추가할 수 있습니다. 가져오기는 상대 경로와 절대 경로를 모두 지원하며 최대 네 단계까지 중첩할 수 있습니다.
공식 문서의 최소 작동 예시: ```markdown @AGENTS.md ## Claude Code src/billing/ 아래에서 변경할 때는 계획 모드를 사용하세요. ``` 다음과 같이 작동합니다. 첫 번째 행인 `@AGENTS.md`는 가져오기 지시문입니다. 세션 시작 시 Claude Code가 `CLAUDE.md`를 분석하며 이 가져오기를 찾아 그 위치에 `AGENTS.md`의 전체 내용을 삽입합니다. 다음에는 `## Claude Code` 제목이 나옵니다. 일반적인 markdown이지만 “Claude 전용 추가 사항” 섹션 역할을 합니다. 그 아래에는 Claude Code에만 적용되는 규칙, 즉 billing 디렉터리 변경 시 plan mode를 사용하라는 규칙이 있습니다. Codex CLI나 Cursor는 이 파일을 열지 않고 일반 `AGENTS.md`를 사용합니다. 가져오기 작동 방식에 관한 문서 인용:

CLAUDE.md 파일은 @path/to/import 구문을 사용해 추가 파일을 가져올 수 있습니다. 가져온 파일은 확장되어 해당 파일을 참조하는 CLAUDE.md와 함께 세션 시작 시 컨텍스트에 로드됩니다.

— Anthropic, https://code.claude.com/docs/en/memory
실용적인 세부 사항 몇 가지: - **상대 경로와 절대 경로.** `@AGENTS.md`는 가져오기를 포함한 파일을 기준으로 한 상대 경로입니다. `@/Users/me/shared/rules.md` 또는 `@~/.claude/personal.md`는 절대 경로입니다. 저장소에 넣고 싶지 않은 개인 설정에는 `@~/.claude/personal.md`를 사용합니다. - **4단계 깊이.** `AGENTS.md`는 `@docs/coding-style.md`를 가져올 수 있고, `coding-style.md`는 또 다른 파일을 가져올 수 있습니다. 최대 네 단계까지 가능합니다. 실제로 필요한 어떤 구조에도 충분합니다. - **백틱은 가져오기를 막습니다.** 텍스트에 `` `@README` ``라고 적혀 있으면 가져오기가 아니라 이름을 언급한 것입니다. 가져오기를 실행하지 않고 독자에게 가져오기 작동 방식을 설명할 때 유용합니다. - **프로젝트 외부 파일에 대한 승인.** 가져오기가 작업 디렉터리 밖을 가리키면(예: `@~/.claude/personal.md`) Claude Code는 처음 한 번 해당 파일 목록을 보여주는 대화상자를 표시합니다. 거부하면 외부 가져오기가 비활성화되고 대화상자는 다시 표시되지 않습니다. 프로젝트 루트의 `@AGENTS.md`는 대화상자를 띄우지 않습니다. 이렇게 하면 관련 없는 파일을 실수로 컨텍스트에 불러오는 일을 막을 수 있습니다. 설명한 프로젝트에서 이 설정으로 전환한 뒤 `CLAUDE.md`는 250줄에서 60줄로 줄었습니다. `@AGENTS.md`와 Claude Code에만 적용되는 규칙 다섯~일곱 개(위험한 디렉터리에서 plan mode 사용, admin 영역에서 건드리면 안 되는 것, 커밋 작성 방식)로 구성됩니다. 공유 규칙은 모두 Codex와 Cursor가 읽는 `AGENTS.md`에 있습니다. ## 심볼릭 링크와 가져오기는 언제 각각 선택해야 할까요?
핵심 요점 Anthropic은 `@AGENTS.md`를 통한 가져오기와 `ln -s AGENTS.md CLAUDE.md` 심볼릭 링크, 두 가지 방식을 제공합니다. 심볼릭 링크는 단순한 별칭이므로 파일을 변경할 필요가 없어 더 간편합니다. 하지만 세 가지 단점이 있습니다. Windows에서는 관리자 권한이 필요하고, `CLAUDE.md`에 Claude 전용 규칙을 추가할 수 없으며, Git diff에서 심볼릭 링크가 엉뚱한 항목처럼 보일 때가 있습니다. 가져오기는 범용적인 방법입니다. Claude 전용 규칙이 없다면 버전 2.1.277부터는 둘 다 필요 없습니다. Claude Code가 `AGENTS.md`를 직접 읽습니다.
문서에는 심볼릭 링크 옵션이 다음과 같이 나옵니다. ```bash ln -s AGENTS.md CLAUDE.md ``` 그리고 곧바로 Windows에 관한 솔직한 경고를 제시합니다.

저장소를 복제하는 사람 중 Windows를 사용하는 사람이 있다면 @AGENTS.md 가져오기를 사용하세요. Windows에서 심볼릭 링크를 만들려면 관리자 권한이나 Developer Mode가 필요합니다. 또한 core.symlinks가 활성화되어 있지 않으면 Git은 커밋된 링크를 일반 텍스트 파일로 체크아웃하므로, 해당 복사본에는 지침 대신 한 줄짜리 CLAUDE.md가 남습니다.

— Anthropic, https://code.claude.com/docs/en/memory
비교표: | 기준 | `@AGENTS.md` 가져오기 | 심볼릭 링크 `ln -s` | |----|----|----| | **Windows에서 관리자 권한 없이 작동** | 예 | 아니요 (Developer Mode 필요) | | **Claude 전용 규칙을 추가할 수 있음** | 예, 가져오기 아래에 | 아니요, 파일이 동일함 | | **Git에서 일반 markdown으로 표시** | 예 | 링크로 표시 (`core.symlinks`에 따라 다름) | | **여러 파일 가져오기 가능** | 예, 최대 네 단계 | 아니요, 일대일 | | **Claude Code의 캐싱/무효화** | CLAUDE.md 표준 동작 | 작동하지만 심볼릭 링크에는 메타데이터 관련 함정이 있음 | | **기본 선택** | 누구에게나 적합 | 크로스 플랫폼 사용이 중요하지 않을 때만 | 설명한 프로젝트에서는 가져오기를 사용합니다. 이유는 다음과 같습니다. 1. **팀이 여러 운영체제를 사용합니다.** 저는 Mac을 사용합니다. 예시의 팀은 Windows와 Mac 사용자가 대략 절반씩입니다. 저장소에 심볼릭 링크가 있으면 Developer Mode가 없는 Windows 사용자는 한 줄짜리 `AGENTS.md` 텍스트 파일로 체크아웃하게 됩니다. 그 때문에 이상한 버그가 생깁니다. 규칙이 작동할 때도 있고 아닐 때도 있는데, 이유를 알기 어렵습니다. 2. **Claude 전용 규칙이 필요합니다.** `@AGENTS.md` 아래에 있는 제 `CLAUDE.md`에는 “Claude Code” 섹션이 있고, 아키텍처 작업에는 `--effort high`를 사용하고 `git push` 전에 `npm run build`를 실행하며 `/api/v1/deploy`를 직접 호출하지 말라는 규칙이 있습니다. Codex는 이 명령들을 이해하지 못합니다. 3. **문제 해결이 쉽습니다.** 문제가 생기면 `CLAUDE.md`를 열어 가져오기와 재정의 항목을 확인합니다. 심볼릭 링크에는 “여기에 추가됨”이라는 표시가 없습니다. Claude Code 설정 문제를 디버깅하는 자세한 방법은 [안전 모드 가이드](https://ailoot.ai/blog/ko/claude-code-safe-mode-recovery/)를 참조하세요. Claude 전용 규칙이 없다면 버전 2.1.277부터 심볼릭 링크는 필요하지 않습니다. `CLAUDE.md`를 삭제하면 Claude Code가 `AGENTS.md`를 직접 읽습니다. 팀원 중 버전 2.1.277보다 오래된 버전을 사용하고 업데이트할 수 없는 사람이 있을 때만 심볼릭 링크를 유지하세요. Claude 전용 규칙이 있다면 열 번 중 아홉 번은 가져오기가 더 편리합니다. ## Codex, Cursor, Copilot, Windsurf, Gemini CLI는 무엇을 읽나요?
핵심 요점 각 도구는 자체 파일을 읽으며, 때로는 여러 파일을 읽습니다. Claude Code는 `CLAUDE.md`를 읽고, 2026년 9월부터는 프로젝트에 `CLAUDE.md`가 없으면 `AGENTS.md`도 읽습니다. Codex CLI는 `AGENTS.md`와 `AGENTS.override.md`를 읽습니다. Cursor는 이전 형식인 `.cursorrules` 또는 최신 형식인 `.cursor/rules/*.mdc`를 읽고, 2026년 여름부터는 `AGENTS.md`도 읽습니다. Copilot은 `.github/copilot-instructions.md` 또는 `.github/instructions/*.instructions.md`를 읽습니다. Windsurf는 이전 형식인 `.windsurfrules` 또는 최신 형식인 `.windsurf/rules/`를 읽습니다. Gemini CLI는 `GEMINI.md`를 읽습니다. Aider와 Cline은 이미 `AGENTS.md`를 지원합니다.
주요 도구 일곱 가지의 개요입니다(각 도구의 공식 문서를 기반으로 함). | 도구 | 기본 지침 파일 | 대안 | AGENTS.md를 읽나요? | |----|----|----|----| | **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, 관리 정책 | 예, 프로젝트에 `CLAUDE.md`가 없으면 (2.1.277부터), 그렇지 않으면 가져오기를 통해 | | **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | 예 (기본 지원) | | **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (사용 중단 예정) | 예 | | **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | 확장 기능을 통해 | | **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (사용 중단 예정) | 예 | | **Gemini CLI** | `GEMINI.md` | \- | 아니요 | | **Aider, Cline, opencode** | `AGENTS.md` | \- | 예 (기본 지원) | 이로부터 알 수 있는 것은 무엇일까요? 저장소에 `AGENTS.md`가 있고 Claude 전용 규칙이 필요한 경우 가져오기를 포함한 `CLAUDE.md`가 있으면 일곱 도구 중 다섯 개가 자동으로 최신 지침을 받습니다. 자체 파일이 있는 Cursor와 Windsurf는 그대로 두어도 됩니다(`AGENTS.md`도 읽음). 또는 `@AGENTS.md` 가져오기를 추가할 수 있습니다. 하지만 구문이 다르고 항상 지원되는 것은 아닙니다. 새 프로젝트에 가장 단순한 전략: 1. **공유 규칙을 모두 `AGENTS.md`에 넣으세요.** 규칙의 95%는 여기에 해당합니다. 2. **Claude 전용 규칙이 필요하면 `CLAUDE.md`를 만드세요.** 첫 줄에 `@AGENTS.md`를 넣고 그 아래에 Claude 전용 규칙 섹션을 추가합니다. 그런 규칙이 없다면 `CLAUDE.md`는 필요 없습니다. 버전 2.1.277부터 Claude Code가 `AGENTS.md`를 직접 읽습니다. 3. **드물게 Cursor 전용 기능이 필요할 때는 `.cursor/rules/`를 사용하세요.** 예를 들어 `@Codebase`와 `@Docs` 명령이 있습니다. 4. **Windsurf도 같은 방식으로 사용하세요.** 이전 `.windsurfrules`는 잊고, 해당 구문을 위한 패턴이 필요할 때만 새 `.windsurf/rules/`를 사용하세요. 이 접근 방식은 작업량의 20%로 이점의 80%를 얻습니다. 제 경험상 여러 팀이 섞여 있는 “Antigravity” 프로젝트를 정리할 때, 진실 공급원을 두 개(공유 규칙과 Claude 전용 규칙)보다 많이 유지하면 관리가 힘들어집니다. 팀원이 `.cursorrules`에 규칙을 추가하고 `AGENTS.md`를 잊으면 일주일 뒤 Cursor와 Codex가 서로 다른 답을 내놓게 됩니다. ## Claude Code의 /init은 기존 AGENTS.md를 어떻게 가져오나요?
핵심 요점 `/init`은 저장소의 기존 내용을 토대로 `CLAUDE.md`를 만들고 수작업 20~30분을 절약해 줍니다. 기본적으로 Cursor 규칙(`.cursor/rules/`, `.cursorrules`)과 Copilot 규칙(`.github/copilot-instructions.md`)을 가져오며, `CLAUDE_CODE_NEW_INIT=1` 모드에서는 `AGENTS.md`, `.windsurfrules`, `.clinerules`도 읽습니다. 이 모드는 대화형 다단계 흐름을 시작합니다. 질문을 하고 subagent를 통해 코드를 탐색한 뒤 작성 전에 계획을 제안합니다. 2026년 9월부터 `AGENTS.md`가 있는 프로젝트에서 `/init`을 사용하면 단점이 생깁니다. 새 `CLAUDE.md`가 `AGENTS.md` 직접 읽기를 비활성화해 규칙이 두 파일에 나뉘게 됩니다.
Anthropic은 문서에서 `/init`을 다음과 같이 설명합니다.

/init을 실행하면 다른 도구의 지침 파일을 읽고 관련 부분을 생성된 CLAUDE.md로 옮깁니다. Cursor 규칙은 .cursor/rules/ 또는 .cursorrules에서, Copilot 규칙은 .github/copilot-instructions.md에서 가져옵니다. CLAUDE_CODE_NEW_INIT=1을 설정하면 AGENTS.md, .devin/rules/, .windsurf/rules/ 또는 .windsurfrules, .clinerules도 읽습니다.

— Anthropic, https://code.claude.com/docs/en/memory
실제로는 어떤 의미일까요? 설명한 저장소에는 Cursor를 시험해 보던 때의 `.cursorrules`(약 80줄)와 직접 작성한 `AGENTS.md`(120줄)가 있었습니다. `claude /init`을 실행하자 두 파일을 가져와 비슷한 규칙을 중복 제거하고 1분 만에 깔끔한 `CLAUDE.md`를 만들었습니다. 나중에 확인하고 오래된 항목을 제거하고 제목이 있는 구조를 추가하는 정도로 수정했습니다. 처음부터 다시 쓰는 것보다 빨랐습니다. `/init`이 `AGENTS.md`도 읽는 대화형 모드는 환경 변수로 활성화합니다. ```bash CLAUDE_CODE_NEW_INIT=1 claude ``` `/init`이 시작되면 Claude는 구성할 항목(`CLAUDE.md`, skills, hooks), 프로젝트의 기술 스택, 테스트에 사용할 명령에 관해 몇 가지 확인 질문을 합니다. 그런 다음 subagent가 `package.json`, `README.md`, 설정 파일을 읽으며 코드베이스를 탐색하고 빠진 부분을 채웁니다. 마지막에는 저장하기 전에 수정할 수 있는 제안을 보여줍니다. 프로젝트를 시작할 때 Claude Code를 설정하는 자세한 방법은 [별도 가이드](https://ailoot.ai/blog/ko/spec-kit-claude-code-spec-driven-development/)를 참조하세요. 이제 단점을 살펴보겠습니다. 프로젝트에 이미 사용 중인 `AGENTS.md`가 있으면 `/init`은 그 옆에 규칙 복사본이 들어 있는 `CLAUDE.md`를 만듭니다. 그 시점부터 Claude Code는 기본적으로 `CLAUDE.md`만 읽으므로 다시 진실 공급원이 두 개가 됩니다. 사용자는 `AGENTS.md`를 업데이트하지만 Claude는 오래된 복사본으로 계속 작업합니다. `/import` 명령도 비슷하게 `AGENTS.md`의 일회성 복사본을 `CLAUDE.md`에 덧붙입니다. 단일 공급원을 유지하려면 `/init`을 마친 뒤 `CLAUDE.md` 첫 줄에 `@AGENTS.md` 가져오기를 넣고 `AGENTS.md`와 반복되는 내용을 `CLAUDE.md`에서 제거하세요. `/init`은 새 프로젝트를 시작하거나 Cursor 또는 Copilot에서 옮길 때 적절한 출발점입니다. 온라인에서 “최고의 CLAUDE.md 템플릿”을 찾을 필요는 없습니다. Anthropic이 저장소 내용을 이미 반영합니다. 프로젝트에 이미 사용 중인 `AGENTS.md`가 있고 Claude 전용 규칙이 없다면 `/init`은 필요하지 않습니다. Claude Code가 `AGENTS.md`를 직접 읽습니다. ## 공유 지침과 Claude 전용 지침은 어떻게 분리하나요?
핵심 요점 어떤 AI 에이전트든 이해할 수 있는 규칙은 `AGENTS.md`에 넣으세요. 건드리면 안 되는 것, 브랜치 이름을 짓는 방법, `.env`에 비밀 정보가 들어 있다는 사실, 테스트에 쓸 명령 등이 해당합니다. Claude Code 전용 규칙은 `CLAUDE.md`(가져오기 아래)에 넣으세요. plan mode, skills, hooks, skill 참조, 버전별 모델 이름 등이 해당합니다. 구분은 간단합니다. 규칙이 “Claude는 해야 한다”로 시작하면 `CLAUDE.md`에, “도구는 해야 한다”로 시작하면 `AGENTS.md`에 둡니다.
저는 이 원칙에 따라 분리합니다. `AGENTS.md`에 넣을 공유 규칙: - **코드에서 건드리지 말아야 할 것.** `.env`, `node_modules`, `prisma/migrations` 폴더(`prisma migrate`를 통해서만 변경), `.next/`, `.git/`. - **이름을 짓는 방법.** 브랜치: `feat/`, `fix/`, `chore/`. 커밋: 간단한 설명 앞에 `feat:`, `fix:`, `docs:` 접두사를 붙임. 컴포넌트 파일은 `kebab-case`로 작성. - **테스트/lint 명령.** `npm run build`, `npm run lint`, `npm test`. `git push` 전에 실행할 명령. - **아키텍처 원칙.** `src/lib/`과 `src/components/`에 들어갈 내용, 비즈니스 로직과 UI가 위치할 곳. - **보안.** 비밀 정보를 절대 커밋하지 않음. 프로덕션 데이터베이스에는 `prod-psql`로만 접근. 프로덕션 SSH 접속에는 `root@IP`가 아니라 `prod` 별칭만 사용. `CLAUDE.md`(`@AGENTS.md` 아래)에 넣을 Claude 전용 규칙: - **Plan mode.** 위험한 디렉터리(예: `src/billing/`)에서 변경할 때는 `plan mode`를 사용. - **Effort 수준.** 아키텍처 작업에는 `--effort high`, 일상적인 작업에는 `medium`을 사용. - **Skills.** 어떤 상황에 어떤 AI 에이전트와 skills를 실행할지. 예를 들어 “가이드를 작업할 때 `build-masterskaya-guide` skill을 실행한다.” - **Claude 메모리.** 자동 메모리에 넣을 내용과 `CLAUDE.local.md`에 넣을 내용. Claude 메모리에 대한 자세한 내용은 [Memory와 CLAUDE.md 가이드](https://ailoot.ai/blog/ko/claude-memory-claude-md-auto-memory/)를 참조하세요. - **Hooks.** `.claude/settings.json`에 hooks가 설정되어 있으면 `CLAUDE.md`에 기능을 설명합니다(Codex와 Cursor는 이를 알지 못하며 알 필요도 없습니다). - **Skills와 명령.** 자주 쓰는 slash 명령 목록(`/init`, `/cd`, `/memory`, `/plan`). 경계가 항상 분명한 것은 아닙니다. 예를 들어 “`main`에 `git push --force`를 절대 실행하지 않는다”는 명백한 공유 규칙이므로 `AGENTS.md`에 둡니다. 하지만 “hot 브랜치에 `git push`를 실행할 때 먼저 plan mode를 사용한다”는 Claude Code 전용 규칙이므로 `CLAUDE.md`에 둡니다. 다음을 확인해 보세요. “내일 Claude Code를 없애고 Codex만 남겨도 이 규칙은 적용될까?” 그렇다면 `AGENTS.md`에 넣으세요. 아니라면 `CLAUDE.md`에 넣으세요. ## AGENTS.md에는 무엇을 넣고, CLAUDE.md 또는 .claude/rules에는 무엇을 넣어야 하나요?
핵심 요점 규모가 큰 프로젝트에서는 `AGENTS.md` 하나로 충분하지 않습니다. 파일이 너무 커지고 모든 에이전트가 불필요한 내용을 컨텍스트에 가져옵니다. 해결책은 주제별로 파일을 나누고 경로에 따라 규칙을 적용하는 YAML 프런트매터 `paths:`를 사용하는 `.claude/rules/` 디렉터리입니다. 예를 들어 Claude가 `src/api/`에서 작업할 때만 API 규칙을 적용할 수 있습니다. 이렇게 하면 컨텍스트 창 공간을 크게 절약합니다. Cursor에서는 `.cursor/rules/`, Windsurf에서는 `.windsurf/rules/`가 이에 해당합니다.
규칙이 200줄을 넘으면 나눌 때입니다. Anthropic 문서는 파일당 200줄을 목표로 권장합니다. `CLAUDE.md`가 너무 길면 Claude가 읽는 것처럼 보여도 지침을 따르는 빈도가 줄어들기 시작하기 때문입니다. 제가 큰 프로젝트에서 사용하는 구조: ``` my-project/ ├── AGENTS.md # 100-150 lines, shared ├── CLAUDE.md # 30-50 lines: @AGENTS.md + Claude-only └── .claude/ ├── CLAUDE.md # alternative to root file, same file └── rules/ ├── api.md # with paths: ['src/api/**'] ├── components.md # with paths: ['src/components/**'] ├── testing.md # without paths, always active └── security.md # without paths, always active ``` `.claude/rules/`의 각 파일에는 프런트매터를 넣을 수 있습니다. ```markdown --- paths: - "src/api/**/*.ts" --- # API rules - Every endpoint validates input with zod - Errors use the standard `{error, code}` format - OpenAPI comments are required ``` Claude는 이 패턴에 해당하는 파일을 작업할 때만 해당 규칙을 불러옵니다. `src/components/Button.tsx`를 수정하면 API 규칙은 컨텍스트에 추가되지 않습니다. 그러면 컨텍스트 창에는 관련 있는 내용만 들어갑니다. `.claude/rules/` 디렉터리는 `CLAUDE.md` 없이도 작동합니다. 프로젝트에 `AGENTS.md`만 있으면 규칙은 그 파일과 함께 로드되며 `AGENTS.md`를 직접 읽는 기능을 비활성화하지 않습니다. Cursor와 Windsurf도 `.cursor/rules/` 및 `.windsurf/rules/` 디렉터리를 통해 같은 방식을 지원합니다. AGENTS.md 표준은 이 디렉터리를 참조할 수 있지만 도구 간 구문은 아직 완전히 안정되지 않았습니다. 공유 규칙은 `AGENTS.md`에 두고 경로별 규칙은 `.claude/rules/` 및 `.cursor/rules/`에 복제하는 편이 안전합니다. 이런 사례는 드문 특수 상황이지 규칙의 대부분이 아닙니다. CLAUDE.md를 둘 수 있는 위치(범위가 넓은 순서에서 좁은 순서): | 수준 | 위치 | 목적 | |----|----|----| | **관리 정책** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | 기업 규칙, IT/DevOps | | **사용자** | `~/.claude/CLAUDE.md` | 모든 프로젝트에 적용되는 개인 설정 | | **프로젝트** | `./CLAUDE.md` 또는 `./.claude/CLAUDE.md` | 프로젝트 팀 규칙 | | **로컬** | `./CLAUDE.local.md` (`.gitignore`에 포함) | 특정 프로젝트를 위한 개인 설정 | `~/.claude/CLAUDE.md`에는 두 가지 규칙을 넣을 수 있습니다. “사용자가 선호하는 언어로 응답하기”와 “Ailoot를 정확히 이렇게 표기하기”입니다. 이 규칙들은 모든 프로젝트에 적용되므로 저장소마다 복제할 필요가 없습니다. 네 수준 가운데 프로젝트 수준의 `CLAUDE.md`와 `CLAUDE.local.md`만 `AGENTS.md`를 직접 읽는 기능을 비활성화합니다. 개인 `~/.claude/CLAUDE.md`와 관리 정책은 방해되지 않습니다. Claude Code는 이들을 `AGENTS.md`와 함께 읽습니다. ## 프로젝트의 AGENTS.md가 이미 오래되었다면 어떻게 해야 하나요?
핵심 요점 `AGENTS.md`를 2025년에 Codex나 Aider용으로 만들고 그 뒤로 편집하지 않았다면 Claude Code에서 프로젝트를 열고 파일을 편집하도록 Claude에 요청하세요. AGENTS.md는 계속 갱신되는 문서이며 Linux Foundation 사양도 업데이트됩니다. 최신 상태로 유지하는 기본 원칙은 각 규칙이 “Claude/Codex에게 반복해서 말하기 지겨운 것이 무엇인가?”라는 질문에 답해야 한다는 것입니다. 그렇지 않으면 보관하세요.
제가 설명한 프로젝트에는 2025년 5월에 만든 `AGENTS.md`가 있었습니다. 180줄이었고 많은 내용이 오래되었습니다(이후 바뀐 Anthropic API 엔드포인트, 더 이상 존재하지 않는 `claude --tools` 구문 예시, 오래된 구조를 기준으로 한 `~/.claude/projects/` 규칙 등). 업데이트할 때 사용한 계획: 1. **plan mode에서 `claude`로 검토합니다.** 저장소를 열고 `claude --safe-mode`를 실행한 다음 이렇게 요청합니다. “`AGENTS.md`를 다시 읽고 오래되었거나 반복되는 항목의 목록을 제안하세요. 편집하지 말고 목록만 작성하세요.” 2분 만에 검토할 항목 23개의 목록을 받았습니다. 2. **명백하게 더 이상 유효하지 않은 항목을 제거합니다.** 23개 가운데 명령 구문, 엔드포인트, 플래그 이름 등 9개가 분명히 오래된 내용이었습니다. 해당 행을 삭제했습니다. 3. **중복을 합칩니다.** 다른 6개 항목은 표현만 달리해 같은 내용을 반복했습니다(“강제 푸시하지 말 것”, “`--force`를 절대 사용하지 말 것”, “`git push -f`를 피할 것”). 이를 한 행으로 합쳤습니다. 4. **새 항목을 추가합니다.** “오류 패턴 하나당 한 행” 원칙에 따라 지난 한 달 동안 Claude/Codex가 반복해서 잘못 처리한 점을 추가했습니다. 새 항목은 8개였습니다. 5. **최종 검토를 위해 subagent를 실행합니다.** “모순, 모호함, 중복을 찾아 주세요”라는 지시로 Claude 검토를 요청했습니다. 더 명확하게 표현할 수 있는 항목 세 개를 찾아 수정했습니다. 한 시간 뒤 `AGENTS.md`는 110줄로 정리되었고 최신 상태였으며, 모든 행의 내용을 직접 알고 있었습니다. 여기서 30줄짜리 `CLAUDE.md`를 만드는 일은 쉬웠습니다. 이후 Codex가 테스트를 훨씬 신중하게 다루기 시작했습니다. Codex가 선의로 따르던 오래된 지침이 “이상한” 결정의 원인이었을 것으로 생각합니다. `AGENTS.md`를 계속 관리하기 위한 핵심 원칙: - **모든 규칙은 반복되는 실수에 대응해야 합니다.** 한 달 동안 어떤 규칙을 떠올릴 일이 한 번도 없었다면 남겨둘 이유가 없습니다. - **이론이 아니라 명령으로 규칙을 작성하세요.** “공백 두 칸을 사용한다”는 규칙입니다. “코드 스타일을 깔끔하게 유지한다”는 규칙이 아닙니다. - **일반론보다 구체적인 지침이 낫습니다.** “`git push` 전에 `npm run build`를 실행한다”는 규칙입니다. “변경 사항을 테스트한다”는 규칙이 아닙니다. ## 이 설정에서 확실히 작동하지 않는 것은 무엇인가요?
핵심 요점 `@AGENTS.md`를 가져와도 서로 다른 도구가 하나처럼 동작하지는 않습니다. 각 도구에는 고유한 특성이 있습니다. Codex CLI는 `.claude/rules/`나 hooks를 알지 못합니다. Cursor에는 자체 자동 완성 엔진이 있어 텍스트를 완성할 때 CLAUDE.md를 읽지 않습니다. Copilot은 `.github/copilot-instructions.md`를 따르며 AGENTS.md의 규칙만으로는 충분하지 않습니다. 이는 “파일 하나 = 동작 하나”가 아니라 “기본 규칙을 위한 하나의 출처가 있고 각 도구에는 고유한 추가 사항이 있다”는 의미입니다.
이 설정을 6개월간 사용하면서 어렵게 배운 점 몇 가지: **1. Cursor 자동 완성은 AGENTS.md를 사용하지 않습니다.** Cursor가 편집기에서 한 줄을 완성할 때 실시간으로 `AGENTS.md`를 읽지 않습니다. 별도의 빠른 엔진이 작동합니다. AGENTS.md의 규칙은 Cursor 안에서 채팅 요청을 보낼 때만 영향을 줍니다. 따라서 AGENTS.md에 “`var`를 쓰지 말고 `const`를 써라”라고 적어도 자동 완성에는 영향을 주지 않습니다. ESLint나 TypeScript 설정을 통해 구성해야 합니다. **2. AGENTS.md의 Claude Code hooks는 Codex에서 작동하지 않습니다.** `.claude/settings.json`에 특정 작업을 차단하는 PreToolUse hook이 설정되어 있다면 이 정보는 Claude에게만 유용합니다. Codex는 hooks를 알지 못합니다. Codex 입장에서는 “도구가 알아서 결정한다”는 뜻입니다. “X를 하지 말 것”은 `AGENTS.md`에, “X를 물리적으로 차단하는 hook이 있다”는 설명은 가져오기 아래의 `CLAUDE.md`에 쓰는 편이 좋습니다. **3. Copilot과 `.github/copilot-instructions.md`.** GitHub Copilot은 자체 파일을 읽으며 아직 AGENTS.md를 잘 읽지 못합니다. 팀에서 Copilot을 적극적으로 사용한다면 규칙을 축약한 `.github/copilot-instructions.md`를 별도로 추가하거나 AGENTS.md를 인식하는 [Copilot Extensions](https://github.com/marketplace?type=apps&category=copilot-extensions)을 사용하세요. 빠르게 변하는 분야이므로 3~6개월 후에는 상황이 달라질 수 있습니다. **4. Git은 심볼릭 링크를 CLAUDE.md의 변경으로 추적하지 않습니다.** `ln -s AGENTS.md CLAUDE.md`를 실행하고 일주일 뒤 `AGENTS.md`를 업데이트하면 Git에는 `AGENTS.md`의 diff만 표시됩니다. 이는 정상 동작이지만 PR을 검토하는 동료는 심볼릭 링크를 통해 `CLAUDE.md`도 업데이트되었다는 사실을 놓칠 수 있습니다. 해결책은 PR 설명에 “`AGENTS.md` 업데이트; Claude Code는 심볼릭 링크를 통해 같은 파일을 확인”이라고 명확히 적는 것입니다. **5. 깊게 중첩된 가져오기는 디버깅하기 어렵습니다.** `AGENTS.md`가 `@docs/coding-style.md`를 가져오고, 그 파일이 `@docs/typescript.md`를 가져오며, 규칙끼리 충돌하면 문제를 해결하기 어렵습니다. 저는 가져오기를 한 단계(`CLAUDE.md` → `AGENTS.md`)로 제한하고 더 중첩하지 않습니다. Anthropic은 어떤 파일을 불러왔는지 기록하는 `InstructionsLoaded` hook을 제공합니다. 계층형 설정을 디버깅할 때 유용합니다. 참고: 이 hook은 가져오기나 심볼릭 링크를 통해 포함된 `AGENTS.md`에는 실행되지만 Claude Code가 직접 읽은 `AGENTS.md`에는 실행되지 않습니다.
### 출처 - [Claude Code 메모리 문서 - AGENTS.md 섹션](https://code.claude.com/docs/en/memory#agents-md) - Claude Code가 AGENTS.md를 직접 읽는 경우, Project instructions 설정, 가져오기와 심볼릭 링크, `/init` 동작을 설명합니다. - [Claude Code 메모리 문서 - 추가 파일 가져오기](https://code.claude.com/docs/en/memory#import-additional-files) - `@path/to/file` 구문, 4단계 깊이, 상대 경로와 절대 경로를 설명합니다. - [agents.md - Linux Foundation 표준](https://agents.md/) - 공식 AGENTS.md 표준과 지원 도구 목록입니다. - [Cursor Rules 문서](https://docs.cursor.com/context/rules-for-ai) - Cursor가 읽는 내용(`.cursor/rules/*.mdc`, AGENTS.md)을 설명합니다. - [GitHub Copilot 사용자 지정 지침](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) - `.github/copilot-instructions.md` 형식을 설명합니다. - [Linux Foundation의 AGENTS.md 사양](https://aaif.io/projects/agents-md/) - 계속 갱신되는 사양입니다.
저녁 한 번으로 준비하는 완전한 바이브 코딩 설정: **AI 클론 + 세컨드 브레인 + 컨텍스트 엔지니어링**. [Ailoot](https://ailoot.ai/)를 알아보세요. ## 2026년 Claude Code, Codex, Cursor를 위한 하나의 지침 파일: 자주 묻는 질문 ### 심볼릭 링크 대신 가져오기를 쓰는 경우는 언제인가요? Claude 전용 내용을 추가하거나 팀원이 Windows를 쓴다면 `CLAUDE.md`에 `@AGENTS.md`를 넣으세요. 심볼릭 링크는 두 이름이 같은 내용을 가리키므로 Claude 전용 섹션을 별도로 담을 수 없습니다. ### 공유 지침이 로드됐는지 어떻게 확인하나요? `/memory`에서 지침 파일 목록을 확인하세요. 설정상 `CLAUDE.md`나 `CLAUDE.local.md`가 AGENTS.md 직접 로드를 막는다면 가져오기를 추가하거나 둘 다 로드하는 설정을 선택한 뒤 새 세션을 시작하세요. ## Ailoot · 회사와 그 프로젝트 포트폴리오 Ailoot는 축적된 운영 경험, 폭넓은 고객 기반, 안정적인 서비스, 지속적인 KPI 관리를 바탕으로 합니다. 회사와 그 프로젝트 포트폴리오: 수백만 고객, 매월 수십억 규모의 매출. Ailoot는 이러한 운영 경험을 고객의 제품, 에이전트, 애플리케이션, 자동화에서 AI 기능을 이용할 수 있는 API 접근에 활용합니다.