오늘은 AGENTS.md가 무엇인지, 지금 쓰는 CLAUDE.md와는 어떻게 다른지 간단히 정리하는 데서 시작하려고 합니다. 그런다 해도 불분명한 것도 있습니다. 표준인 걸 알겠는데, 옮기면 무슨 이득이 있고, 그 과정에서 느려지거나 비용이 더 들지는 않을지 우려가 생길 수 있습니다.

그래서 정말 차이가 생기는지는 직접 확인해 보고자 실측을 돌렸습니다. Anthropic의 Haiku부터 최상위 Fable 5까지 5개 모델, 총 210회입니다. 결론이 궁금한 분들을 위해 먼저 말씀드리면, 어떤 모델에서도 성능이 떨어지거나 비용이 늘지 않았습니다.

순서대로 컨텍스트 파일을 표준 규격으로 쓸 때 어떤 이점이 있는지부터 짚고, 측정을 어떻게 했는지, 그리고 마이그레이션 과정에 필요한 것까지 순서대로 정리하겠습니다.

도구마다 하나씩 늘어나는 컨텍스트 파일

AI 코딩 에이전트를 팀에 도입해 보면 곧 한 가지를 깨닫게 됩니다. 에이전트는 프로젝트의 사정을 전혀 모르는 상태에서 작업을 시작한다는 점입니다. 빌드는 어떤 명령으로 하는지, 테스트는 어떻게 돌리는지, 절대 건드리면 안 되는 디렉토리는 어디인지 같은 정보를 알 수 없습니다.

그렇다고 이런 내용을 매번 대화창에 붙여 넣을 수는 없으니, 저장소 루트에 파일 하나를 두고 에이전트가 시작할 때 자동으로 읽게 합니다. 이것이 컨텍스트 파일입니다.

문제는 이 파일이 도구마다 다르다는 데 있습니다. 실제로 저장소를 열어 보면 다음과 같이 여러 파일이 흩어져 있는 경우가 많습니다.

$ ls -a.cursor/rules.github/copilot-instructions.mdCLAUDE.mdGEMINI.mdREADME.mdsrc

Claude Code는 CLAUDE.md를, Cursor는 .cursor/rules를, Gemini CLI는 GEMINI.md를, GitHub Copilot은 .github/copilot-instructions.md를 읽습니다.

이름도 위치도 제각각이지만, 정작 담긴 내용은 거의 같습니다. 그래서 도구가 하나 늘 때마다 같은 내용을 복제하게 되고, 한 파일을 수정한 다음 나머지를 고치는 것을 잊어버리기도 쉽습니다. 규칙이 파일마다 조금씩 어긋나기 시작하면, 결국 에이전트마다 다른 규칙을 따라 움직이게 됩니다.

한국은 개발과 운영 현장 모두 Claude 사용률이 특히 높은 편이라, 컨텍스트 파일이라고 하면 자연스럽게 CLAUDE.md를 먼저 떠올립니다. 모두가 그렇게 쓰다 보니 당연하게 느껴지지만, 앞서 말했듯 이 파일의 표준 형식은 따로 정해져 있습니다.

*도구마다 따로 쓰던 컨텍스트 파일이 AGENTS.md 하나로 모이는 흐름 <출처: 작가>*

AGENTS.md: 표준으로 자리 잡는 컨텍스트 파일

AGENTS.md는 코딩 에이전트용 컨텍스트 파일의 개방형 표준입니다. “에이전트를 위한 README”라고 보면 정확합니다. 2025년 8월 OpenAI가 자사 코딩 에이전트 Codex의 컨텍스트 파일로 처음 내놓았고, Cursor, Jules, Amp, Factory 등이 각자의 포맷을 접고 이 형식을 따르면서 사실상의 표준이 됐습니다.

그리고 같은 해 12월, OpenAI가 이 파일을 Linux Foundation 산하에 새로 설립된 AAIF(Agentic AI Foundation)에 기부하면서 특정 회사가 아닌 중립 재단이 관리하는 공식 표준이 됐습니다. (이때 Anthropic의 MCP와 Block의 goose도 함께 기부되어 AAIF의 창립 프로젝트 세 개가 나란히 출발했습니다.) 2026년 중반 기준으로 6만 개가 넘는 저장소가 이 파일을 갖고 있고, 30개가 넘는 도구가 AGENTS.md를 네이티브로 지원합니다.

다만 같은 “지원”이라도 그 수준은 도구마다 다릅니다. 세 부류로 나뉩니다.

