168표가 몰린 깃허브 이슈: 개발자들은 왜 CLAUDE.md를 버리자고 할까

프로젝트 루트 폴더를 열어봤더니 CLAUDE.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md가 나란히 놓여 있습니다. 내용은 거의 같습니다. 그런데 파일은 네 개입니다. AI 코딩 도구를 두 개 이상 쓰는 개발자라면 지금 다들 겪는 일인데요. 이 짜증이 쌓여서 결국 깃허브 이슈 하나에 168표가 몰렸습니다.

먼저 짚고 갈 게 있습니다. 이번 주제는 커뮤니티 반응 데이터가 충분히 잡히지 않았습니다. 최근 30일 기준으로 새로 올라온 스레드가 없어서, 아래 내용은 표준 자체의 구조와 그동안 쌓인 논의를 놓고 정리했습니다. 실시간 여론의 온도를 그대로 옮긴 글은 아닙니다. 미리 밝혀둡니다.

그래서 AGENTS.md가 뭔가요

간단합니다. AI 코딩 에이전트한테 “이 프로젝트는 이렇게 굴러갑니다"라고 알려주는 마크다운 파일입니다. 빌드 명령어는 뭔지, 테스트는 어떻게 돌리는지, 코드 스타일 규칙은 뭔지, 커밋 메시지 컨벤션은 어떤지를 적어둡니다. 사람이 읽는 README와 나란히 두는, 기계가 읽는 README라고 보면 됩니다.

핵심은 이름입니다. 형식이 특별한 게 아니라, 그냥 평범한 마크다운입니다. 스키마도 없고 필수 필드도 없습니다. 딱 하나 합의한 게 파일 이름 AGENTS.md입니다. 별것 없어 보이는데, 그 별것 없는 게 요점입니다.

이 이름을 중심으로 오픈AI의 Codex, 커서, 젯브레인스 계열 도구, 데빈 같은 에이전트가 하나둘 모여들었습니다. 수만 개 오픈소스 저장소에 이미 이 파일이 들어가 있고요. 사실상 업계 표준이 됐습니다.

앤트로픽은 왜 CLAUDE.md를 쓸까

Claude Code는 프로젝트 루트의 CLAUDE.md를 읽습니다. 상위 폴더의 CLAUDE.md도 타고 올라가서 읽고 홈 디렉터리의 전역 설정도 읽습니다. @경로 문법으로 다른 파일을 끌어오기도 합니다. 서브디렉터리마다 별도 CLAUDE.md를 두면 그 폴더에서 작업할 때만 로드되기도 하고요.

그러니까 CLAUDE.md는 이름만 다른 게 아닙니다. 계층 구조, 임포트, 스코프 로딩까지 얹힌 고유 기능 집합입니다. 앤트로픽 입장에서는 “우리는 AGENTS.md보다 많은 일을 한다"고 말할 근거가 있습니다.

반대편 논리도 만만치 않습니다. 그 추가 기능은 파일 이름과 아무 상관이 없다는 겁니다. AGENTS.md를 읽으면서도 계층 로딩과 임포트를 똑같이 지원하면 그만입니다. 이름을 고집할 이유가 기술적으로는 없다는 지적인데요, 이게 168표의 정체입니다.

심볼릭 링크라는 우아하지 않은 해법

현장에서는 이미 다들 우회합니다. 가장 흔한 방법이 심볼릭 링크입니다.

ln -s AGENTS.md CLAUDE.md

AGENTS.md를 원본으로 두고 CLAUDE.md를 링크로 걸어버리는 겁니다. 실제로 Claude Code 공식 문서도 이 방법을 언급합니다. 동작은 합니다. 그런데 몇 가지가 걸립니다.

윈도우에서 심볼릭 링크를 만들려면 개발자 모드를 켜거나 관리자 권한이 있어야 합니다. 깃 설정에 따라 링크가 텍스트 파일로 커밋되는 사고도 납니다. 무엇보다 팀에 새로 들어온 사람이 저장소를 클론하고 나서 “이 CLAUDE.md는 왜 화살표가 붙어 있죠?“라고 묻는 순간이 옵니다. 설명이 필요한 해법은 좋은 해법이 아닙니다.

또 다른 방법은 CLAUDE.md 안에 한 줄만 넣는 겁니다. “AGENTS.md를 읽어주세요"라고요. 이건 더 불안합니다. 모델이 그 지시를 따를지 안 따를지는 확률의 문제니까요. 설정 파일이 확률에 기대는 건 좀 이상합니다.

벤더 락인일까, 그냥 먼저 만든 것일까

여기서 논쟁이 갈립니다. 강경한 쪽은 이걸 락인 전략으로 봅니다. 파일 이름에 브랜드를 박아두면 개발자가 그 도구에 묶인다는 논리입니다. 프로젝트에 CLAUDE.md가 있으면 다른 에이전트로 갈아탈 때 마찰이 생기니까요.

온건한 쪽 해석은 다릅니다. Claude Code의 CLAUDE.md는 AGENTS.md 표준이 정리되기 전부터 있었습니다. 나중에 나온 공통 이름에 맞추려면 기존 사용자 전부의 파일을 마이그레이션해야 합니다. 그냥 시점의 문제지 음모가 아니라는 겁니다.

제 생각을 말하자면, 의도를 따지는 건 별로 생산적이지 않습니다. 중요한 건 결과입니다. 지금 개발자는 같은 내용을 두 번 관리하고, 한쪽만 고치면 두 에이전트가 서로 다른 규칙으로 코드를 짭니다. 의도가 무엇이었든 비용은 사용자가 냅니다.

그리고 둘 다 지원하는 건 제로섬이 아닙니다. AGENTS.md도 읽고 CLAUDE.md도 읽으면 됩니다. 둘 다 있으면 CLAUDE.md를 우선하거나 병합하면 되고요. 실제로 이슈에 달린 요구도 “CLAUDE.md를 없애라"가 아니라 “AGENTS.md도 읽어달라“입니다. 표를 던진 사람들은 폴백 한 줄이면 끝날 일이라고 봅니다.

이 논쟁이 진짜로 말하는 것

파일 이름 싸움처럼 보이지만 밑바닥에 깔린 질문은 따로 있습니다. AI 코딩 에이전트 생태계가 포터블해질 것이냐는 질문입니다.

지금은 도구를 바꾸면 설정도 새로 씁니다. 프롬프트 노하우도 다시 쌓습니다. 이게 굳어지면 개발자는 도구를 고르는 게 아니라 진영을 고르게 됩니다. 웹 개발이 브라우저 전쟁을 지나 표준으로 수렴했던 것처럼 AI 에이전트도 언젠가 같은 길을 갈 겁니다. 문제는 그 시점이 언제냐는 거죠.

파일 이름 하나는 사소합니다. 하지만 표준이라는 건 원래 사소한 합의에서 출발합니다. package.json이 그랬고 .gitignore가 그랬습니다. 이름이 하나로 모이니까 그 위에 도구 생태계가 쌓였습니다.

폴백 한 줄이면 될 일

168표는 큰 숫자가 아닙니다. 하지만 “설정 파일 이름 좀 통일해달라"는 요구에 몰린 표라고 보면 신호로는 충분합니다. 앤트로픽이 폴백을 넣는다면 하루짜리 작업일 테고, 넣지 않는다면 그것도 하나의 답변입니다.

지금 여러분 프로젝트 루트에는 에이전트 설정 파일이 몇 개나 있나요. 그중 몇 개가 실제로 같은 내용인가요. 한 번쯤 세어볼 만합니다. 168표는 결국 그 숫자에서 나왔습니다.