AGENTS.md vs CLAUDE.md — 드리프트를 막는 단일 소스 전략과 심링크 동기화 실전 가이드
저도 처음엔 "어차피 비슷한 내용인데 두 파일이 있으면 어때?"라고 생각했습니다. 지금 이 글을 읽고 있다면, 지금 바로 본인 리포지터리를 확인해봐도 좋습니다. Claude Code와 Codex CLI를 함께 쓰거나, Claude Code와 Cursor를 동시에 활용하고 있다면 이 이야기가 낯설지 않을 거거든요.
Claude Code를 쓰는 팀에서 Codex CLI를 추가로 도입했을 때였습니다. 기존 CLAUDE.md를 복사해서 AGENTS.md를 만들었고, 3일 뒤 코드 리뷰에서 API 응답 필드 이름이 userId와 user_id로 제각각인 걸 발견했습니다. 명명 규칙을 한쪽 파일에만 업데이트했고, 다른 쪽은 조용히 옛날 버전으로 남아 있었던 거죠.
핵심은 단순합니다 — 규칙 파일이 두 개 이상 존재하는 순간, 드리프트는 시작됩니다. 이 글에서는 멀티 에이전트 환경은 물론, Claude Code와 Cursor처럼 서로 다른 에이전트를 함께 쓰는 개발자라면 누구에게나 해당되는 드리프트 문제가 왜 생기는지, 그리고 심링크로 두 파일을 영구적으로 동기화하는 방법을 살펴봅니다.
핵심 개념
CLAUDE.md와 AGENTS.md, 뭐가 다른가요?
두 파일 모두 AI 코딩 에이전트에게 "이 프로젝트에서 어떻게 행동해야 하는지"를 알려주는 마크다운 파일입니다. 코딩 컨벤션, 아키텍처 규칙, 금지 행동, 테스트 방법 같은 내용을 담아서 에이전트가 작업을 시작할 때 컨텍스트로 읽어가게 됩니다. 목적은 동일한데, 대상 에이전트가 다릅니다.
| 파일 | 주요 대상 도구 | 배경 |
|---|---|---|
CLAUDE.md |
Claude Code | Anthropic 정의 고유 포맷, 리포지터리 루트에서 자동 로드 |
AGENTS.md |
Codex CLI, Gemini CLI, Cursor, Copilot, Windsurf 등 | OpenAI가 2025년 8월 공개한 도구 중립 오픈 표준 |
GEMINI.md |
Gemini CLI | Google 고유 포맷 |
.cursorrules |
Cursor (구형) | Anysphere 고유 포맷 |
.github/copilot-instructions.md |
GitHub Copilot | Microsoft 고유 포맷 |
AGENTS.md는 2025년 12월 Linux Foundation 산하 Agentic AI Foundation(AAIF)에 기증되면서 업계 표준으로 자리를 잡아가고 있습니다. Anthropic·OpenAI·Block이 공동 창설한 AAIF에는 2026년 4월 기준 170개사 이상이 참여하고 있고, AGENTS.md를 채택한 오픈소스 프로젝트도 60,000개를 넘었습니다.
드리프트(Drift): 동일한 규칙을 담아야 하는 두 파일이 시간이 지나면서 내용이 달라지는 현상. 한쪽만 수정하거나, 리뷰어가 두 파일을 함께 챙기지 않으면 조용히 발생합니다.
왜 Claude Code가 AGENTS.md를 바로 읽지 않나요?
Claude Code는 현재 CLAUDE.md를 우선적으로 읽습니다. AGENTS.md는 "선택적으로 참조한다"고 공식 문서에 나와 있지만, 솔직히 말하면 어떤 조건에서 참조하는지가 명확하지 않습니다. "지금 내 Claude Code가 AGENTS.md를 읽고 있는 건지 아닌지" 확신하기 어려운 상황이에요. GitHub 이슈 #6235와 #34235에서 네이티브 AGENTS.md 지원 요청이 꾸준히 제기되고 있으니, 앞으로는 달라질 가능성이 높습니다. 하지만 지금 당장은 두 파일을 함께 관리해야 하는 현실이 있고, 그래서 단일 소스 전략이 필요합니다.
실전 적용
그렇다면 실제로 어떻게 이 문제를 겪었고, 어떻게 해결했는지 사례를 살펴보겠습니다.
API 컨트랙트 붕괴: 두 에이전트가 서로 다른 파일을 읽었을 때
한 팀이 Claude Code의 에이전트 팀 기능을 1,700줄 규모의 텔레그램 미니앱에 적용했습니다. 백엔드 에이전트 3개, 프런트엔드 에이전트 1개가 동시에 작업하는 구조였죠. CLAUDE.md에는 명명 규칙이 camelCase로 명시되어 있었는데, AGENTS.md는 별도로 유지되면서 구형 규칙을 그대로 담고 있었습니다.
결과는 처참했습니다. 백엔드와 프런트엔드 에이전트가 서로 다른 파일을 참조하면서 API 필드명이 userId와 user_id로 혼재하기 시작했습니다. 더 교묘한 문제는 컨텍스트 컴팩션(context compaction) 이후에 발생했습니다. 긴 작업 중에 에이전트의 컨텍스트가 압축되면서 규칙 파일에 명시됐던 세부 지침이 사라지고, 에이전트가 즉흥적으로 판단하기 시작한 겁니다.
컨텍스트 컴팩션(Context Compaction): 에이전트가 작업이 길어질수록 초기 컨텍스트를 압축해서 처리하는 과정. 이 과정에서 규칙 파일의 세부 지침이 휘발될 수 있습니다.
이 사례에서 얻을 수 있는 교훈은 두 가지입니다. 첫째, 규칙은 한 곳에 있어야 합니다. 둘째, "should use camelCase" 같은 표현보다 "must use camelCase — never use snake_case"처럼 명확한 강도로 작성해야 컴팩션 이후에도 살아남습니다.
가장 빠른 해법: 심링크로 단일 소스 만들기
가장 실용적이고 즉시 적용 가능한 방법입니다. AGENTS.md를 정식 소스로 두고, 나머지 파일들은 이를 가리키는 심링크로 전환하는 패턴입니다.
# 1. 기존 CLAUDE.md를 AGENTS.md로 이동 (AGENTS.md가 정식 소스)
mv CLAUDE.md AGENTS.md
# 2. CLAUDE.md는 AGENTS.md의 심링크로
# -s: 심볼릭 링크(symlink) 생성 (하드링크가 아님)
ln -s AGENTS.md CLAUDE.md
# 3. GitHub Copilot 지시 파일도 동일하게
# -f: 기존 파일이 있으면 강제 덮어쓰기, -n: 대상 심링크 자체를 처리
mkdir -p .github
ln -sfn ../AGENTS.md .github/copilot-instructions.md
# 4. Cursor 규칙도 동일하게
# 주의: .mdc는 Cursor 전용 포맷이라 심링크 동작이 완전하지 않을 수 있습니다
# 실제 Cursor에서 규칙이 적용되는지 직접 확인해보는 것을 권장합니다
mkdir -p .cursor/rules
ln -sfn ../../AGENTS.md .cursor/rules/main.mdc
# 5. 심링크가 잘 연결됐는지 확인
ls -la CLAUDE.md
# CLAUDE.md -> AGENTS.md ✓Git은 심링크를 네이티브로 추적하기 때문에, 팀원이 clone이나 pull을 하면 동일한 심링크 구조를 그대로 가져갑니다. AGENTS.md 하나만 수정하면 Claude Code, Copilot, Cursor 모두에 자동으로 반영됩니다.
| 파일 | 역할 |
|---|---|
AGENTS.md |
진짜 규칙이 담긴 단일 소스 |
CLAUDE.md |
AGENTS.md 심링크 |
.github/copilot-instructions.md |
AGENTS.md 심링크 |
.cursor/rules/main.mdc |
AGENTS.md 심링크 (Cursor 동작 검증 권장) |
Windows 환경이라면: Windows에서는 심링크 생성에 관리자 권한이 필요하거나 지원이 제한적입니다. 이 경우 아래에서 소개할 CONTEXT.md 포인터 파일 패턴이 좋은 대안이 됩니다.
PrestaShop의 CONTEXT.md 아키텍처: 도구별 차이까지 수용하는 방법
대형 오픈소스 이커머스 프레임워크 PrestaShop은 조금 더 정교한 접근을 택했습니다. CONTEXT.md를 유일한 진실 원천으로 두고, 나머지 도구별 파일은 CONTEXT.md를 참조하는 포인터 파일로만 유지하는 구조입니다.
<!-- AGENTS.md (포인터 파일) -->
# AI Agent Context
이 프로젝트의 코딩 컨벤션, 아키텍처 규칙, 개발 가이드라인은
[CONTEXT.md](./CONTEXT.md)를 참조하시기 바랍니다.
## 빠른 참조
- 빌드: `pnpm build`
- 테스트: `pnpm test`
- 상세 규칙: [CONTEXT.md](./CONTEXT.md) 전체 내용 참고<!-- CLAUDE.md (포인터 파일) -->
# Claude Code Context
전체 프로젝트 가이드라인은 [CONTEXT.md](./CONTEXT.md)를 참고해주세요.
<!-- Claude Code 전용 추가 설정이 있다면 이곳에 -->이 방식은 도구별로 미세한 차이가 있을 때 심링크보다 유연하게 대응할 수 있다는 점이 매력적입니다. 공통 규칙은 CONTEXT.md에, 도구별 특이사항만 각 포인터 파일에 담을 수 있거든요. 저는 두 방식을 섞어서 쓰는 편인데 — 대부분의 파일은 심링크로 연결하고, Claude Code처럼 도구 고유의 동작 차이가 있을 때만 포인터 파일 패턴을 활용합니다. 다만 포인터 파일이 너무 얇으면 에이전트가 실제로 CONTEXT.md까지 따라가지 않는 경우도 있어서, 최소한의 핵심 규칙은 포인터 파일 안에도 함께 넣어두는 것을 권장합니다.
PrestaShop은 이 전략을 Core 표준으로 채택해서 전 도메인에 롤아웃했습니다.
AGENTS.md를 더 효과적으로 작성하는 방법
이 논문 수치를 보고 저도 좀 놀랐는데 — ETH Zurich 연구(2026)에서 AGENTS.md가 존재하면 SWE-bench 계열 태스크 기준으로 작업 완료까지 중간 런타임이 28.64% 단축되고, 출력 토큰 소비가 16.58% 감소했습니다. 단, 조건이 있습니다. 사람이 직접 작성한 파일만 이런 효과가 있었고, AI가 자동 생성한 AGENTS.md는 오히려 작업 성공률을 소폭 낮췄습니다.
규칙을 작성할 때 강도가 중요합니다.
# ❌ 컨텍스트 컴팩션 후 무시되기 쉬운 표현
- should use camelCase for variables
- try to avoid direct database queries in controllers
- it would be nice to add tests for new features
# ✅ 명확한 강도로 살아남는 표현
- **ALWAYS** use camelCase for variables — NEVER use snake_case
- **NEVER** write direct database queries in controllers; use the repository pattern
- **MUST** add unit tests for every new public method장단점 분석
장점
| 항목 | 내용 |
|---|---|
| DRY 원칙 | 규칙을 한 곳에서만 편집하면 모든 에이전트에 자동 반영됩니다 |
| 드리프트 방지 | 파일 간 내용 불일치로 인한 에이전트 행동 편차를 원천 차단합니다 |
| 도구 교체 유연성 | 새 에이전트 도입 시 심링크 하나만 추가하면 됩니다 |
| 성능 개선 | 런타임 28.64% 단축, 토큰 소비 16.58% 감소 효과가 있습니다 |
| 팀 협업 | Git이 심링크를 추적하므로 클론 시 모든 팀원이 동일한 구조를 가져갑니다 |
단점 및 주의사항
| 항목 | 내용 | 대응 방안 |
|---|---|---|
| Windows 심링크 제약 | 관리자 권한이 필요하거나 지원이 제한적입니다 | CONTEXT.md 포인터 파일 패턴을 대안으로 사용할 수 있습니다 |
| 포인터 파일의 함정 | CLAUDE.md가 한 줄짜리 참조만 있으면 에이전트가 실제로 읽지 않을 수 있습니다 | 심링크를 우선 사용하고, 포인터 파일에는 최소한의 핵심 규칙을 함께 포함하는 것을 권장합니다 |
| AI 생성 파일의 역효과 | LLM이 자동 생성한 AGENTS.md는 성능을 오히려 저하시킬 수 있습니다 | 사람이 직접 작성하거나 꼼꼼히 검토한 후 사용하는 것을 권장합니다 |
| 단일 파일 비대화 | 모든 도구 규칙을 한 파일에 담으면 불필요한 토큰이 증가합니다 | 공통 규칙은 AGENTS.md, 도구별 세부 사항은 얇은 래퍼 파일로 분리하는 것이 좋습니다 |
| 모호한 표현 휘발 | "should", "nice to have" 같은 표현은 컴팩션 후 무시됩니다 | "always", "never", "must"로 명확하게 표현하는 것을 권장합니다 |
| Cursor .mdc 포맷 호환성 | .mdc는 Cursor 전용 포맷으로, 심링크만으로 완전한 동작이 보장되지 않을 수 있습니다 |
실제 Cursor에서 규칙이 적용되는지 직접 확인해보는 것을 권장합니다 |
컨텍스트 토큰(Context Token): AI 모델이 한 번에 처리할 수 있는 텍스트의 단위. 규칙 파일이 비대해지면 실제 코딩 작업에 쓸 수 있는 토큰 공간이 줄어들 수 있습니다.
실무에서 가장 흔한 실수
- 복사 붙여넣기로 파일 생성 후 방치 — 처음엔 동일한 내용이지만 한쪽만 업데이트되면서 드리프트가 시작됩니다. 생성 직후에 심링크나 포인터 파일로 전환하는 것이 안전합니다.
- AI에게 AGENTS.md 작성을 맡기기 — 연구 결과에 따르면 AI가 생성한 컨텍스트 파일은 오히려 역효과를 낼 수 있습니다. 초안은 AI에게 도움받더라도 사람이 직접 검토하고 다듬는 과정이 중요합니다.
- 약한 표현으로 규칙 작성 — "가능하면 camelCase를 사용해주세요"는 컨텍스트 컴팩션 후 에이전트에게 무시되기 쉽습니다. "MUST use camelCase — NEVER use snake_case"처럼 명확한 강도로 작성하는 것을 권장합니다.
마치며
저는 이 문제로 반나절을 날렸는데, 고치는 데는 5분도 안 걸렸습니다. 멀티 에이전트 환경에서 규칙 파일은 단일 소스여야 하고, 이를 달성하는 가장 빠른 방법은 심링크입니다.
AAIF를 중심으로 AGENTS.md가 업계 표준으로 자리를 잡아가고 있는 건 맞습니다. 하지만 표준화가 진행 중인 지금 이 순간에도, 드리프트는 리포지터리 어딘가에서 조용히 일어나고 있습니다. 멀티 에이전트를 이미 쓰고 있거나, 곧 팀에 두 번째 에이전트를 도입할 예정이거나, 단독으로라도 Claude Code와 Cursor를 함께 쓰고 있다면 오늘 리포지터리를 한번 점검해보시면 좋을 것 같습니다.
지금 바로 시작해볼 수 있는 3단계:
- 현황 파악 — 리포지터리에서
CLAUDE.md,AGENTS.md,.cursorrules,.github/copilot-instructions.md가 몇 개나 있는지 확인해봅니다.ls -la CLAUDE.md AGENTS.md 2>/dev/null명령으로 빠르게 확인할 수 있습니다. - 단일 소스 지정 — 가장 내용이 풍부한 파일을
AGENTS.md로 정리하고, 나머지는ln -s AGENTS.md CLAUDE.md형태로 심링크로 전환합니다. Windows 환경이라면 CONTEXT.md 포인터 파일 패턴을 고려해볼 수 있습니다. - 규칙 표현 강화 — AGENTS.md를 열어서 "should", "try to", "nice to have" 같은 표현을 찾아 "MUST", "ALWAYS", "NEVER"로 교체해봅니다. 에이전트가 컨텍스트를 압축하는 상황에서도 살아남는 규칙이 됩니다.
다음 글: AGENTS.md의 계층적 구조 활용법 — 루트 파일과 서브디렉터리별 파일을 나눠서 모노레포 환경에서 에이전트를 더 정밀하게 제어하는 방법
참고 자료
공식 문서 & 표준
- AGENTS.md 공식 사이트 | agents.md
- Linux Foundation: Agentic AI Foundation(AAIF) 발표
- Anthropic: MCP 기증 및 AAIF 설립
- OpenAI: AAIF 공동 창설 발표
- Claude Code GitHub Issue #6235: AGENTS.md 지원 요청
- Claude Code GitHub Issue #34235: AGENTS.md 네이티브 지원 요청
연구
- arXiv: On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents
- arXiv: Agent READMEs — An Empirical Study of Context Files for Agentic Coding
- InfoQ: AGENTS.md 파일의 가치 재평가 연구 (2026.03)
실무 사례 & 가이드
- PrestaShop GitHub Issue #41152: AI-Agnostic 컨텍스트 전략
- SSW.Rules: AGENTS.md와 Claude 설정 심링크 방법
- Kaushik Gopal: AGENTS.md 단일 소스 동기화 유지 방법
- tessl.io: AGENTS.md 오픈 표준 부상 배경
- amattn.com: AGENTS.md·CLAUDE.md로 에이전트 드리프트 대응
- deployhq.com: CLAUDE.md, AGENTS.md, Copilot Instructions 통합 가이드
- SmartScope: AGENTS.md 크로스 도구 통합 관리 가이드 (2026.02)
- layer5.io: AGENTS.md — One File to Guide Them All
- builder.io: AGENTS.md로 AI 코드 품질 높이기