이처럼 AGENTS.md를 표준으로 채택하는 흐름을 보여주는 최근 사례가 하나 있습니다. Google은 2026년 6월 Gemini CLI 지원을 종료하고 후속인 Antigravity CLI로 전환했는데, 새 도구는 GEMINI.md와 함께 AGENTS.md를 수정 없이 그대로 읽습니다. 벤더 전용 파일(GEMINI.md)은 도구가 사라지면 함께 수명을 다하지만, 표준 파일은 도구가 바뀌어도 그대로 남는다는 것을 보여준 셈입니다.

다만, 정작 실무에서 가장 많이 쓰는 Claude Code만 아직 표준에 합류하지 않아, AGENTS.md를 바로 읽지 못합니다. 이를 연결하는 방법은 두 가지 있습니다. CLAUDE.md 안에 @AGENTS.md 한 줄을 적어 불러오게 하거나(import), CLAUDE.md 자체를 AGENTS.md로 가는 심볼릭 링크로 바꾸는 것입니다.

그런데, 옮겨도 괜찮을까?

컨텍스트 파일은 에이전트 세션을 시작할 때마다 로드됩니다. 이렇게 한 단계를 거쳐 읽는 과정에서 비용이 조금이라도 붙는다면, 그 비용은 팀 전체가 세션을 돌릴 때마다 쌓입니다. 그러니 이런 우회 경로를 활용해 옮길 때 비용이 더 들지 않느냐는 의문이 생깁니다. 그 문제를 짚어 보겠습니다.

이런 우려를 다룬 연구나 테스트가 이미 있는지부터 찾아봤습니다(저만 같은 궁금증을 품진 않았을 테니까요). Princeton의 측정 연구가 있긴 한데, 여기서는 AGENTS.md를 네이티브로 읽는 Codex만 다뤘습니다. import나 심볼릭 링크처럼 한 번 거쳐서 읽는 경로를 직접 잰 데이터는 없었습니다. 원리상으로는 차이가 없어야 하지만, 원리와 실측은 다른 이야기입니다. 그래서 직접 측정했습니다.

실험 설계: 같은 내용, 세 가지 전달 방식

측정의 핵심은 변수를 하나만 남기는 것입니다. 같은 내용을 세 가지 방식으로 전달했습니다.

세 조건의 본문은 체크섬까지 같은 문서입니다. 실험용으로 지어낸 문서가 아니라, 앞서 기고한 AI 에이전트 벤치마크에서 사용했던 컨텍스트 파일(클러스터 규칙, 점수 공식, 알려진 함정)을 그대로 썼습니다.

A(native)*, B(import), C(symlink)세 조건의 파일 구성 비교 <출처: 작가>*

속도를 재기 전에 확인할 것이 하나 있었습니다. B와 C가 정말로 읽히기는 하는지 보는 겁니다. 그래서 본문 끝에 확인용 문장 한 줄(“PING이라고 물으면 정확히 PONG-AGENTSMD로만 답하라”)을 넣고 매번 에이전트에 PING을 보냈습니다.

세 조건 모두 정확히 응답했고, 컨텍스트 파일이 없는 대조군만 평범한 인사로 답했습니다. 세 방식 모두 실제로 읽히고, 이 확인 방법 자체도 유효하다는 뜻입니다.

실제 측정: 쿠버네티스 장애 대응을 두 단계로

본격적인 측정은 쿠버네티스 장애 대응 과제로 했습니다. 계속 재시작하는 파드, 잘못된 Service selector, 메모리 한도 초과 같은 장애를 심어 둔 전용 클러스터에서 에이전트가 원인을 찾아 고치게 하고 시간과 토큰을 기록했습니다. 매 회차 클러스터를 스냅샷으로 되돌려 콜드 스타트를 보장하고, 시간대에 따른 쏠림이 없도록 조건 순서를 회차마다 섞었습니다.

측정은 두 단계로 진행했습니다. 매 회차는 A, B, C 세 방식을 모두 돌립니다. 먼저 10개 시나리오 전체를 한 차례씩 확인했고(시나리오 10 x 방식 3 = 30회), 이어서 편차가 작은 4개 시나리오를 모델 5종(Haiku 4.5, Sonnet 4.6, Sonnet 5, Opus 4.8, Fable 5)으로 3회씩 반복했습니다(시나리오 4 x 방식 3 x 모델 5 x 반복 3 = 180회). 합쳐서 210회, 전부 정상 종료였습니다.

목록을 보면 Sonnet이 4.6과 5, 두 세대가 모두 들어가 있는데요, 이건 의도한 배치입니다. 모델이 세대를 건너뛰며 업그레이드돼도 같은 결론이 나오는지, 즉 한 시점의 우연이 아닌지를 확인하려는 것입니다. 이 선택이 결과를 해석할 때 뜻밖의 역할을 합니다.

