2026년 Claude Code, Codex, Cursor를 위한 하나의 지침 파일

서비스에 대한 자세한 내용은 Ailoot 문서를 참조하세요.

Claude Code, Codex, Cursor를 함께 사용하면 무엇이 달라질까요?#

여기서 설명하는 예시에서는 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의 문제가 아니라 진실 공급원이 여러 개인 모든 시스템에 있는 기본적인 함정입니다. 이 문제는 멀티 에이전트 작업 가이드에서 더 자세히 다룹니다.

2026년 6월, Anthropic의 Claude Code 메모리 문서는 공유 파일과 가져오기를 조합하는 해결책을 제시했습니다. 2026년 9월부터는 프로젝트에 CLAUDE.md가 없으면 Claude Code가 AGENTS.md를 직접 읽습니다. Claude 전용 규칙이 있을 때는 가져오기가 필요합니다. 아래에서 AGENTS.md 하나만으로 충분한 경우, 가져오기를 설정하는 방법, 공유 규칙과 Claude 전용 규칙을 분리하는 방법을 설명합니다.

Claude Code는 AGENTS.md를 직접 읽나요?#

2026년 9월 전까지 답은 “아니요”였습니다. AGENTS.md 지원을 요청한 이슈 #6235는 2025년 8월부터 열려 있었고 2026년 8월 17일에 종료되었습니다. 그동안 메모리 문서는 한 가지 해결책을 제시했습니다. CLAUDE.md를 만들고 AGENTS.md를 가져오기로 포함하는 방법입니다. 버전 2.1.277부터 문서 내용이 달라졌습니다.

프로젝트에 어떤 파일이 있는지에 따라 Claude Code가 읽는 내용이 정확히 달라집니다.

이 확인에서는 작업 디렉터리와 모든 상위 디렉터리에 있는 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.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 안에 어떻게 가져오나요?#

공식 문서의 최소 작동 예시:

@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를 사용합니다.

가져오기 작동 방식에 관한 문서 인용:

실용적인 세부 사항 몇 가지:

• 상대 경로와 절대 경로. @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에 있습니다.

심볼릭 링크와 가져오기는 언제 각각 선택해야 할까요?#

문서에는 심볼릭 링크 옵션이 다음과 같이 나옵니다.

ln -s AGENTS.md CLAUDE.md

그리고 곧바로 Windows에 관한 솔직한 경고를 제시합니다.

비교표:

설명한 프로젝트에서는 가져오기를 사용합니다. 이유는 다음과 같습니다.

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 설정 문제를 디버깅하는 자세한 방법은 안전 모드 가이드를 참조하세요.

Claude 전용 규칙이 없다면 버전 2.1.277부터 심볼릭 링크는 필요하지 않습니다. CLAUDE.md를 삭제하면 Claude Code가 AGENTS.md를 직접 읽습니다. 팀원 중 버전 2.1.277보다 오래된 버전을 사용하고 업데이트할 수 없는 사람이 있을 때만 심볼릭 링크를 유지하세요. Claude 전용 규칙이 있다면 열 번 중 아홉 번은 가져오기가 더 편리합니다.

Codex, Cursor, Copilot, Windsurf, Gemini CLI는 무엇을 읽나요?#

주요 도구 일곱 가지의 개요입니다(각 도구의 공식 문서를 기반으로 함).

이로부터 알 수 있는 것은 무엇일까요? 저장소에 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를 어떻게 가져오나요?#

Anthropic은 문서에서 /init을 다음과 같이 설명합니다.

실제로는 어떤 의미일까요? 설명한 저장소에는 Cursor를 시험해 보던 때의 .cursorrules(약 80줄)와 직접 작성한 AGENTS.md(120줄)가 있었습니다. claude /init을 실행하자 두 파일을 가져와 비슷한 규칙을 중복 제거하고 1분 만에 깔끔한 CLAUDE.md를 만들었습니다. 나중에 확인하고 오래된 항목을 제거하고 제목이 있는 구조를 추가하는 정도로 수정했습니다. 처음부터 다시 쓰는 것보다 빨랐습니다.

/init이 AGENTS.md도 읽는 대화형 모드는 환경 변수로 활성화합니다.

CLAUDE_CODE_NEW_INIT=1 claude

/init이 시작되면 Claude는 구성할 항목(CLAUDE.md, skills, hooks), 프로젝트의 기술 스택, 테스트에 사용할 명령에 관해 몇 가지 확인 질문을 합니다. 그런 다음 subagent가 package.json, README.md, 설정 파일을 읽으며 코드베이스를 탐색하고 빠진 부분을 채웁니다. 마지막에는 저장하기 전에 수정할 수 있는 제안을 보여줍니다. 프로젝트를 시작할 때 Claude Code를 설정하는 자세한 방법은 별도 가이드를 참조하세요.

이제 단점을 살펴보겠습니다. 프로젝트에 이미 사용 중인 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 전용 지침은 어떻게 분리하나요?#

저는 이 원칙에 따라 분리합니다. 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 가이드를 참조하세요.
• 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에는 무엇을 넣어야 하나요?#

규칙이 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/의 각 파일에는 프런트매터를 넣을 수 있습니다.

---
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를 둘 수 있는 위치(범위가 넓은 순서에서 좁은 순서):

~/.claude/CLAUDE.md에는 두 가지 규칙을 넣을 수 있습니다. “사용자가 선호하는 언어로 응답하기”와 “Ailoot를 정확히 이렇게 표기하기”입니다. 이 규칙들은 모든 프로젝트에 적용되므로 저장소마다 복제할 필요가 없습니다.

네 수준 가운데 프로젝트 수준의 CLAUDE.md와 CLAUDE.local.md만 AGENTS.md를 직접 읽는 기능을 비활성화합니다. 개인 ~/.claude/CLAUDE.md와 관리 정책은 방해되지 않습니다. Claude Code는 이들을 AGENTS.md와 함께 읽습니다.

프로젝트의 AGENTS.md가 이미 오래되었다면 어떻게 해야 하나요?#

제가 설명한 프로젝트에는 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를 실행한다”는 규칙입니다. “변경 사항을 테스트한다”는 규칙이 아닙니다.

이 설정에서 확실히 작동하지 않는 것은 무엇인가요?#

이 설정을 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을 사용하세요. 빠르게 변하는 분야이므로 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에는 실행되지 않습니다.

저녁 한 번으로 준비하는 완전한 바이브 코딩 설정: AI 클론 + 세컨드 브레인 + 컨텍스트 엔지니어링.

Ailoot를 알아보세요.