CLAUDE.md, AGENTS.md, .cursorrules: 하나의 설정 전략

제가 함께 일하는 대부분의 엔터프라이즈 개발 팀은 이제 둘 이상의 AI 코딩 에이전트를 운영합니다. 플랫폼 팀은 Claude Code로 표준화했고, 프런트엔드 팀은 Cursor를 구독하며, 조직의 GitHub Enterprise 계약을 통해 모두가 GitHub Copilot을 갖고 있고, 누군가는 Codex에 백그라운드 작업을 쌓아 두며, 데이터 팀은 노트북 절반에 Gemini CLI를 설치했습니다. 각 도구는 자기만의 지침 파일을 읽고, 각 파일은 그 도구를 가장 먼저 도입한 사람이 썼습니다. 6개월이 지나면 CLAUDE.md의 빌드 명령은 틀려 있고, .cursorrules는 팀이 지금 의존하는 라이브러리를 여전히 금지하고 있으며, 어느 파일이 권위 있는 파일인지 아무도 말하지 못합니다. 이 가이드는 그 상황을 위한 단일 설정 전략을 제시합니다. AGENTS.md라는 벤더 중립적 단일 진실 공급원, 그 주위를 감싸는 얇은 도구별 어댑터, 무엇이 도구 전용으로 남아야 하는지에 대한 명확한 규칙, 그리고 파일을 정직하게 유지하는 거버넌스입니다. 도구가 무엇을 읽는지에 관한 모든 주장은 해당 벤더의 현재 문서와 대조해 확인했으며 본문에 링크했습니다.

문제: 다섯 개의 도구, 다섯 개의 파일, 그리고 드리프트

지침 파일은 새 엔지니어에게 건네는 온보딩 문서와 같습니다. 다만 그 엔지니어는 매 세션 시작마다 문서를 읽고, 내용이 틀려도 절대 반박하지 않습니다. 그래서 드리프트는 문서 드리프트가 한 번도 그랬던 적 없는 방식으로 비싸집니다. 오래된 README.md는 신입의 오후 한 번을 낭비할 뿐입니다. 오래된 지침 파일은 저장소의 모든 에이전트 세션을 같은 잘못된 길로 보내고, 도구마다 파일이 따로 있기 때문에 드리프트는 고르지도 않습니다. Claude Code는 새 테스트 러너를 알고 있는데 Copilot은 여전히 옛 러너를 실행할 수 있습니다.

가장 흔한 두 파일은 엔터프라이즈 팀용 CLAUDE.md 가이드와 엔터프라이즈 AI 코딩용 AGENTS.md 가이드에서 각각 다뤘습니다. 그 글들은 각 파일 안에 무엇이 들어가는지 설명합니다. 이 글은 그 위에 자리하며, 검색 쿼리와 디스커버리 콜에서 계속 등장하는 질문에 답합니다. 팀이 여러 에이전트를 운영할 때 어느 파일이 이기며, 같은 규칙의 복사본 다섯 개를 유지하는 일을 어떻게 멈추는가?

짧은 답은, 복사본 다섯 개를 유지하지 않는다는 것입니다. 하나만 유지하고, 각 도구가 그것을 정확히 어떻게 소비하는지 이해하는 것입니다.

각 도구가 읽는 파일

아래 표는 제가 이 문제를 풀기 시작할 때 있었으면 했던 참조표입니다. 각 벤더의 현재 문서를 바탕으로 작성했으며, 표 다음의 도구별 절에 세부 사항과 링크를 담았습니다.

Claude Code: CLAUDE.md와 그 계층

Claude Code의 메모리 문서는 로드 순서대로 네 가지 범위를 나열합니다. IT가 배포하는 관리형 정책 파일(macOS의 /Library/Application Support/ClaudeCode/CLAUDE.md, Linux와 WSL의 /etc/claude-code/CLAUDE.md, Windows의 C:\Program Files\ClaudeCode\CLAUDE.md), ~/.claude/CLAUDE.md의 사용자 파일, ./CLAUDE.md 또는 ./.claude/CLAUDE.md의 프로젝트 파일, 그리고 개인 메모용으로 gitignore 처리되는 ./CLAUDE.local.md입니다. Claude는 시작 시 작업 디렉터리와 그 상위 모든 디렉터리의 CLAUDE.md 파일을 로드하고, 파일 시스템 루트에서 아래로 연결해 가장 가까운 파일이 마지막에 읽히게 하며, 하위 디렉터리 파일은 그 하위 디렉터리의 파일을 읽거나 쓰거나 편집할 때만 로드합니다.