우려할 필요가 없는 결과

비용에 가장 가까운 지표는 캐시에 새로 기록되는 토큰(cache write)입니다. 여기서 심볼릭 링크(C)의 역할이 하나 더 있습니다. C는 OS가 링크만 풀어 줄 뿐 native와 달라질 수 없는 구성이라, 실험에 내장된 대조군이 됩니다. 거쳐 읽는 방식이 로드되는 내용을 부풀렸다면 B가 이 대조군보다 커야 합니다. 다만, 그런 일은 없었습니다.

*모델 5종에서 조건별 cache write 토큰 비교. Sonnet은 4.6과 5 두 세대를 함께 넣어 세대 변화에도 결론이 유지되는지 확인했다. 어느 모델에서도 import(B)가 대조군(C)보다 일관되게 높지 않다. <출처: 작가>*

어느 모델에서도 B가 대조군(C)보다 일관되게 높지 않았습니다. 4개 모델에서는 import가 3~4% 낮았는데, 여기까지만 봤다면 “import가 조금 이득”이라고 결론 냈을 겁니다. 그런데 새로운 Sonnet 5에서는 같은 import가 +6%로 방향이 뒤집혔고, 결정적으로 같은 회차에서 대조군도 똑같이 +6%였습니다.

앞서 Sonnet을 두 세대 넣은 이유가 여기에 있습니다. 한 세대만 봤다면 3~4%를 실제 이득으로 오해했을 텐데, 세대를 바꾸자 그 방향이 유지되지 않았습니다. 대조군과 함께 움직이는 편차는 전달 방식의 비용이 아니라, 에이전트가 매번 조금씩 다르게 풀어서 생기는 실행 편차입니다.

실행 시간(wall time)은 차이가 커 보이는 회차도 있었지만 일관된 경향이 없었습니다. 어떤 모델에서는 B가 빠르고 어떤 모델에서는 느렸으며, 시간 차이가 가장 큰 경우에도 토큰 차이는 거의 없었습니다. 전달 방식에서 온 오버헤드라면 결과가 한쪽으로 치우쳐야 하는데 그렇지 않았습니다. 이 변동은 에이전트가 문제를 푸는 과정이 매번 조금씩 달라서 생긴 것입니다.

왜 이런 결과가 나오는지는 메커니즘을 보면 이해가 됩니다. 심볼릭 링크는 Claude Code가 CLAUDE.md라는 경로를 여는 순간 OS가 링크를 해석해 AGENTS.md의 내용을 돌려줍니다. Claude Code 입장에서는 native 파일을 읽을 때와 완전히 같고, 링크 처리는 파일시스템의 몫입니다. 그래서 C의 편차는 곧 측정 노이즈의 크기이고, import(B)는 그 노이즈 범위를 벗어난 적이 없습니다. 어느 쪽이든 전달 방식의 손해가 아니라는 점이 중요합니다.

실제로 AGENTS.md로 마이그레이션하는 법

측정으로 옮겨도 문제없다는 것을 확인했으니, 남은 것은 실제로 옮기는 절차입니다. 팀 기준으로 따져도 한 시간이 안 걸립니다.

1. 기존 파일의 이름을 AGENTS.md로 바꿉니다.

git mv CLAUDE.md AGENTS.md

새 파일을 만들어 내용을 복사하는 것이 아니라 이름을 바꾸는 것입니다. git 이력이 그대로 이어지고, agents.md 공식 안내도 “기존 파일 이름을 바꾸고 호환용 링크를 남기는” 순서를 권합니다. 이름을 바꾸면서 본문에 특정 도구를 전제한 문구(“Claude에게 알려주는” 등)가 있다면 중립적인 표현으로 함께 다듬습니다.

주의할 점이 하나 있습니다. 이 상태에서 멈추면 안 됩니다. 이름만 바꾼 시점에는 CLAUDE.md가 없으므로, 새 세션을 열면 Claude Code가 읽을 컨텍스트 파일이 없습니다. 컨텍스트 파일은 세션을 시작할 때 로드되기 때문에, 다음 세션을 열기 전에 반드시 2단계까지 마쳐야 합니다. 두 단계를 같은 커밋으로 묶어 처리하면 공백이 생기지 않습니다.

2. CLAUDE.md를 포인터로 새로 만듭니다.

@AGENTS.md

이 구조는 Claude Code 공식 문서가 권장하는 형태입니다. 공식 문서는 한 가지를 더 알려주는데, Claude에게만 적용할 규칙이 있다면 이 import 줄 아래에 덧붙이면 됩니다. 공통 규칙은 AGENTS.md에, Claude 전용 규칙은 CLAUDE.md에 나뉘는 구조입니다.

