코딩 에이전트가 프로젝트를 이해하도록 돕는 설정 파일이 도구별로 제각각인 상황을 정리하자는 요구가 커지고 있다. 클로드 코드(Claude Code)의 공개 이슈 트래커에 올라온 한 기능 요청은 이 문제를 정면으로 다룬다. 요지는 간단하다. Codex, Amp, Cursor 등 여러 코딩 에이전트가 'AGENTS.md'라는 통합 마크다운 파일을 중심으로 표준화를 시작했으니, 클로드 코드도 이를 지원해 달라는 것이다. 반면 클로드 코드가 사용하는 CLAUDE.md는 특정 도구에 지나치게 종속돼 있어, 클로드 코드를 쓰지 않는 동료와 협업할 때 잘 작동하지 않는다는 지적이다.
파편화된 에이전트 설정 파일 문제
최근 코딩 에이전트가 늘어나면서 저장소 루트에 도구 전용 설정 파일을 두는 방식이 관행처럼 자리 잡았다. 이런 파일에는 대개 프로젝트 구조, 빌드·테스트 명령, 코딩 컨벤션, 주의할 점 같은 정보가 담긴다. 사람이 읽는 README와 달리, 에이전트가 코드베이스의 맥락을 빠르게 파악하도록 돕는 일종의 온보딩 문서에 가깝다. 문제는 도구마다 이 파일의 이름과 형식이 달라, 팀이 여러 에이전트를 섞어 쓰면 사실상 같은 내용을 여러 벌 관리해야 한다는 데 있다.
AGENTS.md는 이 파편화를 하나의 파일 이름으로 수렴시키려는 시도다. 별도의 전용 문법을 요구하지 않는 평범한 마크다운이라는 점이 핵심이다. 즉 특정 벤더의 포맷을 배우지 않아도 되고, 사람이 읽어도 자연스러운 문서를 그대로 에이전트에게 넘길 수 있다. 여러 도구가 같은 파일을 참조한다면, 저장소에는 단일한 진실의 원천 하나만 두면 된다는 것이 이 접근의 매력이다.
CLAUDE.md가 협업에서 걸리는 지점
이슈 작성자가 CLAUDE.md의 한계로 든 것은 기능이 아니라 이름과 소속감이다. 파일 이름 자체가 특정 도구를 전제하기 때문에, 클로드 코드를 쓰지 않는 개발자 입장에서는 자기 워크플로와 무관한 파일처럼 보인다. 오픈소스 프로젝트나 여러 도구가 공존하는 팀에서는 이런 도구 색깔이 강한 파일이 오히려 협업의 마찰을 만든다. 내용이 아무리 유용해도, 이름에서부터 '이건 저 도구 쓰는 사람용'이라는 신호를 주기 때문이다.
실무 관점에서 보면 이 요청의 본질은 '중립적인 공용 파일'에 대한 수요다. 팀은 도구 선택을 개인 자유에 맡기면서도, 프로젝트 지식은 한곳에 모아 두고 싶어 한다. AGENTS.md처럼 벤더 이름이 빠진 파일명은 그 심리적·실무적 중립성을 제공한다. 이것이 Codex, Amp, Cursor 같은 서로 경쟁하는 도구들이 같은 규약을 채택하기 시작한 배경이기도 하다.
한국 개발팀이 지금 할 수 있는 것
다만 이 이슈는 어디까지나 기능 요청 단계라는 점을 분명히 해 둘 필요가 있다. 원문은 다른 도구들의 표준화 흐름과 CLAUDE.md의 한계를 지적할 뿐, 클로드 코드가 실제로 AGENTS.md를 채택했는지, 언제 어떤 방식으로 지원할지에 대한 확정된 정보를 담고 있지 않다. 따라서 표준이 이미 자리 잡았다고 단정하기보다는, 다수의 에이전트가 같은 방향으로 움직이기 시작한 초기 신호로 받아들이는 편이 정확하다.
여러 코딩 에이전트를 병행하는 국내 팀이라면, 프로젝트 컨텍스트 문서를 도구 이름에 묶이지 않는 중립적 구조로 관리해 두는 것이 당장의 현실적 대비책이 될 수 있다. 실제 내용을 한 파일에 정리하고 도구별 설정 파일은 그것을 가리키게 하거나, 심볼릭 링크·복사로 동기화하는 식이다. 규약이 어느 쪽으로 수렴하든 핵심 지식이 흩어지지 않게 해 두면, 나중에 표준이 확정됐을 때 전환 비용을 크게 줄일 수 있다. 결국 이 논의가 던지는 질문은 '어떤 파일 이름을 쓸 것인가'가 아니라, 에이전트를 위한 프로젝트 지식을 얼마나 도구 독립적으로 관리할 것인가다.