공유 전략에 중요한 세부 사항이 세 가지 있습니다. 첫째, @path/to/file 가져오기 구문은 다른 파일을 컨텍스트로 끌어오며, 가져오기를 포함한 파일을 기준으로 상대 경로를 해석하고, 최대 4단계까지 중첩할 수 있습니다. 코드 스팬과 펜스 블록 안의 가져오기는 무시됩니다. 둘째, Anthropic의 지침은 CLAUDE.md 파일당 200줄 미만을 목표로 하라는 것이며, 가져온 파일은 가져오는 파일과 함께 로드되므로 가져오기가 그 비용을 줄여 주지는 않습니다. 셋째, .claude/rules/*.md 파일은 프로젝트 CLAUDE.md와 함께 로드되며, paths: 프런트매터 필드로 규칙을 일치하는 파일에 범위 지정하면 Claude가 그 파일을 작업할 때만 로드됩니다. 스킬과 훅을 포함한 Claude Code 저장소의 계층별 전체 그림이 필요하면 Claude Code 프로젝트의 해부학을 읽어 보십시오.

OpenAI Codex: 재정의 파일이 있는 AGENTS.md

Codex는 이 형식이 만들어진 바로 그 도구이며, Codex의 AGENTS.md 문서는 제가 찾은 중첩 설명 중 가장 정밀합니다. Codex는 먼저 홈 디렉터리(~/.codex 또는 CODEX_HOME)를 살피는데, 여기서는 비어 있지 않은 첫 파일만 사용하며 AGENTS.override.md를 AGENTS.md보다 선호합니다. 그다음 보통 Git 루트인 프로젝트 루트에서 시작해 현재 디렉터리까지 내려가면서, 디렉터리당 최대 한 파일을 AGENTS.override.md, AGENTS.md, 그리고 project_doc_fallback_filenames에 나열된 이름 순으로 가져갑니다. 파일들은 루트에서 아래로 빈 줄로 구분되어 연결되므로, 작업 디렉터리에 가까운 지침이 프롬프트 뒤쪽에 나타나 우선합니다.

대부분의 팀이 놓치는 제한은 project_doc_max_bytes가 결합 크기를 기본 32 KiB로 제한하며, 체인이 그 한도에 도달하면 Codex가 파일 추가를 멈춘다는 점입니다. 비대해진 루트 파일은 패키지 수준 파일을 조용히 컨텍스트 밖으로 밀어낼 수 있습니다.

GitHub Copilot: 세 종류의 지침 파일

GitHub의 저장소 사용자 지정 지침 문서는 저장소 전체용 .github/copilot-instructions.md, 프런트매터에 applyTo glob(및 code-review 또는 cloud-agent 값의 선택적 excludeAgent)이 있는 .github/instructions/ 아래의 경로별 NAME.instructions.md 파일, 그리고 에이전트 지침 파일을 설명합니다. 에이전트 지침 파일은 저장소 어디에나 둘 수 있는 AGENTS.md(가장 가까운 파일이 우선) 또는 루트의 단일 CLAUDE.md나 GEMINI.md입니다. 경로별 파일이 일치하고 저장소 전체 파일도 있으면 둘 다 사용됩니다. 소스 간에는 개인 지침이 저장소 지침보다, 저장소 지침이 조직 지침보다 우선하지만, 관련된 모든 집합이 모델에 제공되므로 GitHub의 조언은 순위에 의존하지 말고 모순을 피하라는 것입니다.

함정은 지원 매트릭스에 있습니다. Copilot 클라우드 에이전트, GitHub.com의 Copilot 코드 리뷰, VS Code의 Copilot Chat, Copilot CLI는 AGENTS.md를 읽습니다. GitHub.com, Visual Studio, JetBrains IDE의 Copilot Chat은 .github/copilot-instructions.md는 읽지만 AGENTS.md는 읽지 않습니다. 또한 Copilot 코드 리뷰는 기본 브랜치가 아닌 풀 리퀘스트의 헤드 브랜치에서 지침을 읽는데, 같은 PR에서 파일을 바꿀 때 이 점이 중요합니다.

Cursor: .cursor/rules와 AGENTS.md

Cursor의 규칙 문서는 프로젝트 규칙을 .cursor/rules/ 아래의 .mdc 파일(프런트매터가 없는 일반 .md는 무시됨)로 설명하며, 프런트매터 필드는 세 가지입니다. alwaysApply: true는 규칙을 모든 채팅에 넣고, globs는 일치하는 파일이 컨텍스트에 있을 때 규칙을 첨부하며, description만 있으면 에이전트가 규칙을 끌어올지 스스로 결정합니다. 규칙은 Team Rules, Project Rules, User Rules 순으로 병합되며 충돌 시 앞선 소스가 우선합니다. Team Rules는 Team 및 Enterprise 플랜에서 Cursor 대시보드로 관리하며, 사용자가 비활성화할 수 없도록 강제할 수 있습니다. Cursor는 또한 규칙을 500줄 미만으로 유지하라고 요청하고, 규칙에서 참조한 파일은 인라인되지 않으며 에이전트가 필요하다고 판단할 때만 도구로 읽는다고 경고합니다.

AGENTS.md는 단순한 경우에 .cursor/rules의 일반 Markdown 대안으로 문서화되어 있으며, 프로젝트 루트와 하위 디렉터리에서 지원되고, 중첩 지침은 상위와 결합되며 더 구체적인 파일이 우선합니다. 오래된 가이드들이 설명하는 단일 .cursorrules 파일은 현재 규칙 페이지에 전혀 나타나지 않습니다. 레거시로 취급하고 마이그레이션하십시오.

Gemini CLI: 이름을 바꿀 수 있는 GEMINI.md

Gemini CLI의 컨텍스트 파일 문서는 전역 ~/.gemini/GEMINI.md, 구성된 워크스페이스 디렉터리와 그 상위에서 발견되는 GEMINI.md 파일, 그리고 도구가 접근하는 모든 디렉터리에서 신뢰할 수 있는 루트까지의 파일을 적시에 로드하는 동작을 설명합니다. 발견된 모든 것은 연결되어 매 프롬프트와 함께 전송됩니다. @file.md 가져오기는 상대 경로와 절대 경로를 지원합니다. 여기서 중요한 기능은 settings.json의 context.fileName으로, 단일 이름이나 목록을 받으며 문서의 예시 자체가 ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]입니다. /memory show는 결합된 컨텍스트를 출력하고 /memory reload는 파일을 다시 스캔합니다.

Windsurf: 문자 수 제한이 있는 규칙

Windsurf의 규칙 문서는 이제 Devin Desktop 아래에 있으며, .devin/rules/*.md를 권장하고 .windsurf/rules/*.md는 대체 경로로 유지합니다. 레거시 단일 파일 .windsurfrules도 여전히 읽힙니다. 각 규칙 파일은 always_on, glob, model_decision, manual 중 하나의 trigger를 가집니다. 전역 규칙 파일은 6,000자, 워크스페이스 규칙 파일은 각 12,000자로 제한되는데, 이는 여기서 다루는 도구 중 가장 엄격하게 문서화된 제한입니다. AGENTS.md는 모든 디렉터리에서 지원됩니다. 루트 파일은 항상 켜지고 하위 디렉터리 파일은 해당 디렉터리에 자동으로 glob 범위 지정됩니다. Git 저장소에서는 탐색이 Git 루트까지 올라가며, 엔터프라이즈 IT는 읽기 전용 시스템 규칙을 배포할 수 있습니다.

단일 소스 전략: AGENTS.md와 얇은 어댑터

AGENTS.md가 단일 진실 공급원인 이유

AGENTS.md 사양은 필수 필드가 없는 일반 Markdown이며, Linux Foundation 산하 Agentic AI Foundation이 관리하고, 지원 목록에 Codex, Cursor, Gemini CLI, Windsurf, GitHub Copilot의 코딩 에이전트, VS Code, Zed, JetBrains Junie, Devin, Aider, Factory 등이 올라 있으며, 6만 개 이상의 오픈소스 프로젝트가 사용합니다. 비교표의 모든 도구가 기본적으로 읽거나 읽도록 설정할 수 있는 유일한 파일입니다. 다른 어떤 파일도 근접하지 못합니다. CLAUDE.md는 Claude Code와, 루트에서만, 일부 Copilot 표면이 읽습니다. GEMINI.md는 Gemini CLI와 같은 Copilot 표면이 읽습니다. .cursor/rules는 Cursor만 읽습니다.

따라서 공유 규약은 AGENTS.md에 들어가고, 다른 모든 파일은 어댑터가 됩니다. 도구 전용 지침을 담고 공유 파일을 끌어오는 얇은 스텁이거나, CI가 동기화 상태로 유지하는 생성된 복사본입니다.

Claude Code: 복제하지 말고 가져오기

여기서의 함정은 기본 동작입니다. Anthropic 문서는 작업 디렉터리나 그 상위 어느 디렉터리에도 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없을 때만 Claude가 AGENTS.md를 읽는다고 명시합니다. 누군가 Claude 전용 메모를 위해 CLAUDE.md를 추가해서 두 파일이 모두 있는 저장소는 Claude Code에서 AGENTS.md 로드가 조용히 중단됩니다. 문서화된 해결책은 @AGENTS.md를 CLAUDE.md의 첫 줄로 두는 것입니다. Claude는 가져온 파일을 먼저 읽고 그 아래의 Claude 전용 내용을 읽으며, 문서는 이 가져오기가 절대 이중 읽기를 일으키지 않는다고 확인합니다.

심볼릭 링크(ln -s AGENTS.md CLAUDE.md)도 작동하지만, Anthropic은 누군가 Windows에서 클론할 때는 이를 피하라고 경고합니다. Windows에서 심볼릭 링크를 만들려면 관리자 권한이나 개발자 모드가 필요하고, core.symlinks가 활성화되어 있지 않으면 Git이 커밋된 심볼릭 링크를 한 줄짜리 텍스트 파일로 체크아웃하기 때문입니다. 제 고객 대부분은 Windows 개발자가 적어도 한 명은 있으므로 저는 가져오기를 사용합니다. claude-md-and-agents-md 값을 가진 Project instructions 설정도 있지만, 사용자 설정, --settings, 관리형 설정에서만 적용되고 프로젝트와 로컬 설정에서는 무시되므로 저장소에 커밋할 수 없습니다. 가져오기가 이식 가능한 답입니다.

GitHub Copilot: 가리키지 말고 생성하기

AGENTS.md를 읽는 Copilot 표면에서는 할 일이 끝났습니다. GitHub.com, Visual Studio, JetBrains의 Copilot Chat에서는 로드되는 저장소 파일이 .github/copilot-instructions.md 하나뿐입니다. 그 파일에 “AGENTS.md를 읽으십시오"라고 쓰는 것은 모델이 파일을 열기로 결정하는 데 의존하는데, 이는 Anthropic이 AGENTS.md를 읽으라고 말로 지시하는 CLAUDE.md에 대해 지적하는 것과 같은 약점입니다. 신뢰할 수 있는 패턴은 CI에서 AGENTS.md로부터 .github/copilot-instructions.md를 생성하고, 생성된 파일임을 알리는 헤더를 넣고, 둘이 어긋나면 파이프라인을 실패시키는 검사를 두는 것입니다. **/*.sql에만 적용되는 규칙과 같은 경로별 Copilot 동작은 공유 파일에 대응물이 없는 .github/instructions/*.instructions.md에 들어갑니다.

Cursor, Gemini CLI, Codex, Windsurf

Cursor는 루트와 중첩된 AGENTS.md를 기본적으로 읽으므로, .cursor/rules는 Cursor 전용 glob 범위 동작과 관리자가 Team Rules로 강제하는 내용으로 줄어듭니다. Gemini CLI는 커밋된 설정 한 줄, 즉 .gemini/settings.json에서 context.fileName을 ["AGENTS.md", "GEMINI.md"]로 두는 것만 필요하며, 그 뒤 GEMINI.md는 Gemini 전용 지침만 담습니다. Codex와 Windsurf는 설정 없이 공유 파일을 읽습니다. Codex의 경우 체인을 32 KiB 미만으로 유지하고 AGENTS.override.md는 임시 로컬 재정의에만 사용하십시오. Codex를 GitHub 코드 리뷰에 사용한다면, 검토 대상 코드에 가장 가까운 AGENTS.md에 ## Code Review Rules 섹션을 추가하십시오. 이것이 OpenAI가 문서화한 메커니즘입니다.

공유할 수 없는 것

지침 파일은 모델을 위한 산문입니다. 모델에 제안되는 것이 아니라 도구가 강제하는 모든 것은 해당 도구의 자체 설정에 남으며, 도구마다 다릅니다.

Anthropic의 메모리 페이지는 분명하게 말합니다. Claude는 CLAUDE.md를 강제 설정이 아닌 컨텍스트로 취급하며, 모델의 결정과 무관하게 동작을 차단하려면 PreToolUse 훅이나 permissions.deny 규칙을 사용해야 합니다. 이 가이드의 모든 파일에 같은 원칙이 적용됩니다. 모든 에이전트가 알 수 있도록 AGENTS.md에 규칙을 쓰고, 중요한 규칙은 도구 설정과 CI에서 강제하십시오.

모노레포 우선순위: 루트 파일과 패키지 수준 파일

표의 모든 도구는 루트 파일과 중첩 파일을 지원하며, 모든 도구가 이를 약간씩 다르게 병합합니다. 공유 AGENTS.md 전략이 버티는지 무너지는지가 여기서 갈립니다.

이 표에서 두 가지 규칙이 도출됩니다. 첫째, 모든 중첩 AGENTS.md는 루트가 컨텍스트에 함께 있든 없든 올바르도록 작성하십시오. Copilot 문서는 병합을 약속하지 않고, Codex는 잘라낼 수 있으며, Claude Code는 에이전트가 실제로 그 디렉터리를 건드릴 때만 중첩 파일을 로드합니다. 놓치면 치명적인 한두 가지 경계는 반복해서 적고, 루트와 절대 충돌하지 마십시오. 지침이 충돌할 때 모델이 “임의로 하나를 고를 수 있다"는 Anthropic의 조언은 모든 에이전트에 적용됩니다. 둘째, 루트를 짧게 유지하십시오. Anthropic의 200줄 목표와 Codex의 32 KiB 상한이 설계를 묶는 두 숫자이며, 대략 10 KB 미만으로 유지되는 루트 파일은 Codex가 파일을 버리기 시작하기 전에 패키지 파일 두세 개를 넣을 여지를 남깁니다.

패키지가 수십 개인 팀을 위해 Claude Code의 대규모 코드베이스 지침은 루트 하나와 패키지당 파일 하나로 나누는 두 수준 분할을 권장하며, 각 파일은 해당 패키지 소유자가 유지하고, 작업하지 않는 패키지에는 claudeMdExcludes를 사용합니다. 이 소유권 모델은 다른 모든 도구의 중첩 AGENTS.md 파일에 그대로 대응됩니다.

공유 파일에 들어갈 것과 도구별 파일에 들어갈 것

제가 모든 줄에 적용하는 테스트는 이것입니다. 개발자가 내일 도구를 바꾼다면 이 지침이 여전히 참인가? 그렇다면 AGENTS.md에 속합니다. 한 제품 안에서만 의미가 있다면 그 제품의 파일에 속합니다.

거버넌스: 소유권, 리뷰, 버전 관리, 비밀 정보, 테스트

소유권. AGENTS.md, 어댑터 파일, 동기화 스크립트를 CODEOWNERS에 추가하고, 루트는 플랫폼 또는 개발자 경험 팀이, 중첩 파일은 각 패키지 팀이 소유하도록 하십시오. Anthropic의 모노레포 지침도 디렉터리별 CLAUDE.md 파일에 같은 권고를 합니다. 각 디렉터리의 소유자가 자기 파일을 유지합니다.

리뷰. 지침 파일의 모든 변경은 코드처럼 풀 리퀘스트를 거칩니다. Claude Code는 여기서 도우미를 제공합니다. /doctor prompt-audit(v2.1.283 이상)는 CLAUDE.md, CLAUDE.local.md, AGENTS.md 파일과 규칙 및 스킬을 검사해 존재하지 않는 파일이나 명령에 대한 참조, 구형 모델용으로 작성된 지침, 서로 모순되는 파일을 찾아내고, 승인하기 전까지 아무것도 바꾸지 않은 채 편집을 제안합니다. 변경을 유발한 도구가 Claude Code가 아니더라도 공유 파일 변경을 병합하기 전에 실행하십시오.

버전 관리. 파일은 Git에 있으므로 버전 관리됩니다. 팀이 잊는 것은 생성된 복사본을 의도적으로 버전 관리하는 일입니다. .github/copilot-instructions.md를 커밋하고 오래되면 CI가 실패하게 하십시오. 아무도 diff를 보지 못하는 빌드 시점에 조용히 재생성하지 마십시오.

비밀 정보. 절대 안 됩니다. 이 파일들은 모든 개발자 머신의 모든 도구가 모델 컨텍스트에 주입하고, 그 도구가 호출하는 벤더로 전송하며, 생성기가 복사합니다. AGENTS.md의 연결 문자열은 다섯 벤더의 요청 로그에 있는 연결 문자열입니다. 개인 파일인 CLAUDE.local.md와 ~/.codex/AGENTS.override.md는 gitignore 처리되지만 여전히 컨텍스트에 들어가므로 비밀 정보를 둘 곳이 아닙니다. 에이전트를 환경 변수나 비밀 관리자로 안내하고, 규칙을 강제로 뒷받침하십시오. Read(./.env) 같은 Claude Code permissions.deny 규칙은 모델의 의도와 무관하게 읽기를 차단합니다.

지침 테스트. 공유 파일 변경을 빌드 스크립트 변경처럼 다루고 각 도구에서 스모크 테스트하십시오. 먼저 로드를 확인합니다. Claude Code의 /context는 Memory files 아래에 파일을 나열하고, Gemini CLI의 /memory show는 결합된 컨텍스트를 출력하며, GitHub.com의 Copilot Chat은 파일을 사용했을 때 References에 .github/copilot-instructions.md를 표시하고, OpenAI는 감사할 수 있는 로그를 쓰도록 codex -c log_dir=./.codex-log를 제안합니다. 그다음 고정된 프롬프트 세트(“테스트는 어떤 명령으로 실행합니까?”, “데이터베이스 쿼리는 어디에 속합니까?")를 실행하고 도구 간 답을 비교하십시오. 불일치는 개발자가 발견하기 전에 잡아낸 드리프트입니다.

템플릿

복사해 쓸 수 있는 짧고 현실적인 세트입니다. 저장소는 가상의 결제 플랫폼이며, 세부 사항은 교체하십시오.

AGENTS.md (단일 진실 공급원)

# AGENTS.md: Payments Platform

## Project
Node 22 / TypeScript 5.6 monorepo using pnpm workspaces.
Services live under `services/`, shared libraries under `packages/`.

## Commands
- Install: `pnpm install --frozen-lockfile`
- Build: `pnpm -r build`
- Test: `pnpm -r test` (run before every commit)
- Lint and format check: `pnpm lint && pnpm format:check`

## Conventions
- TypeScript strict mode. No `any` without a comment explaining why.
- Database access goes through `packages/db`. No raw SQL in route handlers.
- Commit subjects: `<package>: <imperative summary>`, for example `api: add idempotency keys`.

## Boundaries
- Never edit files under `**/generated/`. Run `pnpm codegen` instead.
- Never modify a migration that has merged. Add a new one.
- Never commit secrets or `.env*` files. Configuration comes from the environment.
- Changes under `services/payments/` require a human reviewer from the payments team.

## Pull requests
- Title format: `[<package>] <summary>`. Run lint and tests before opening the PR.

## Code Review Rules
- Flag any new dependency without a justification in the PR description.
- Flag raw SQL strings outside `packages/db`.

CLAUDE.md (얇은 어댑터)

@AGENTS.md

## Claude Code

- Use plan mode for any change under `services/payments/`.
- Permissions, hooks and MCP servers are configured in `.claude/settings.json`. Do not duplicate them here.

.cursor/rules/testing.mdc (Cursor 전용, glob 범위)

---
description: Testing conventions for the payments monorepo
globs: "**/*.test.ts"
alwaysApply: false
---

- Use Vitest. Never add Jest.
- Wrap database tests in a transaction that rolls back.
- Shared project rules live in AGENTS.md; this file holds Cursor-specific behaviour only.

.gemini/settings.json (Gemini CLI를 공유 파일로 연결)

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

scripts/sync-agent-instructions.sh (Copilot 복사본 생성)

#!/usr/bin/env bash
set -euo pipefail
{
  echo "<!-- GENERATED from AGENTS.md. Edit AGENTS.md and run scripts/sync-agent-instructions.sh. -->"
  cat AGENTS.md
} > .github/copilot-instructions.md
# In CI, fail when the committed copy is out of date:
git diff --exit-code -- .github/copilot-instructions.md

팀을 위한 롤아웃 계획

1. 1주차: 인벤토리. 모든 저장소의 모든 지침 파일을 나열하십시오. 예를 들어 git ls-files | grep -Ei 'claude\.md|agents\.md|cursorrules|cursor/rules|copilot-instructions|instructions\.md|gemini\.md|windsurf'를 사용합니다. 각 파일을 누가 썼고 마지막으로 언제 바뀌었는지 기록하십시오. 활발히 개발 중인 저장소 하나를 파일럿으로 고르십시오.
2. 2주차: 통합. “어느 도구에서도 참인가?” 테스트를 적용해 파일럿의 파일들을 하나의 AGENTS.md로 병합하십시오. Claude Code의 /init은 기존 Cursor와 Copilot 파일을 읽고, CLAUDE_CODE_NEW_INIT=1을 설정하면 AGENTS.md, Windsurf, Cline 파일까지 읽어 통합 초안을 제안합니다. 결과물이 아닌 출발점으로 사용하십시오. 얇은 CLAUDE.md, Gemini 설정, Copilot 동기화 스크립트를 작성하십시오. .cursorrules와 중복된 산문을 삭제하십시오.
3. 3주차: 파일럿. 팀이 보유한 모든 도구를 합쳐서 사용하는 개발자 3~5명을 선정하십시오. 각자 로드 확인과 고정 프롬프트 세트를 실행한 뒤 일주일 동안 평소처럼 작업하며 에이전트가 무시했거나 틀리게 처리한 지침을 모두 기록합니다. 개발자가 아니라 파일을 고치십시오.
4. 4주차: 제도화. CODEOWNERS 항목, CI 동기화 검사, 저장소 템플릿을 추가하십시오. 무엇을 조직 계층으로 옮길지 결정하십시오. Claude Code의 관리형 CLAUDE.md와 관리형 설정, Cursor Team Rules, Copilot 조직 지침, Windsurf 시스템 규칙이 모든 저장소에 적용되어야 하는 규칙이 속하는 곳입니다. 그다음 이 패턴을 다음 저장소들로, 저장소마다 풀 리퀘스트 하나씩 확장하십시오.

해야 할 일

1. 모든 저장소의 모든 지침 파일을 인벤토리하고 각 파일의 소유자를 지정하십시오.
2. 명령, 레이아웃, 규약, 경계, 보안 규칙, PR 규약을 담은 루트 AGENTS.md를 만들고 200줄 미만으로 유지하십시오.
3. CLAUDE.md가 있다면 첫 줄을 @AGENTS.md로 만들고 Claude 전용이 아닌 모든 내용을 밖으로 옮기십시오.
4. 누군가 Gemini CLI를 사용한다면 커밋된 .gemini/settings.json에서 context.fileName에 AGENTS.md를 포함하도록 설정하십시오.
5. AGENTS.md에서 .github/copilot-instructions.md를 생성하고 오래되면 실패하는 CI 검사를 추가하십시오.
6. .cursorrules를 삭제하고, glob 범위의 Cursor 전용 동작에는 .cursor/rules/*.mdc를 유지하십시오.
7. 패키지별 중첩 AGENTS.md 파일을 추가하되, 자체 완결적이고 루트와 충돌하지 않으며 핵심 경계를 반복하도록 하십시오.
8. 권한, 훅, MCP 등록을 각 도구의 설정으로 옮기고 중요한 규칙은 deny 규칙과 CI로 강제하십시오.
9. 모든 지침 파일에서 비밀 정보를 검색해 제거하고 .env 읽기에 대한 deny 규칙을 추가하십시오.
10. 파일을 CODEOWNERS에 추가하고, 변경을 병합하기 전에 /doctor prompt-audit를 실행하고, 변경마다 각 도구를 스모크 테스트하십시오.

자주 묻는 질문

AGENTS.md와 CLAUDE.md의 차이는 무엇입니까? AGENTS.md는 Linux Foundation 산하 Agentic AI Foundation이 관리하는 벤더 중립적 파일로, Codex, Cursor, Copilot의 에이전트, Gemini CLI, Windsurf가 읽습니다. CLAUDE.md는 Claude Code 전용 파일로, 공유 형식에 없는 @path 가져오기, 관리형 정책 계층, CLAUDE.local.md, 경로 범위 규칙을 제공합니다. 공유 규약은 AGENTS.md에 들어가고, 짧은 CLAUDE.md가 이를 가져와 Claude 전용 지침을 덧붙입니다.

Claude Code는 AGENTS.md를 읽습니까? 예, v2.1.277부터 읽지만, 작업 디렉터리나 그 상위에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없을 때만 읽습니다. 두 파일이 모두 있으면 Project instructions 설정이 claude-md-and-agents-md로 되어 있지 않은 한 CLAUDE.md만 읽습니다. 이식 가능한 해결책은 CLAUDE.md 첫 줄의 @AGENTS.md 가져오기입니다.

.cursorrules와 .cursor/rules 중 무엇을 써야 합니까? .cursor/rules/*.mdc 또는 일반 AGENTS.md를 사용하십시오. Cursor의 현재 문서는 .mdc 프로젝트 규칙, Team Rules, 루트와 하위 디렉터리의 AGENTS.md를 다루며, .cursorrules는 더 이상 문서화하지 않습니다.

GitHub Copilot은 AGENTS.md를 읽습니까? Copilot 클라우드 에이전트, GitHub.com의 코드 리뷰, VS Code의 Copilot Chat, Copilot CLI는 읽습니다. GitHub.com, Visual Studio, JetBrains IDE의 Copilot Chat은 읽지 않고 .github/copilot-instructions.md에 의존하므로, 그 파일을 AGENTS.md에서 생성하십시오.

모노레포에서 중첩된 AGENTS.md 파일은 어떻게 동작합니까? 사양은 가장 가까운 파일이 우선하고 명시적 프롬프트가 모든 것을 재정의한다고 명시합니다. Codex는 루트에서 아래로 연결하며 가까운 파일이 더 강하고 기본 32 KiB에서 멈춥니다. Cursor는 중첩 파일을 상위와 결합하고, Windsurf는 glob으로 자동 범위 지정하며, Copilot은 가장 가까운 파일을 적용합니다. 중첩 파일은 루트와 절대 충돌하지 않도록 작성하십시오.

팀이 지침뿐 아니라 재사용 가능한 에이전트 동작도 패키징하고 있다면, gh skill GitHub CLI 가이드에서 Copilot, Claude Code, Cursor, Codex, Gemini CLI 전반에서 스킬을 설치하고 고정하는 방법을 다룹니다. 같은 단일 소스 원칙이 적용됩니다.

도움이 필요하십니까? Big Hat Group은 미국과 캐나다의 조직을 대상으로 2주간의 AI 코딩 에이전트 설정 검토부터 전체 저장소에 걸친 멀티 에이전트 롤아웃까지 애플리케이션 개발 컨설팅을 제공합니다. 디스커버리 콜을 예약해 귀사의 환경을 함께 살펴보십시오.

출처

• How Claude remembers your project (CLAUDE.md, imports, rules, AGENTS.md), Claude Code 문서
• Settings files and precedence, Claude Code 문서
• Set up Claude Code in a monorepo or large codebase, Claude Code 문서
• AGENTS.md specification, Agentic AI Foundation
• Custom instructions with AGENTS.md, OpenAI Codex 문서
• Adding repository custom instructions for GitHub Copilot, GitHub Docs
• Support for custom instructions in GitHub Copilot, GitHub Docs
• Rules, Cursor 문서
• Provide context with GEMINI.md files, Gemini CLI 문서
• Rules and memories, Devin Desktop (Windsurf) 문서