AI 코딩 에이전트를 신입 직원처럼 온보딩하려 할수록, 오히려 에이전트는 느려지고 비용은 올라갑니다. 왜 그럴까요?
Google Chrome 팀의 Addy Osmani가 2026년 초 발표된 두 편의 연구를 토대로 AGENTS.md(또는 CLAUDE.md) 사용 방식을 재검토해야 한다는 내용의 글을 발표했습니다. AI 코딩 에이전트에 컨텍스트 파일을 제공하는 것이 항상 도움이 되지는 않으며, 무엇을 넣느냐에 따라 성능을 높이기도, 낮추기도 한다는 것이 핵심입니다.
출처: Stop Using /init for AGENTS.md – Addy Osmani
두 연구가 보여준 상반된 결과
Lulla et al.(ICSE JAWs 2026)은 124개의 실제 GitHub PR을 대상으로 AGENTS.md 유무만 다르게 해 실험했습니다. 결과는 AGENTS.md가 있을 때 에이전트 실행 시간이 28.64% 단축되고, 토큰 소비도 16.58% 줄었습니다. 명확한 효율 향상이었죠.
그런데 ETH Zurich의 별도 연구는 반대 방향을 가리킵니다. LLM이 자동 생성한 컨텍스트 파일은 작업 성공률을 2~3% 낮추면서 비용은 20% 이상 올렸습니다. 개발자가 직접 작성한 파일은 성공률을 4% 높였지만, 역시 비용이 최대 19% 늘었습니다.
왜 이렇게 엇갈릴까요? ETH Zurich 연구가 결정적인 단서를 제공합니다. 저장소에서 모든 문서(README, docs 폴더 등)를 제거한 뒤 자동 생성 컨텍스트 파일을 테스트했더니, 오히려 성능이 2.7% 개선됐습니다. 자동 생성 내용이 쓸모없는 게 아니라 중복이었던 겁니다. 에이전트는 어차피 코드베이스를 직접 읽으며 같은 정보를 찾아냅니다. 같은 정보를 두 번 주면 에이전트는 두 출처를 대조하느라 토큰을 더 씁니다.
반면 Lulla 연구에서 효과를 보인 파일들은 개발자가 실제로 관리해온 것들이었습니다. 코드베이스에서 스스로 추론하기 어려운 정보, 즉 진짜 함정과 비표준 관례가 담겨 있었죠.
/init이 만드는 게 바로 그 중복
/init이 생성하는 내용을 보면 패턴이 명확합니다. ETH Zurich 연구에서 Claude Sonnet 4.5가 자동 생성한 파일의 100%, GPT-5.2가 생성한 파일의 99%에 코드베이스 개요가 포함됐습니다. 디렉토리 구조, 기술 스택, 모듈 설명 같은 것들이죠.
이것들은 에이전트가 첫 번째 디렉토리 목록을 조회하는 순간 이미 파악하는 내용입니다. 결과적으로 에이전트는 AGENTS.md를 읽고, 실제 코드를 읽고, 두 출처를 맞춰보는 과정을 거칩니다. 더 많은 추론 토큰, 더 많은 단계, 결과는 같은데 더 느리고 더 비쌉니다.
앵커링 효과: 오래된 정보가 에이전트를 편향시킨다
컨텍스트 파일에는 효율 지표에 잡히지 않는 비용도 있습니다. 앵커링 효과입니다.
AGENTS.md에 “백엔드는 tRPC를 사용합니다”라는 한 줄이 있다고 가정해 봅시다. 해당 코드가 몇 개의 레거시 엔드포인트에만 남아 있고 새 코드는 전혀 다른 스택을 쓴다 해도, 에이전트는 이제 모든 프롬프트에서 tRPC를 의식합니다. LLM은 “예전에 쓰던 것”과 “지금 써야 할 것”을 구분하지 않습니다.
이는 프롬프트 엔지니어링의 오래된 교훈과 같은 맥락입니다. 시스템 프롬프트에 추가하는 모든 내용은 실제 작업과 주의력을 두고 경쟁합니다. Liu et al.의 “Lost in the Middle”(2024) 연구는 LLM이 긴 컨텍스트 중간에 있는 정보를 잘 처리하지 못한다는 것을 보여줬고, Levy et al.은 내용이 완전히 관련 있어도 긴 컨텍스트 자체가 성능을 저하시킨다는 것을 발견했습니다.
AGENTS.md에 넣어야 할 것과 넣지 말아야 할 것
ETH Zurich 연구는 구체적인 단서를 줍니다. 개발자가 작성한 파일에 uv가 언급된 경우, 에이전트는 작업당 평균 1.6회 이를 사용했습니다. 언급이 없었을 때는 0.01회 미만이었습니다. 다른 저장소 특화 도구도 같은 패턴을 보였습니다.
uv vs pip 선택은 AGENTS.md에 넣을 정보의 완벽한 예시입니다. 코드베이스에서 추론으로 발견하기 어렵고, 에이전트가 실행하는 명령어를 실질적으로 바꾸며, 관례로는 추측할 수 없기 때문입니다. 반면 “이 프로젝트는 /packages에 패키지가 있는 모노레포 구조입니다”는 에이전트가 첫 디렉토리 조회로 파악하는 내용이죠.
판단 기준은 단순합니다. “에이전트가 코드를 읽으면서 스스로 찾을 수 있는가?” — 그렇다면 넣지 마세요.
올바른 마인드셋: 진단 도구로서의 AGENTS.md
Osmani가 제안하는 관점 전환이 인상적입니다. AGENTS.md를 영구 설정 파일이 아니라 아직 고치지 못한 코드베이스 냄새(smell) 목록으로 보라는 것입니다.
에이전트가 계속 같은 실수를 반복한다면, 그건 컨텍스트 파일 문제가 아니라 코드베이스 문제일 가능성이 높습니다. 잘못된 디렉토리에 파일을 넣는다면 디렉토리 구조가 혼란스러운 것이고, 오래된 의존성을 계속 선택한다면 임포트 구조가 잘못된 것이며, 타입 체크를 빠뜨린다면 빌드 파이프라인이 자동으로 잡아야 합니다.
이 관점에서 AGENTS.md는 이런 형태가 됩니다:
uv로 패키지를 관리하세요--no-cache없이 테스트를 실행하면 픽스처 설정 문제로 위양성이 납니다- auth 모듈은 커스텀 미들웨어 패턴을 사용합니다. 표준 Express 미들웨어로 리팩토링하지 마세요
legacy/디렉토리는 deprecated됐지만 프로덕션 모듈 세 개가 임포트합니다. 삭제하지 마세요
그 외에는 거의 없어야 합니다.
다만 이렇게 잘 정리된 파일에도 구조적 한계가 있습니다. 지시는 정적이지만 작업은 동적이기 때문입니다. “커밋 전 항상 테스트 스위트를 실행하라”는 지시는 코드 변경에는 타당하지만, 문서 수정 작업에서 에이전트가 전체 테스트를 충실히 돌리는 것은 낭비입니다. 단일 파일은 작업 유형에 따라 조건을 달 수 없으니까요. ACE(Agentic Context Engineering) 프레임워크는 정적 파일 대신 task 유형에 따라 컨텍스트를 동적으로 로드하는 방식으로, 기존 정적 접근 대비 벤치마크에서 12.3% 향상을 보였습니다.
원문에는 자동화된 최적화 루프로 AGENTS.md를 개선하는 Arize AI의 프롬프트 학습 실험 결과(정확도 최대 +10.87%), 레이어드 컨텍스트 아키텍처의 상세 설계, 그리고 현재 두 연구가 검증하지 못한 영역들에 대한 논의도 담겨 있습니다.
참고자료:
답글 남기기