자동 생성된 AGENTS.md가 왜 에이전트를 더 느리고 비싸게 만들 수 있는지, 무엇을 넣어야 하는지, 더 나은 컨텍스트 아키텍처는 무엇인지 살펴봅니다.
TL;DR: 좋은 멘탈 모델은 AGENTS.md를 영구 설정이 아니라 아직 고치지 않은 코드베이스의 스멜 목록처럼 다루는 것입니다. 자동 생성된 AGENTS.md 파일은 에이전트가 이미 스스로 찾아낼 수 있는 내용을 중복해서 담기 때문에 에이전트 성능을 해치고 비용을 20% 이상 부풀립니다. 사람이 직접 쓴 파일은 도구 관련 함정, 눈에 잘 띄지 않는 규약, 지뢰 같은 비발견성 정보가 들어 있을 때만 도움이 됩니다. 그 밖의 모든 줄은 노이즈입니다.
AI 코딩 에이전트를 도입하는 개발자들 사이에서 거의 보편적인 의식처럼 자리 잡은 절차가 있습니다. 새 리포지토리를 만들고 /init를 실행한 뒤, 에이전트가 코드베이스를 스캔하는 모습을 지켜보고, 반짝이는 AGENTS.md를 돌려받습니다. 여기에는 디렉터리 구조, 기술 스택, 테스트 관례가 적혀 있습니다. 대충 훑어보면 그럴듯하고, 커밋합니다. 책임감 있게 할 일을 했다는 느낌이 듭니다. 이제 에이전트가 설정된 것입니다.
2026년 초에 발표된 두 편의 논문은, 어쩌면 당신이 방금 에이전트를 더 느리게 만들고, 더 비싸게 만들었으며, 정확도는 전혀 높이지 못했을 수 있다고 시사합니다. 그리고 그 함의는 코드베이스 개요를 넣을지 말지보다 더 멀리 뻗어 있습니다.
무엇을 넣을지의 문제를 넘어, 초기에 이름 붙일 만한 구조적 문제도 있습니다. 리포지토리 루트에 단 하나의 AGENTS.md만 두는 방식은 실제 복잡성을 가진 코드베이스에는 충분하지 않습니다. 실제로 필요한 것은 AGENTS.md 파일의 계층 구조입니다. 관련 디렉터리나 모듈 수준에 배치하고, 자동으로 유지되도록 해서, 각 에이전트가 프로젝트 전체의 관심사를 한데 뒤섞는 거대한 파일이 아니라 자신이 작업 중인 코드에 정확히 범위가 맞춰진 컨텍스트를 받도록 해야 합니다.
Lulla et al. (ICSE JAWs 2026)는 깔끔한 짝지은 실험을 수행했습니다. 실제 GitHub 풀 리퀘스트 124개를 대상으로, AGENTS.md 파일이 있는 경우와 없는 경우를 비교했고, 다른 모든 조건은 동일하게 유지했습니다. 같은 작업, 같은 리포지토리 스냅샷, 같은 에이전트입니다. 그들은 AGENTS.md 파일의 존재가 중앙값 wall-clock runtime을 28.64% 줄였고, 출력 토큰 소비를 16.58% 줄였다는 사실을 발견했습니다. 통계적으로 유의미했습니다. 에이전트는 더 저렴하고 더 빨라졌습니다.
이건 분명한 승리처럼 들립니다. 잠깐만 생각을 멈춰 봅시다.
ETH Zurich의 별도 연구는 SWE-bench와, 이미 개발자가 작성한 컨텍스트 파일을 갖고 있는 리포지토리들로 만든 맞춤형 벤치마크에서 네 개의 에이전트를 테스트했습니다. 이들의 결과는 정반대 방향을 가리킵니다. LLM이 생성한 컨텍스트 파일은 작업 성공률을 2~3% 낮추는 동시에 비용은 20% 이상 증가시켰습니다. 개발자가 쓴 파일은 성공률을 약 4% 높였지만, 비용도 최대 19% 증가시켰습니다.
그렇다면 어느 쪽일까요? AGENTS.md는 도움이 될까요, 해가 될까요?
둘 다입니다. 무엇을 넣느냐에 따라 달라집니다. 그리고 사실 이 점이 더 흥미로운 결과입니다.
ETH Zurich 논문은 이 논쟁 전체를 다시 보게 만드는 사실을 발견했습니다. 리포지토리에서 README, docs 폴더, 마크다운 파일 등 모든 문서를 제거한 다음 그 후에 LLM 생성 컨텍스트 파일을 테스트했더니, 그 파일들이 갑자기 성능을 2.7% 향상시켰습니다. 자동 생성 콘텐츠가 쓸모없는 것이 아닙니다. 중복된 것입니다. 에이전트는 어차피 그것을 스스로 찾을 수 있었습니다. 같은 정보를 두 번 주면, 그저 노이즈를 추가한 셈입니다.
반면 Lulla 논문은 개발자들이 실제로 유지 관리하던 리포지토리의 사람이 작성한 AGENTS.md 파일을 사용했습니다. 실제 프로젝트 특화 지식, 눈에 잘 띄지 않는 도구 요구사항, 진짜 함정들입니다. 바로 이런 컨텍스트가 에이전트의 시간을 절약해 줍니다. 스스로 발견할 수 없는 것을 추론하려 애쓸 필요가 없기 때문입니다.
질문은 AGENTS.md를 둘 것인가가 아닙니다. 어떤 내용이 그 안의 한 줄을 차지할 자격이 있는가입니다.
AGENTS.md 파일에는 효율성 지표에 드러나지 않는 더 미묘한 비용이 있습니다. 바로 고정 효과입니다.
AGENTS.md에 백엔드에서 tRPC를 사용한다고 적혀 있다고 해봅시다. 아키텍처 개요에서 스쳐 지나가듯 언급한 정도라도 말입니다. 그러면 이제 모델은 모든 프롬프트마다 tRPC를 컨텍스트에 두게 됩니다. tRPC가 몇몇 레거시 엔드포인트에서만 쓰이고, 새로운 것은 전부 다른 방식으로 돌아간다면, 당신은 에이전트를 현재 코드베이스에 맞지 않는 패턴으로 편향시킨 것입니다. 당신이 말했고, 그 정보는 거기 있으며, LLM은 “이건 예전에 하던 방식이다”와 “이건 지금 네가 따라야 하는 방식이다”를 구분하지 못합니다.
이것은 프롬프트 엔지니어링의 지혜가 시스템 프롬프트에 무엇을 넣는지 조심하라고 늘 말해 온 것과 같은 이유입니다. 추가하는 모든 것은 실제 작업과 경쟁합니다. 더 넓은 의미의 LLM 컨텍스트 연구도 일관된 패턴을 보여 줍니다. 컨텍스트가 많아질수록 성능이 나빠지는 경우가 많고, 이는 비용 때문만이 아니라 주의가 희석되기 때문이기도 합니다. Liu 등의 “Lost in the Middle” 결과(2024)는 긴 컨텍스트의 중간에 놓인 정보를 LLM이 잘 다루지 못한다는 점을 보여 주었습니다. Levy 등은 내용이 완벽하게 관련 있어도 컨텍스트가 길어지면 작업 성능이 떨어진다는 점을 보였습니다. AGENTS.md의 모든 줄은 당신이 실제로 에이전트에게 요청한 일과 경쟁하는 한 줄입니다.
자동 생성 컨텍스트 파일의 핵심 문제는 이것입니다. /init는 무엇을 만들어낼까요? 코드베이스 개요, 디렉터리 구조, 기술 스택 설명, 모듈 설명입니다. ETH Zurich 논문에 따르면 Sonnet 4.5가 자동 생성한 컨텍스트 파일의 100%에는 코드베이스 개요가 들어 있었습니다. GPT-5.2의 경우도 99%가 마찬가지였습니다.
이것들은 에이전트가 디렉터리 목록을 보고 기존 README를 읽는 것만으로 스스로 알아낼 수 있는 것들입니다. 실제로 AGENTS.md의 존재 여부와 무관하게 에이전트는 어차피 그렇게 합니다. 그러니 당신은 에이전트가 읽는 파일 하나를 추가했고, 에이전트는 그다음 실제 코드를 읽어 그 내용을 다시 확인하며, 이제 두 개의 진실 공급원을 조정해야 합니다. 더 많은 추론 토큰, 더 많은 단계, 같은 결과. 단지 더 느리고 더 비싸질 뿐입니다.
ETH Zurich 논문은 무엇이 효과적인지에 대해 구체적인 사실을 보여 주었습니다. 개발자가 쓴 컨텍스트 파일에 uv가 언급되면, 에이전트는 작업당 평균 1.6회 그것을 사용했습니다. 언급되지 않으면 0.01회보다 적게 사용했습니다. 다른 리포지토리 특화 도구들에서도 같은 패턴이 나타났습니다. 언급되면 작업당 2.5회 사용했고, 언급되지 않으면 0.05회보다 적게 사용했습니다.
uv 대 pip는 AGENTS.md에 들어가야 할 것이 무엇인지 보여 주는 완벽한 예입니다. 이것은:
이를 “이 프로젝트는 /packages에 패키지가 있는 모노레포 구조를 사용한다”와 비교해 보세요. 에이전트는 첫 번째 디렉터리 목록 조회에서 이미 이것을 알아냅니다. 한쪽은 한 줄을 차지할 자격이 있습니다. 다른 한쪽은 노이즈입니다.
실용적인 필터는 단순합니다. 에이전트가 코드를 읽어서 이것을 스스로 알아낼 수 있는가? 그렇다면 지우세요. 모든 줄은 리포지토리 안에 이미 존재하지 않는 정보를 담아야 합니다.
그 말은 AGENTS.md가 다음과 더 비슷해야 한다는 뜻입니다:
패키지 관리는 uv를 사용
–no-cache 없이 테스트를 실행하면 fixture 설정 때문에 false positive가 나므로 항상 해당 옵션과 함께 실행
auth 모듈은 커스텀 미들웨어 패턴을 사용하므로 표준 Express 미들웨어로 리팩터링하지 말 것
legacy/ 디렉터리는 폐기 예정이지만 세 개의 프로덕션 모듈이 import하고 있으므로 그 안의 어떤 것도 삭제하지 말 것
그리고 그 외에는 거의 아무것도 없어야 합니다.
타이트하고 중복 없는 AGENTS.md를 작성하더라도, 구조적 약점이 있습니다. 파일은 정적이지만 작업은 동적이라는 점입니다.
파일에는 “커밋 전에 항상 테스트 스위트를 실행하라”고 적혀 있습니다. 그런데 에이전트는 문서 변경 작업을 하고 있습니다. 에이전트는 성실하게 전체 테스트 스위트를 실행합니다. 코드 변경에는 맞는 지시였을지 몰라도, 이번 작업에는 불필요한 지시 하나 때문에 토큰이 타고, 시간이 낭비됩니다.
이것은 가상의 실패 모드가 아닙니다. 아키텍처에 내장된 문제입니다. 평평한 지시 집합은 어떤 종류의 작업이 실행 중인지에 따라 조건부로 반응할 수 없습니다. CSS 리팩터링을 하는 에이전트에게는 데이터베이스 마이그레이션 경고가 필요 없습니다. 보안 수정 작업을 하는 에이전트라면 성능 최적화 힌트는 건너뛰는 편이 나을 수도 있습니다. 하나의 거대한 파일은 매번 같은 방식으로 로드됩니다.
ACE framework(Agentic Context Engineering, ICLR 2026)는 이 문제를 정면으로 다룹니다. 정적 파일이 아니라 generator/reflector/curator 파이프라인을 통해 적응하는 진화하는 플레이북으로 컨텍스트를 다루는 방식입니다. 에이전트 벤치마크에서 정적 접근보다 12.3% 더 좋은 성능을 냈습니다. 아키텍처는 중요합니다.
AGENTS.md를 둘러싼 담론에서 여러 사람이 거의 같은 아이디어에 독립적으로 수렴해 왔습니다. 올바른 구조는 하나의 거대한 파일이 아니라, 필요할 때 초점 맞춘 컨텍스트를 로드하는 라우팅 레이어라는 것입니다.
구조는 대략 다음과 같을 것입니다:
레이어 1: 프로토콜 파일 (AGENTS.md가 실제로 되어야 하는 것) 코드베이스 개요가 아닙니다. 스타일 가이드도 아닙니다. 라우팅 문서입니다. 사용 가능한 페르소나와 언제 호출해야 하는지. 사용 가능한 스킬과 어떤 작업 클래스를 다루는지. 사용 가능한 MCP 연결과 그것들의 용도. 에이전트가 정말로 스스로 발견할 수 없는 최소한의 핵심 리포지토리 사실들, 그리고 그 외에는 아무것도 없습니다.
레이어 2: 초점 맞춘 페르소나/스킬 파일 작업 유형에 따라 선택적으로 로드됩니다. 컴포넌트 아키텍처를 다루는 UX 중심 에이전트는 데이터 파이프라인을 디버깅하는 백엔드 에이전트와 다른 컨텍스트를 로드합니다. 어느 쪽도 상대방의 컨텍스트를 로드하지 않습니다. 특정 작업에 대한 전체 컨텍스트 양은 제한된 상태로 유지됩니다.
레이어 3: 유지관리 서브에이전트 유일한 역할은 코드베이스가 진화함에 따라 프로토콜 파일을 정확하게 유지하는 것입니다. 아무도 잘 말하지 않는 사실이 있기 때문입니다. 문서는 썩습니다. ETH Zurich 연구는 갓 생성된 컨텍스트 파일을 사용했는데도 성능 저하를 발견했습니다. 여섯 달 동안 손대지 않은 실제 AGENTS.md 파일이, 이미 교체한 의존성이나 바뀐 디렉터리 구조를 설명하고 있다면 어떨까요? 더 나쁠 것입니다. 훨씬 더 나쁠 것입니다.
주요 코딩 에이전트들 가운데 이 아키텍처를 쉽게 만들 수 있도록 라이프사이클 훅을 노출하는 도구는 없습니다. 서브에이전트와 범위가 제한된 컨텍스트로 얼추 흉내 낼 수는 있지만, 아직 깔끔한 해법은 없습니다. 이것은 채워지기를 기다리는 툴링 공백입니다.
이 영역에서 가장 도발적인 발견은 Arize AI의 프롬프트 학습 작업에서 나왔습니다. CLAUDE.md 지침을 손으로 쓰는 대신, 그들은 자동 최적화 루프를 사용했습니다. 학습 작업에 에이전트를 실행하고, 출력을 평가하고, 왜 해법이 실패했는지에 대한 LLM 피드백을 생성하고, meta-prompting을 사용해 지침을 다듬습니다. 이를 반복합니다.
결과는 다음과 같습니다. 교차 리포지토리 테스트 분할에서 정확도 +5.19% 향상. 리포지토리 내부 분할에서는 +10.87%(과거 Django 이슈로 학습하고 미래 이슈로 테스트).
최적화기가 발견한 것은 불편한 함의입니다. 사람이 코드베이스를 이해하는 데 도움이 되는 것과 LLM이 그 안을 탐색하는 데 도움이 되는 것은 종종 다릅니다. 당신에게는 분명히 유용해 보이는 지시, 예를 들어 “이 서비스는 repository pattern을 사용한다” 같은 말은 모델에게는 노이즈일 수 있습니다. 반대로 모델이 실제로 필요로 하는 것, 예를 들어 특정 import path를 구분하는 방식이나 눈에 잘 띄지 않는 파일 명명 규칙 같은 것은, 당신은 이미 내면화했기 때문에 적어 둘 생각조차 못 할 수 있습니다.
AGENTS.md에 대한 수동 접근은 당신이 에이전트에게 필요한 것이 무엇인지 안다고 가정합니다. 경험적 증거는 아마 그렇지 않다는 점을 시사합니다. 최적화기는 당신이 중요하다고 생각하는 것과 실제로 성능을 움직이는 것 사이의 차이를 찾아냅니다.
그렇다고 컨텍스트 파일 작성을 포기해야 한다는 뜻은 아닙니다. 자동 최적화 연구는 아직 초기 단계이고, 5%는 의미 있지만 판도를 바꿀 정도는 아닙니다. 다만 무엇을 넣어야 하는지에 대한 직관을 느슨하게 붙들고 있어야 하며, 아마도 직접 테스트해 봐야 한다는 뜻입니다.
AGENTS.md를 아직 고치지 않은 마찰의 살아 있는 문서라고 생각해 보세요.
당신이 추가하는 모든 줄은 코드베이스 안에 AI 에이전트를 걸려 넘어지게 할 만큼 혼란스러운 무언가가 있다는 신호입니다. 즉, 새로 들어온 인간 기여자도 충분히 헷갈릴 가능성이 높다는 뜻입니다. 이 신호에 대한 올바른 반응은 컨텍스트 파일을 키우는 것이 아닙니다. 실제 문제를 고치는 것입니다.
에이전트가 계속 새 유틸리티를 잘못된 디렉터리에 넣나요? 그렇다면 디렉터리 구조가 혼란스러워서 재조직해야 할지도 모릅니다. 에이전트가 계속 폐기된 의존성을 집어 드나요? 그렇다면 import 구조 때문에 잘못된 것을 너무 쉽게 집고 있는지도 모릅니다. 에이전트가 타입 체크 실행을 자꾸 잊나요? 그렇다면 빌드 파이프라인이 산문 지시에 의존하지 말고 그 문제를 자동으로 잡아줘야 할지도 모릅니다.
AGENTS.md는 영구 설정이 아니라 진단 도구가 됩니다. 한 줄을 추가하고, 왜 에이전트가 계속 이 실수를 하는지 조사하고, 근본 원인을 고치고, 그러고 나면 아마 그 줄을 지울 수 있을 것입니다.
시도해 볼 만한 한 가지 기법이 있습니다. AGENTS.md를 거의 비워 둔 상태로 시작하고, 지시 하나만 추가하는 것입니다. “이 프로젝트에서 놀랍거나 혼란스러운 점을 마주치면, 코멘트로 표시하라.” 에이전트가 제안하는 추가사항 대부분은 영구 보존할 대상이 아니라 코드베이스가 어디에서 불명확한지를 보여 주는 지표입니다. 그것을 고치세요. 파일은 최소한으로 유지하세요.
두 논문 모두 짚고 넘어가야 할 실제 한계를 갖고 있습니다.
Lulla 논문은 정확성을 전혀 측정하지 않고 효율성만 측정합니다. 따라서 AGENTS.md가 출력 품질을 개선한다고 결론 내릴 수는 없습니다. 저자들도 이 점을 분명히 밝힙니다. 에이전트가 사소하지 않은 출력을 생성하는지 확인하기 위한 sanity check는 수행했지만, 완전한 정확성 평가는 향후 과제입니다. 더 빠르고 더 저렴하다는 것은 의미 있지만, 코드가 틀리다면 소용이 없습니다.
ETH Zurich 논문은 새로 만든 컨텍스트 파일을 사용했습니다. 이는 실험 통제 측면에서는 이상적이지만, 대부분의 개발자가 실제로 사는 시나리오를 시험한다고 보기는 어렵습니다. 현실 세계의 경우는 리포지토리에 몇 달 동안 있었고 부분적으로 오래된 컨텍스트 파일입니다. 이는 논문이 측정한 것보다 더 나쁜 성능을 보일 가능성이 큽니다.
두 논문 모두 여러 실무자가 올바른 아키텍처라고 주장하는 계층적이고 동적으로 로드되는 접근을 테스트하지 않습니다. 평가되는 것은 오직 “평평하고 거대한 단일 컨텍스트 파일”입니다. 선택적 컨텍스트 로딩을 갖춘 제대로 계층화된 시스템이 다른 성능을 보이는지는 여전히 열린 경험적 질문입니다.
그리고 모델 궤적 문제도 있습니다. 몇 달에 한 번씩, 개발자들은 기반 모델이 코드베이스 내비게이션을 더 잘하게 되면서 컨텍스트 파일에 넣어야 할 것이 줄어든다고 말합니다. 여섯 달 전에는 필수였던 지시가 모델이 개선되면서 중복이 됩니다. 오늘 작성하는 AGENTS.md는 다음 분기쯤이면 순수한 오버헤드가 될 수도 있습니다.
/init 실행을 멈추세요. 자동 생성 출력은 당신의 기존 문서와 중복되며, 리포지토리에 진짜로 문서가 전혀 없는 경우가 아니라면 이점 없이 오버헤드만 추가합니다. 그런 경우라 해도 아주 약간 없는 것보다는 나을 뿐입니다.
AGENTS.md에 어떤 줄이든 추가하기 전에 물어보세요. 에이전트가 코드를 읽어서 이것을 찾을 수 있는가? 그렇다면 쓰지 마세요.
에이전트가 어떤 문제로 반복해서 어려움을 겪는다면, 그것을 컨텍스트 문제로 보기 전에 먼저 코드베이스 문제로 다루세요. 코드를 재구성하세요. linter 규칙을 추가하세요. 테스트 커버리지를 개선하세요. 그 옵션들을 다 써 본 뒤에야 AGENTS.md를 꺼내 드세요.
CI/CD나 자동 리뷰 파이프라인에서 대규모로 에이전트를 운영하고 있다면, 컨텍스트 파일로 인한 15~20%의 비용 오버헤드는 수천 번의 실행에 걸쳐 누적됩니다. 그 트레이드오프가 가치 있는지 당연하게 여기기 전에 먼저 계산해 보세요.
컨텍스트 파일이 썩어 가게 내버려두는 대신, 그것을 정확하게 유지하는 일을 맡는 유지관리 에이전트를 만드는 것도 고려해 보세요.
그리고 에이전트에게 무엇이 필요한지에 대한 당신의 직관을 느슨하게 붙드세요. 당신에게는 분명히 유용해 보이는 것이 모델에게는 노이즈일 수 있습니다. 경험적 증거는 우리가 에이전트에게 필요하다고 생각하는 것과 실제로 도움이 되는 것 사이의 간극이 상당하다는 점을 시사하며, 아마도 그 방향은 우리가 예상하는 쪽이 아닐 가능성이 큽니다.
코딩 에이전트를 새로 입사한 직원처럼 온보딩하고 싶어지는 본능, 즉 사무실 투어를 시켜 주고, 조직도를 설명하고, 아키텍처를 같이 훑어 주고 싶어지는 마음은 충분히 이해할 만합니다. 하지만 코딩 에이전트는 신입 직원이 아닙니다. 당신이 프롬프트를 다 치기도 전에 코드베이스 전체를 grep할 수 있습니다. 그들에게 필요한 것은 지도 아닙니다. 어디에 지뢰가 묻혀 있는지 아는 것입니다.
그리고 어쩌면 점점 더, 그것조차 필요 없을지도 모릅니다.
영상에 관심이 있다면, 이 주제에 대한 Theo의 견해도 아주 훌륭합니다.
Matt Pocock의 것도 마찬가지입니다:
