Claude Code의 가장 많은 요청 사항은 의외로 알려져 있지 않다

GitHub의 anthropics/claude-code 이슈를 반응(reactions) 수가 많은 순서대로 나열해 보세요. 맨 앞에 오는 것은 부작업자의 침묵 중단도, 6월 15일의 과금 분리도 아닙니다.

이슈 #6235, 누적 5,200개가 넘는 reactions. "AGENTS.md에 대응해 주길 바란다"라는 기능 요청입니다. 2025년 8월 21일에 제기되어 9개월 이상 지난 지금도 미대응 상태로 계속되고 있습니다. 단일 이슈로서는 과거 최대 규모이며, 2위인 717개의 7배 이상입니다.

그런데도 이 이야기를 일본어로 정리한 기사는 거의 보이지 않습니다. 본 기사에서는 이 고통의 정체와, 대응을 기다리는 동안 이용자 측에서 취할 수 있는 회피책을 실제로 운용한 것들만 작성하겠습니다.

고통의 정체 — 같은 지시를 서로 다른 장소에 나누어 쓰기

현재 AI 코딩 도구는 하나가 아닙니다. Claude Code를 주로 사용하면서 Cursor나 Codex를 병용하는 사람이 늘고 있습니다.

문제는 각각이 읽는 지시서의 위치가 다르다는 점입니다.

• Claude Code는 CLAUDE.md를 읽음
• Cursor는 .cursorrules를 읽음
• Codex는 AGENTS.md를 읽음

동일한 codebase의 규약이나 제약을 3개의 서로 다른 이름으로, 서로 다른 장소에 나누어 써야 합니다. 하나를 업데이트하면 나머지 것도 수동으로 맞춰야 합니다. 이 동기화 작업의 번거로움이 매주 조금씩 쌓여갑니다.

고통이 나타나는 방식은 사용법에 따라 세 가지로 나뉩니다.

• 개인이 여러 도구를 사용한다. 혼자서 도구를 전환할 때마다 지시서의 불일치를 확인해야 함
• 팀으로 작업한다. 각자의 선호 도구가 섞이면서 동기화의 책임이 팀 관리자에게 집중됨
• 여러 도구를 동시에 병행하여 사용한다. 혼자서 여러 창을 띄워놓고, 전환할 때마다 불일치를 확인해야 함

저 자신은 세 번째 경우입니다. 병행해서 사용하다 보면 하루에도 몇 번씩 도구 창을 오갑니다. 지시서의 불일치를 확인하는 것만으로도 대략 연간 100시간 이상이 사라지고 있었습니다.

왜 발생하는가

AGENTS.md는 코딩 에이전트(coding agent)가 codebase를 이해하기 위한 공통 Markdown 문서로서 업계에서 수렴되고 있는 표준입니다 (공식 사이트: https://agents.md/ ).

주요 도구의 대응 현황은 다음과 같습니다.

4개 이상이 대응 완료되었거나 대응 중인 반면, Claude Code만이 독자적인 경로를 유지하고 있습니다. 그렇기 때문에 Claude Code를 사용하는 사람이 다른 도구와 병행하면 지시서를 나누어 써야 하는 상황이 발생하는 것입니다.

지금 바로 가능한 회피책

공식 대응을 기다리는 동안 이용자 측에서 취할 수 있는 조치가 있습니다. 우선 공식 가이드에서 첫 번째로 권장하는 방법부터 간편한 순서대로 나열합니다.

1. CLAUDE.md에 AGENTS.md를 포함하기 (공식이 첫 번째로 권장)

공식 Claude Code 가이드에서 가장 먼저 제시하는 방법입니다. Claude Code는 AGENTS.md가 아니라 CLAUDE.md를 읽지만, CLAUDE.md를 "AGENTS.md를 한 줄로 가져오기만 하는" 내용으로 만들면 실체 파일을 늘리지 않고 해결할 수 있습니다.

@AGENTS.md
## Claude Code 고유의 추가 사항
(Claude Code에만 적용하고 싶은 지시가 있다면 이 아래에 추가)

세션 시작 시 AGENTS.md를 읽어 들인 뒤, 그 아래에 작성한 추가 사항을 뒤에 붙입니다. 실체 파일은 AGENTS.md 하나뿐이므로 불일치가 발생하지 않습니다. 심볼릭 링크(symbolic link)와 달리 특별한 권한이 필요하지 않으며, 공식에서도 Windows에서는 이 방식을 권장하고 있습니다 (Windows의 심볼릭 링크는 관리자 권한이나 개발자 모드가 필요함). 이미 AGENTS.md가 있는 리포지토리에서 /init을 실행하면, 그 내용을 읽어 CLAUDE.md에 포함시켜 줍니다.

2. 심볼릭 링크로 참조를 공통화하기

실체를 하나의 파일로 만들고, 두 개의 이름으로 참조합니다.

ln -s CLAUDE.md AGENTS.md

처음에 약 2분만 투자하면 그것으로 끝납니다. 유지 관리의 수고는 거의 제로입니다. 다만 Windows와 일부 WSL에서는 관리자 권한이나 개발자 모드가 필요하며, clone 경로에 따라 링크가 실체의 복사본으로 변할 수 있으므로, 제대로 링크로서 해결되고 있는지 확인해야 합니다. Claude Code 고유의 추가 기입이 필요 없고 OS 제약이 없다면 간편합니다.

3. 커밋 전에 동기화하기 (pre-commit hook)

git의 hook을 사용하여, 커밋할 때마다 자동으로 맞춥니다. 두 파일을 서로 다른 실체의 파일로 유지하고 싶을 때 적합합니다. 팀 내에서 심볼릭 링크(Symbolic Link)를 공지하기 어려울 때도 사용할 수 있습니다.

4. SessionStart hook으로 정합성을 확인하기

세션이 시작될 때마다, CLAUDE.md와 AGENTS.md가 어긋나 있지 않은지 확인합니다. 제가 배포하고 있는 무료 hook 모음(후술)에 이 용도의 agents-md-sync-checker가 포함되어 있습니다. 크기 차이가 클 때 경고를 보내고, 심볼릭 링크 사용을 제안합니다.

5. direnv로 환경 변수를 정비하기

디렉토리에 진입했을 때 환경 변수를 정비하는 direnv를 사용하는 방법입니다. 프로젝트마다 지시서(Instruction)의 취급을 다르게 하고 싶을 때 적합합니다.

6. CI에서 차이를 검출하여 경고하기

CI에서 지시서가 어긋나 있지 않은지 검사하여 경고합니다. 팀 단위 운영을 보완하는 마지막 방파제입니다.

무엇을 선택할 것인가

• 이제 시작한다면, 우선 공식이 권장하는 1(통합). 실체가 하나라 불일치가 발생하지 않으며, Windows에서도 권한이 필요하지 않습니다. - Claude Code 고유의 추가 기입이 필요 없고 OS 제약이 없다면 **2(심볼릭 링크)**도 간편합니다. - 팀에서 사용한다면 → 3(pre-commit) + 6(CI) 조합으로 각자의 로컬 환경과 공유 환경 모두를 잡습니다.

저 자신은 통합 방식이 공식적으로 정리되기 전부터 2(심볼릭 링크)와 4(SessionStart hook) 조합으로 운용해 왔습니다. 처음 설정에 12분 정도 걸렸을 뿐, 그전까지 연간 100시간 이상 들였던 확인 작업이 거의 제로가 되었습니다. 지금 시작한다면 우선 1번 통합 방식이 가장 빠릅니다.

무료 hook 모음

4번에서 언급한 agents-md-sync-checker를 포함하여, Claude Code의 사고 방지를 위한 hook 모음을 MIT 라이선스로 배포하고 있습니다. 최근 14일 동안 1,580명 이상이 사용 중입니다.

더 깊이 알고 싶은 분들을 위해

본 기사는 5,200개가 넘는 reactions의 고통과 즉시 사용할 수 있는 회피책의 개요입니다.

• 3가지 하위 문제 (제공처의 고정, .agents/skills/ 생태계, 문서와 실제 기기의 동작 차이) - Anthropic 공식 대응의 추적과 6월 15일 과금 분리와의 관계
• CLAUDE.md에서 AGENTS.md로의 안전한 이행 절차 (롤백 경로 포함) - 각 회피책의 즉시 사용 가능한 템플릿 모음

이 내용들은 별도의 책으로 정리되어 있습니다.

AGENTS.md와 Claude Code의 상호 운용(Interop) 운영 가이드 (¥1,500, 서문과 제1장·제2장은 무료로 미리 읽을 수 있습니다)

여러 도구를 병용하며 지시서를 구분해서 쓰는 데 매주 시간을 허비하고 있다면, 우선 본 기사의 회피책 중 하나를 오늘 바로 시도해 보세요. 공식이 권장하는 통합 방식이라면, CLAUDE.md에 @AGENTS.md라고 한 줄 적는 것만으로 시작할 수 있습니다.

Discussion