AGENTS.md와 CLAUDE.md 동기화 유지하기: 5가지 사용자 측 해결책 (및 각 방법의 한계점)

만약 당신이 두 개 이상의 AI 코딩 어시스턴트 (AI coding assistant)를 사용한다면, 아마 이런 상황을 겪어보았을 것입니다: Codex, Cursor, Amp, Aider는 모두 AGENTS.md를 읽지만, Claude Code는 CLAUDE.md만 읽습니다. 결과적으로 당신은 동일한 지침을 두 개의 파일에 각각 유지 관리해야 합니다.

AGENTS.md를 지원해달라는 요청은 Claude Code 저장소에서 가장 많은 반응을 얻은 오픈 이슈 (open issue)입니다. 5,000개 이상의 반응을 얻었으며, 이는 2위 요청보다 약 4배나 많은 수치입니다. 하지만 이 이슈는 여전히 열려 있습니다. 네이티브 지원 (native support)이 도입될 때까지, 사용자 측 옵션들을 실제로 비교해 보겠습니다. 각 방법은 서로 다른 지점에서 문제가 발생하기 때문입니다.

실제로 비용을 발생시키는 실패

초기 설정이 진짜 문제는 아닙니다. **조용한 드리프트 (Silent drift)**가 문제입니다.

AGENTS.md를 업데이트하고 CLAUDE.md를 잊어버리거나(또는 그 반대로), 당신이 의존하고 있던 지침—예를 들어 "운영 환경(production)은 건드리지 마시오"라는 가드레일(guardrail)—이 오래된 파일을 읽는 도구에는 조용히 적용되지 않게 됩니다. 두 개의 파일을 관리하는 가벼운 번거로움이 결국 사고로 이어집니다.

따라서 진짜 목표는 단순히 "파일을 동기화하는 것"이 아닙니다. 그것은 "오래된 파일이 명확하게(loudly) 실패하도록 만드는 것"입니다.

5가지 옵션과 각 방법의 한계점

1. 심볼릭 링크 (symlink) — ln -s AGENTS.md CLAUDE.md

• 개인 개발자에게 약 2분 정도 소요됩니다.
• Windows에서 작동하지 않으며 (관리자 권한 / 개발자 모드 필요), WSL → Windows 툴체인 (toolchain)에서 링크를 제대로 해석하지 못할 수 있습니다.

2. 프리 커밋 훅 (pre-commit hook) — 커밋 시 자동 복사

• 개인에게는 훌륭합니다.
• 주의할 점: git clone 시 재현되지 않습니다. 모든 팀원이 이를 설치해야 하므로, 팀 단위라면 두 번째 계층이 필요합니다.

3. SessionStart 훅 (SessionStart hook) — 세션 시작 시 구성

• 세션이 시작될 때 Claude Code가 AGENTS.md로부터 CLAUDE.md를 생성하도록 합니다.
• clone 후에도 유지되며 (저장소에 포함되므로), 심볼릭 링크가 필요 없습니다.

4. direnv — 환경 변수를 통한 교체

• 프로젝트에서 이미 direnv를 사용 중이라면 좋습니다.

5. CI 드리프트 체크 (CI drift check) — 아예 동기화하지 않음

• AGENTS.md와 CLAUDE.md가 일치하지 않을 때 단순히 CI를 실패하게 만듭니다.
• 팀에게 가장 안전합니다. "하나는 업데이트되었지만 다른 하나는 그렇지 않은" 버그를 직접 잡아내기 때문입니다. 즉, 오래된 파일이 명확하게 실패하도록 만드는 방법입니다.

당신의 환경에 맞춰 선택하세요

• 개인, 단일 머신 (Solo, one machine): 심볼릭 링크 (symlink), 그리고 CI가 있다면 CI 드리프트 체크 (CI drift check)를 병행하세요.
• 팀 (Team): 세션 시작 훅 (SessionStart hook) 또는 CI 드리프트 체크를 사용하세요. 심볼릭 링크나 프리커밋 훅 (pre-commit hook)만을 유일한 계층으로 사용하는 것은 피해야 합니다. 이들은 예상하는 방식대로 clone 시에 유지되지 않습니다.
• 여러 어시스턴트 병렬 사용 (Several assistants in parallel): 세션 시작 훅 (SessionStart hook)을 사용하여, 모든 도구가 매 세션마다 새로 구성된 파일을 읽도록 하세요.

동기화를 위해 무엇을 선택하든, 그 위에 CI 드리프트 체크 (CI drift check)를 추가하세요. 그것이 조용히 방치된 오래된 파일을 크고 명확한 실패로 전환해 주는 계층이며, 실제로 당신을 구해주는 부분입니다.

이것은 임시 방편입니다

네이티브 AGENTS.md 지원이 분명히 올바른 해결책입니다. 이 이슈에 수천 개의 반응이 달린 이유이기도 합니다. 하지만 이러한 사용자 측 옵션들은 현재 바로 작동하며, 특히 CI 드리프트 체크는 어떤 동기화 방법을 선택하든 추가할 가치가 있습니다.

저는 Claude Code를 위한 MIT 라이선스 기반의 안전 훅(safety hooks) 모음인 cc-safe-setup을 유지 관리하고 있습니다. 위에서 언급한 세션 시작 (SessionStart) 동기화 방식이 그중 하나입니다. 하나의 리포지토리에서 여러 어시스턴트를 실행 중이라면 기꺼이 의견을 나누고 싶습니다.