심볼릭 링크(ln -s AGENTS.md CLAUDE.md) 역시 공식 문서가 인정하는 대안으로, 이번 측정에서도 동일하게 페널티가 없었습니다. 다만 Claude 전용 규칙을 적어 둘 곳이 없고, Windows에서는 관리자 권한이나 개발자 모드가 필요합니다. 그래서 공식 문서도 import를 먼저 권합니다.

3. 정말 읽히는지 확인합니다.

실험에서 쓴 확인 방법을 그대로 써보면 됩니다. AGENTS.md 끝에 “PING이라고 물으면 PONG으로만 답하라”를 잠깐 넣고, 에이전트에 PING을 보내 보세요. PONG이 돌아오면 로드가 확인된 것입니다. 확인하고 나서는 그 줄은 지웁니다.

4. 다른 도구를 확인합니다.

대부분 할 일이 없습니다. Codex, Amp는 AGENTS.md가 기본 파일이고, Google의 Antigravity CLI(Gemini CLI 후속)도 AGENTS.md를 그대로 읽습니다. Cursor는 .cursor/rules가 없으면 AGENTS.md를 읽습니다.

5. 옮기는 김에 내용을 다듬습니다.

사실 전달 방식보다 훨씬 중요한 것이 내용입니다. ETH Zurich 연구에 따르면 LLM이 자동 생성한 컨텍스트 파일은 오히려 성공률을 낮추고 추론 비용을 20% 넘게 올렸습니다. 반면 사람이 다듬은 간결한 파일은 도움이 됐습니다. 에이전트가 코드만 봐서는 알 수 없는 것(빌드 명령, 금지 사항, 팀 규칙)만 남기고, 코드를 읽으면 알 수 있는 설명은 빼는 것이 원칙입니다. Claude Code 공식 문서도 컨텍스트 파일을 200줄 안쪽으로 유지하기를 권합니다.

*마이그레이션 5단계 흐름. 이름 변경부터 내용 다듬기까지 <출처: 작가>*

짚어둘 두 가지

첫째, 이번에 측정한 범위는 속도와 토큰 비용까지입니다. 답변의 정확성이나 안전(위험한 명령이 늘거나 줄었는지)은 별도 채점이 필요해서 이번 범위에 넣지 않았습니다. 원리상 세 조건 모두 모델에는 완전히 같은 내용이 전달되므로 정확성이 달라질 이유는 없지만, 측정하지 않은 이상 단정하지는 않겠습니다. 필요해지면 따로 진행하겠습니다.

둘째, 측정 환경은 Claude Code 2.1.198~2.1.199 기준입니다. Claude Code가 AGENTS.md를 네이티브로 지원하면 이런 연결 자체가 필요 없어집니다. 다만 이를 요청하는 공식 저장소의 이슈가 2025년 8월에 처음 열렸는데, 수천 개의 공감이 달린 지금까지도 공식 응답이 없습니다. 오래 열려 있는 이슈가 대개 그렇듯 당분간은 이 구조가 유지된다고 보는 편이 현실적이고, 그때까지 import로 연결해 써도 손해가 없다는 것을 실측으로 확인해 둔 셈입니다.

마치며: 도구, 에이전트, 그리고 지시하는 방법

2025년에는 Gateway API 구현체 7개를 비교했고, 올해는 그 인프라를 다루는 AI 에이전트 9종을 비교했습니다. 그 벤치마크는 CLAUDE.md 기반으로 설계했는데, 다음 측정으로 넘어가기 전에 AGENTS.md로 옮겨도 되는지부터 확인한 것이 이번 글입니다. 답은 “된다”였습니다.

필요한 것들이 하나씩 앞단으로 옮겨 온 셈입니다. 어떤 도구를 고를 것인가에서, 그 도구를 다룰 에이전트를 고르는 문제로, 이제는 그 에이전트에 지시하는 방법을 표준화하는 문제로 왔습니다. 도구는 계속 바뀌고 에이전트도 계속 바뀌지만, 팀의 규칙을 한 곳에 적어 두고 어떤 에이전트든 같은 규칙을 읽게 하는 구조는 오래 남을 것입니다. AGENTS.md가 그 자리를 차지해 가고 있습니다.

물론 옮기는 일이 그냥 되는 것은 아닙니다. 팀 기준 한 시간 남짓의 작업이 들고, 옮긴 뒤에도 신경 쓸 일이 생깁니다. 모두가 CLAUDE.md를 쓰는 환경에서 AGENTS.md를 중심에 두고 import로 연결하는 구조가 낯설고 부담스러운 것도 사실입니다. 이번 측정이 보여준 것 역시 속도와 토큰에서 손해가 없다는 점이지, 아무 노력도 들지 않는다는 뜻은 아닙니다.

