AGENTS.md와 CLAUDE.md를 심볼릭 링크(symlink)로 통합했더니 Windows 팀원만 지시 사항이 사라졌다——Git for

AGENTS.md와 CLAUDE.md를 하나로 합치고 싶다는 수요는 매우 큽니다. GitHub의 Claude Code에 대한 가장 큰 요청 중 하나(#6235, 5,200개 이상의 reactions)도 바로 여기에 있습니다.

간편하고 대중적인 방법은 심볼릭 링크 (symlink)입니다. CLAUDE.md를 AGENTS.md에 대한 심볼릭 링크로 만들면, 하나의 파일을 두 도구 모두가 읽게 됩니다. 많은 해설서가 이 방법을 권장합니다.

하지만 팀에 Windows 사용자가 있다면, 그 사람만 지시 사항이 조용히 사라집니다. 에러는 단 하나도 발생하지 않습니다. 알아차리는 시점은 AI가 "지키겠습니다"라고 작성한 규칙을 어기기 시작할 때부터입니다.

원래 리포지토리(repository)에서 CLAUDE.md는 심볼릭 링크 (symlink)입니다. git ls-files --stage를 실행하면 mode가 120000으로 나옵니다.

$ git ls-files --stage
100644 c0a9443... 0 AGENTS.md
120000 47dc3e3... 0 CLAUDE.md

이를 Windows의 기본 설정(core.symlinks=false)으로 클론 (clone)해 보겠습니다.

$ git -c core.symlinks=false clone <repo> cloned

그러면 클론 (clone)한 쪽의 CLAUDE.md는 심볼릭 링크 (symlink)가 되지 않습니다. 내용을 확인해 보면 다음과 같습니다.

$ cat cloned/CLAUDE.md
AGENTS.md
$ wc -c cloned/CLAUDE.md
...

CLAUDE.md의 내용이 AGENTS.md라는 9바이트 문자열뿐입니다. 본래의 지시 사항(# 프로젝트의 지시로 시작하는 전체 내용)은 단 한 글자도 들어있지 않습니다.

Claude Code는 이 9바이트 파일을 지시서로 읽습니다. 즉, 지시 사항이 통째로 사라진 상태로 동작합니다. 그럼에도 CLAUDE.md 파일은 존재하기 때문에 읽기에는 성공하며, 경고도 발생하지 않습니다.

Git은 심볼릭 링크 (symlink)를 "링크 대상의 경로를 내용으로 하는 파일"로 저장합니다. 체크아웃 (checkout) 시에 실제 심볼릭 링크 (symlink)를 다시 만들지 여부는 core.symlinks 설정에 따라 결정됩니다.

Git for Windows의 기본값은 관리자 권한이나 개발자 모드가 없으면 심볼릭 링크 (symlink)를 생성할 수 없기 때문에 core.symlinks가 false로 설정됩니다. 이 경우 Git은 링크 대상의 경로만 적힌 일반 텍스트 파일로 체크아웃 (checkout)합니다. CLAUDE.md의 내용이 AGENTS.md가 되는 이유는 바로 이것 때문입니다.

동일한 리포지토리를 core.symlinks=true로 클론 (clone)한 쪽은 정상적으로 심볼릭 링크 (symlink)가 되며 내용도 올바르게 읽을 수 있습니다. 차이점은 이 설정 하나뿐입니다.

클론 (clone)한 후, CLAUDE.md의 내용과 크기를 확인하기만 하면 됩니다.

file CLAUDE.md # "ASCII text"라면 텍스트화된 것입니다
cat CLAUDE.md # 내용이 "AGENTS.md"뿐이라면 깨진 것입니다
wc -c CLAUDE.md # 몇 바이트밖에 없다면 깨진 것입니다

정상적이라면 CLAUDE.md의 내용은 본래 지시 사항의 전체 내용입니다. 팀에서 심볼릭 링크 (symlink)를 사용하고 있다면, Windows 팀원에게 이 세 줄을 실행해 보라고 요청하는 것이 가장 빠른 원인 파악 방법입니다.

공식적으로 권장하는 방법은 심볼릭 링크 (symlink)가 아니라 포함 (import) 방식입니다. CLAUDE.md의 서두에 한 줄,

@AGENTS.md

이라고 적기만 하면 됩니다. CLAUDE.md는 실체가 있는 파일이므로 Windows에서도 텍스트화되지 않습니다. Claude Code는 이 CLAUDE.md를 읽고, @AGENTS.md 행에서 AGENTS.md의 내용을 가져옵니다. Claude Code 고유의 지시 사항은 그 아래에 추가할 수 있습니다.

어떻게든 심볼릭 링크 (symlink)를 계속 유지하고 싶다면, 팀원 전원이 git config core.symlinks true를 설정해야 하며, Windows 팀원은 OS의 개발자 모드를 활성화해야 합니다. 단 한 명이라도 빠지면 그 사람만 조용히 망가집니다. 그렇기 때문에 공식은 Windows에서는 포함 (import) 방식을 권장하고 있습니다.

symlink의 이러한 함정은 공존을 위한 5가지 방법 중 하나입니다. pre-commit hook (pre-commit hook)으로 동기화하는 방법은 git clone 시 복제되지 않으므로 각 사용자에게 별도로 배포해야 합니다. CI에서 동기화하는 방법은 로컬 환경에는 적용되지 않습니다. 공식적인 포함 (import) 방식은 제약이 가장 적은 반면, Claude Code 고유의 추가 내용을 작성하는 위치를 잘못 지정하면 공유 측으로 유출될 수 있습니다.

어떤 방법이 자신의 사용 방식(개인별 사용 / 팀 / 병행)에 맞는지, 그리고 어떤 환경에서 조용히 망가지는지. 그 목록과 CLAUDE.md에서 AGENTS.md로의 롤백(rollback)을 포함한 이행 절차를 별도의 책으로 정리했습니다.

• 5가지 방법 각각이 어떤 유형과 어떤 환경에서 망가지는지에 대한 목록
• Anthropic의 공식 대응 추적 및 6월 15일 과금 분리(billing separation)와의 관계
• 각 회피책에 대한 즉시 사용 가능한 템플릿 모음

AGENTS.md와 Claude Code의 상호 운용성 (interop) 운영 가이드 (¥1,500, 서론 및 제1장·제2장은 무료로 미리 읽기가 가능합니다)

파괴적인 명령어나 인증 정보의 유출을 예방하는 hook은 cc-safe-setup (MIT, 무료)을 통해 약 800건을 공개하고 있습니다.