AGENTS.md 가 포맷 논쟁을 끝냈다. Codex CLI·GitHub Copilot·Cursor·Windsurf·Amp·Devin 이 이제 같은 파일을 읽는다. Claude Code 는 여전히 CLAUDE.md 를, Gemini CLI 는 여전히 GEMINI.md 를 읽지만 그 예외 목록은 계속 짧아지고 있다.
비용이 걸린 쪽은 처음부터 포맷이 아니었다.
오늘 아침, 실제로 쓰고 있는 노트북 한 대를 스캔했다. 특별할 것 없는 환경이다. 개발자 한 명, 몇 년치 프로젝트, 흔한 에이전트 도구 구성이다.
| 파일 | 디스크상 사본 수 | 서로 다른 내용 |
|---|---|---|
AGENTS.md | 111 | 19 |
CLAUDE.md | 38 | 19 |
GEMINI.md | 2 | 2 |
SKILL.md (에이전트 스킬) | 3,073 | 887 |
측정 방법은 find ~ -maxdepth 7 -type f -name <X> 이고, node_modules·.venv*·site-packages·Library/Caches 는 제외했다. 「서로 다른 내용」은 md5 해시의 고유 개수다. 벤더가 설치한 스킬 번들도 SKILL.md 행에 포함했는데, 그게 정확히 요점이다 — 그 파일들은 이미 기기에 올라와 있고 에이전트가 읽을 수 있다.
파일 111개. 실제로 하는 말은 19가지.
중첩 파일 자체는 기능이다. 모노레포라면 패키지 단위로 지시문 범위를 나누는 것이 맞고, 스펙에도 그렇게 적혀 있다. 그러나 사본 111개에 내용이 19가지인 상태는 범위 분할이 아니다. 복사하고, 그중 하나만 고치고, 잊은 결과다.
1. 손으로 복사한다. 마음에 드는 규칙을 하나 쓴다. 다음 리포지토리에 붙여넣는다. 여섯 달 뒤 그중 하나에서 오타를 고친다. 나머지 사본은 그 순간부터 틀린 내용이고, 아무것도 그 사실을 알려주지 않는다.
2. 기기 경계. 전역 설정은 리포지토리 바깥에 있다 — ~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md, ~/.config/opencode/AGENTS.md. 노트북이 두 대면 버전도 둘이고, 그 차이는 3주쯤 지나 「내 기기에서는 다르게 동작한다」는 형태로 드러난다.
3. 생성기. 흔한 해법은 원본 파일 하나만 두고 나머지를 생성하는 것이다 — AGENTS.md → CLAUDE.md → .cursor/rules/*.mdc → .github/copilot-instructions.md. 돌린 날에는 맞는다. 다음 사람이 생성된 파일을 직접 수정하는 순간 무너진다. 디스크 어디에도 「이 파일은 생성물」이라는 표시가 없고, 그것을 검사하는 것도 없기 때문이다.
이 실패 양상은 따로 정리해 뒀다: 파일 하나에서 생성해도 어긋남은 멈추지 않았다.
경로는 사람들이 자주 틀리는 부분이라 한 표로 모아 둔다.
| 도구 | 읽는 파일 |
|---|---|
| Claude Code | CLAUDE.md (프로젝트 루트, 하위 디렉터리, ~/.claude/), .claude/skills/*/SKILL.md, .claude/agents/*.md |
| Codex CLI | AGENTS.md (루트 + 중첩, 가장 가까운 것이 우선) |
| GitHub Copilot | .github/copilot-instructions.md, 범위 지정본은 .github/instructions/*.instructions.md |
| Cursor | .cursor/rules/*.mdc (구형은 .cursorrules) |
| Windsurf | .windsurf/rules/*.md (구형은 .windsurfrules) |
| Gemini CLI | GEMINI.md (~/.gemini/, 워크스페이스 루트, 하위 디렉터리) |
| opencode | AGENTS.md, 없으면 CLAUDE.md 로 폴백, 전역은 ~/.config/opencode/AGENTS.md |
agent-drift 는 단일 파일 파이썬 스크립트다. MIT, 의존성 없음. 트리를 훑어 위 도구들이 읽는 지시문 파일을 전부 찾고, 내용 해시로 묶은 뒤 서로 어긋나는 것만 출력한다.
curl -O https://raw.githubusercontent.com/untactit/agent-drift/main/agent_drift.py
python3 agent_drift.py ~리포지토리: https://github.com/untactit/agent-drift
고쳐 주지는 않는다. 지금 얼마나 벌어져 있는지 알려줄 뿐이다. 대개 팀에 없는 것이 바로 그 숫자다 — 숫자가 없으면 프로세스를 바꾸자는 주장 자체가 성립하지 않는다.
untactit 을 만들고 있다. 에이전트가 돌아가는 스킬·지침·메모리를 한곳에 두고, 변경은 한 번만 검토하며, 그 결과가 아무도 파일을 열지 않은 채 모든 대상에 반영되게 하는 것이다.
여기서 갈리는 지점이 있다. 판단은 사람이, 전파는 무접촉이다. 무엇을 승인할지는 사람이 정하고, 그 뒤로는 손이 닿지 않는다. 파편화는 각자가 손대서 생긴다. untactit 은 손댈 필요를 없앤다 — 사후에 복구하는 것이 아니라, 사본을 고치는 사람이 없어져 애초에 생기지 않는 상태다.
아직 공개 전(pre-launch)이다. 위 스캐너는 제품 없이도 쓸모가 있고, 그건 의도한 설계다. 논지의 긴 버전은 제품 페이지에 있다.
직접 스캔을 돌려 봤다면 그 숫자를 보고 싶다. 세 명이 넘는 팀이라면 AGENTS.md 행은 내 것보다 나쁠 것으로 본다.