그래도 여러 에이전트를 함께 쓰는 팀이라면, 조직 방침이나 고객 요구로 특정 도구에 묶이지 않는 구성이 필요하다면 옮길 이유는 충분합니다. 지금은 Claude가 앞서 있지만, 경쟁이 치열해져 주력 도구는 언제든 바뀔 수 있습니다. 그 가능성까지 생각하면 규칙을 표준 파일 하나에 모아 두는 쪽이 결국 좋은 선택일 수 있습니다.

이번 AGENTS.md 측정 하네스와 재현 방법은 GitHub 저장소에, 측정 설계와 해석은 블로그에 정리해 두었습니다.

끝으로 개인적인 소식을 하나 나누자면, 제가 이 AGENTS.md를 관리하는 AAIF의 앰배서더로 선정되었습니다. CNCF 앰배서더로 활동해 온 데 이어 두 번째 앰배서더 자리라 무척 기쁜 소식입니다.

AAIF는 에이전트 생태계의 개방형 표준을 중립적으로 관리하는 재단으로, MCP를 비롯해 goose, AGENTS.md, agentgateway까지 네 가지 프로젝트를 책임지고 있습니다. 지난 28일 발표된 MCP의 대형 업데이트도 조만간 자세히 소개해 보겠습니다. AAIF 앰버서더 전체 명단과 프로그램 소개는 aaif.io/ambassadors에서 보실 수 있습니다.

앞으로도 CNCF & AAIF 앰배서더로서, 어디에도 치우치지 않고 사용자에게 직접 도움이 되는 연구 활동을 공유하겠습니다.

작가

조훈 (CNCF&AAIF 앰버서더)

쿠버네티스 및 AI 네이티브 기술 전문가로, CNCF와 에이전틱 AI 재단(AAIF) 글로벌 앰버서더이자 Kubestronaut이다. 쿠버네티스랩을 운영하며 인프라 자동화 기술을 연구하고 공유한다. ‘IT 인프라 엔지니어 그룹’ 운영진이자 오픈소스 컨트리뷰터로 활동 중이며, 맞춤형 인프라 교육, 쿠버네티스 비용 최적화, 멀티 LLM 및 AI 에이전트 비교 검증 등 다양한 실무 PoC를 수행하고 있다. 최근 출간한 『AI 시대에 개발자가 알아야 할 인프라 구성 배포 with 클로드 코드』를 포함해 총 5권의 IT 서적을 집필했으며, 인프런 강의 및 요즘IT 기고 등 지식 공유 활동을 이어가고 있다.

심근우

LG유플러스 CTO부문에서 대고객 비즈니스 시스템의 DevOps를 담당하는 UcubeDAX팀의 팀장으로 일하고 있다. 퍼블릭 클라우드와 프라이빗 클라우드에 걸친 쿠버네티스 클러스터를 안정적으로 운영하기 위해 노력하고 있으며, 특히 주니어 DevOps 엔지니어들의 육성에 큰 관심을 가지고 있다.

문성주

체커(CHEQUER) 사의 DevOps Engineer로서 쿠버네티스의 멀티 클러스터 관리 방법론과 쿠버네티스 구현체(CAPI, OCI)에 대한 명세와 컨테이너 리소스 격리 방법에 대한 연구를 병행하고 있다. 이런 연구 활동을 기반으로 쿠버네티스 볼륨 테스트 파트에 컨트리뷰션했다. 본업은 쿠버네티스 오퍼레이터와 같은 CRD(커스텀 리소스)를 개발해 현업에서 쿠버네티스를 좀 더 편리하게 사용할 수 있도록 돕는 일이다. 또한, 페이스북 그룹 ‘코딩이랑 무관합니다만'과 ‘IT 인프라 엔지니어 그룹'의 운영진을 맡고 있다.

이성민

미국 넷플릭스(Netflix) 사의 Data Platform Infrastructure 팀에서 사내 플랫폼 팀들과 데이터 사용자들을 어우르기 위한 가상화 및 도구들을 개발하는 일들을 하고 있다. 과거 컨테이너와 쿠버네티스에 큰 관심을 두고 ingress-nginx를 비롯한 오픈 소스에 참여했으며, 현재는 데이터 분야에 일하게 되면서 stateful 한 서비스들이 컨테이너화에서 겪는 어려움을 보다 근본적으로 해결하기 위한 많은 노력을 하고 있다.