AGENTS.md에 /init 명령어, 이제 그만 쓰세요

AI 코딩 에이전트를 도입하는 개발자들 사이에서 어느새 하나의 의식처럼 굳어진 행동이 있습니다. 새 저장소를 만들고 /init을 실행하면, 에이전트가 코드베이스를 훑고 나서 반짝이는 AGENTS.md를 내놓습니다. 디렉터리 구조, 기술 스택, 테스트 관례가 잘 정리되어 있죠. 대충 훑어보면 그럴듯해 보이고, 커밋을 올리고 나면 뭔가 제대로 준비를 마친 것 같은 기분이 듭니다. 에이전트 설정이 완료됐다고 느끼는 겁니다.

2026년 초 발표된 두 편의 논문은 그 행동이 오히려 에이전트를 느리고, 비싸고, 결과는 그대로인 상태로 만들었을 수 있다고 말합니다. 그리고 그 시사점은 단순히 코드베이스 개요를 포함할지 말지의 문제를 훨씬 넘어섭니다.

무엇을 담을지와는 별개로, 구조적인 문제도 짚고 넘어갈 필요가 있습니다. 저장소 루트에 AGENTS.md 하나를 두는 방식은 어느 정도 복잡성을 가진 코드베이스에서는 충분하지 않습니다. 실제로 필요한 건 디렉터리나 모듈 단위로 배치된 AGENTS.md 파일의 계층 구조입니다. 각 에이전트가 작업 중인 코드에 딱 맞는 컨텍스트만 받을 수 있도록, 프로젝트 전체를 뭉뚱그린 단일 파일 대신 자동으로 관리되는 계층 구조가 필요합니다.

연구가 실제로 말하는 것

Lulla 외 (ICSE JAWs 2026)는 깔끔한 대조 실험을 설계했습니다. 실제 GitHub 풀 리퀘스트 124개를 AGENTS.md 파일이 있는 경우와 없는 경우로 나누어 실행하되, 나머지 조건은 모두 동일하게 유지했습니다. 같은 작업, 같은 저장소 스냅샷, 같은 에이전트입니다. 결과적으로 AGENTS.md가 있을 때 실제 실행 시간 중앙값이 28.64% 단축되고 출력 토큰 소비량이 16.58% 감소하는 것으로 나타났습니다. 통계적으로도 유의미한 결과로, 에이전트가 더 빠르고 저렴해진 것입니다.

명백한 성과처럼 들립니다. 그런데 잠깐 생각해 봅시다.

ETH 취리히의 별도 연구에서는 네 가지 에이전트를 SWE-bench와 개발자가 직접 작성한 컨텍스트 파일이 이미 있는 저장소를 대상으로 한 커스텀 벤치마크에서 테스트했습니다. 결과는 반대 방향을 가리켰습니다. LLM이 생성한 컨텍스트 파일은 작업 성공률을 2~3% 낮추는 동시에 비용을 20% 이상 높였습니다. 개발자가 직접 작성한 파일은 성공률을 약 4% 높였지만, 비용 역시 최대 19%까지 증가했습니다.

그렇다면 어느 쪽이 맞을까요? AGENTS.md는 도움이 될까요, 해가 될까요?

무엇을 담느냐에 따라 둘 다입니다. 그리고 사실 이게 더 흥미로운 결론입니다.

ETH 취리히 논문은 이 논쟁 전체를 새롭게 바라보게 하는 발견을 했습니다. 저장소에서 README, docs 폴더, 마크다운 파일 등 모든 문서를 제거한 뒤 LLM이 생성한 컨텍스트 파일로 테스트하자, 그 파일이 성능을 2.7% 향상시켰습니다. 자동 생성된 내용이 쓸모없는 게 아닙니다. 문제는 중복이라는 겁니다. 에이전트는 어차피 저장소를 읽으면서 그 내용을 스스로 찾아낼 수 있습니다. 이미 있는 정보를 두 번 건네면 그건 그냥 노이즈가 될 뿐입니다.

반면 Lulla 논문은 개발자들이 실제로 관리해온 저장소의 AGENTS.md, 즉 사람이 직접 작성한 파일을 사용했습니다. 프로젝트에 특화된 실질적인 지식, 직관적이지 않은 도구 요구사항, 실제 함정들이 담겨 있었습니다. 에이전트가 스스로 추론해서는 알아낼 수 없는 정보가 시간을 아껴준 것입니다.

AGENTS.md를 쓸 것이냐 말 것이냐가 아닙니다. 어떤 내용이 한 줄을 차지할 자격이 있는가가 핵심입니다.

분홍 코끼리 문제

AGENTS.md 파일에는 효율성 지표에는 잘 드러나지 않는 더 미묘한 비용이 있습니다. 바로 앵커링 효과입니다.

AGENTS.md에 백엔드에서 tRPC를 사용한다고 적혀 있다면, 설령 아키텍처 개요에 가볍게 언급한 것뿐이라도 모델은 매번 프롬프트마다 tRPC를 컨텍스트에 담아두게 됩니다. 만약 tRPC가 일부 레거시 엔드포인트에서만 쓰이고 새로운 코드는 전혀 다른 방식으로 돌아간다면, 에이전트가 현재 코드베이스에 맞지 않는 패턴으로 편향되도록 만든 셈입니다. 한번 적어두면 그게 거기 있는 것이고, LLM은 "예전에 우리가 쓰던 방식"과 "지금 써야 할 방식"을 구분하지 못합니다.

프롬프트 엔지니어링(prompt engineering)의 오랜 원칙이 시스템 프롬프트에 무엇을 넣을지 신중히 생각하라고 강조해온 것도 같은 이유입니다. 추가하는 내용은 모두 실제 작업과 경쟁하게 됩니다. LLM 컨텍스트에 관한 광범위한 연구들은 일관된 패턴을 보여줍니다. 컨텍스트가 많아질수록 비용뿐 아니라 주의력 분산을 통해서도 성능이 저하된다는 것입니다. Liu 외의 "Lost in the Middle"(2024) 연구는 LLM이 긴 컨텍스트 중간에 배치된 정보를 제대로 처리하지 못한다는 사실을 보여줬고, Levy 외의 연구는 내용이 완전히 관련성 있는 경우에도 긴 컨텍스트가 작업 성능을 저하시킨다고 밝혔습니다. AGENTS.md의 모든 줄은 실제로 에이전트에게 요청한 작업과 자리를 두고 경쟁합니다.

/init을 반대하는 이유

자동 생성 컨텍스트 파일의 핵심 문제는 이렇습니다. /init는 무엇을 만들어낼까요? 코드베이스 개요, 디렉터리 구조, 기술 스택 설명, 모듈 설명. ETH 취리히 논문에 따르면 Sonnet 4.5가 자동 생성한 컨텍스트 파일의 100%가 코드베이스 개요를 포함했고, GPT-5.2도 99%가 마찬가지였습니다.

이것들은 정확히 에이전트가 디렉터리를 나열하고 기존 README를 읽는 것만으로 스스로 파악할 수 있는 내용입니다. 에이전트는 AGENTS.md 유무와 관계없이 어차피 그렇게 합니다. 결국 에이전트가 파일을 읽고, 실제 코드를 읽어 확인하고, 두 출처를 대조해야 하는 상황이 됩니다. 추론 토큰은 늘어나고, 단계는 많아지고, 결과는 같은데 더 느리고 더 비쌉니다.

한 줄을 차지할 자격이 있는 것들

ETH 취리히 논문은 실제로 효과 있는 것에 대해 구체적인 결과를 보여줬습니다. 개발자가 직접 작성한 컨텍스트 파일에 uv이 언급된 경우, 에이전트는 작업당 평균 1.6회 사용했습니다. 언급되지 않은 경우에는 0.01회 미만이었습니다. 저장소 특화 도구들에서도 같은 패턴이 나타났습니다. 언급된 경우 작업당 2.5회, 언급되지 않은 경우 0.05회 미만이었습니다.

uv와 pip의 차이는 AGENTS.md에 들어갈 만한 내용의 전형적인 예입니다. 이런 내용은:

코드베이스를 읽는 것만으로는 추론 없이 알 수 없고
실질적으로 중요하며 (에이전트가 실행하는 명령어가 바뀝니다)
에이전트가 관례만으로 올바르게 추측하기 불가능합니다

반면 "이 프로젝트는 /packages에 패키지가 있는 모노레포 구조를 사용한다"는, 에이전트가 첫 디렉터리 목록에서 바로 확인하는 내용입니다. 둘 중 하나는 한 줄을 차지할 자격이 있고, 하나는 노이즈입니다.

판단 기준은 단순합니다. 에이전트가 코드를 읽으면서 스스로 찾아낼 수 있는가? 그렇다면 삭제하세요. 모든 줄은 저장소 안에 이미 없는 정보여야 합니다.

그렇다면 AGENTS.md는 다음과 같은 모습에 가까워야 합니다:

- Use `uv` for package management
- Always run tests with `–no-cache` or you'll get false positives from the fixture setup
- The auth module uses a custom middleware pattern; do not refactor to standard Express middleware
- The `legacy/` directory is deprecated but imported by three production modules - don't delete anything in it

그리고 거의 그게 전부입니다.

정적 파일의 문제

군더더기 없이 잘 작성된 AGENTS.md라도 구조적인 약점이 있습니다. 파일은 정적이지만, 작업은 동적이라는 점입니다.

파일에는 "커밋 전에 항상 테스트 스위트를 실행하라"고 적혀 있습니다. 에이전트는 문서 수정 작업을 하고 있습니다. 지침에 따라 전체 테스트 스위트를 충실히 실행합니다. 코드 변경에는 맞는 지침이지만, 지금 이 작업에는 불필요한 일에 토큰과 시간이 낭비됩니다.

이건 가상의 실패 시나리오가 아닙니다. 아키텍처 자체에 내재된 문제입니다. 단일한 지침 집합은 어떤 종류의 작업인지에 따라 조건부로 동작할 수 없습니다. CSS 리팩터링 작업을 하는 에이전트에게는 데이터베이스 마이그레이션 경고가 필요 없습니다. 보안 수정을 구현하는 에이전트는 성능 최적화 힌트를 건너뛰어야 할 것입니다. 단일 파일은 매번 동일한 방식으로 불러와집니다.

ACE 프레임워크(Agentic Context Engineering, ICLR 2026)는 이 문제를 정면으로 다룹니다. 컨텍스트를 정적 파일이 아니라 생성기/반영기/큐레이터 파이프라인을 통해 진화하는 플레이북으로 취급합니다. 에이전트 벤치마크에서 정적 방식 대비 12.3% 높은 성능을 보였습니다. 아키텍처가 중요합니다.

아직 아무도 만들지 않은 더 나은 아키텍처

AGENTS.md 논쟁을 지켜보는 여러 사람들이 각자 독립적으로 비슷한 결론에 도달했습니다. 올바른 구조는 단일 파일이 아니라, 필요에 따라 집중된 컨텍스트를 불러오는 라우팅 레이어라는 것입니다.

구조는 대략 이런 모습이 될 것입니다:

레이어 1: 프로토콜 파일 (AGENTS.md가 실제로 담아야 할 것) 코드베이스 개요가 아닙니다. 스타일 가이드도 아닙니다. 라우팅 문서입니다. 사용 가능한 페르소나와 언제 호출할지. 사용 가능한 스킬과 어떤 작업 유형을 담당하는지. 사용 가능한 MCP 연결과 그 용도. 에이전트가 정말로 스스로 알아낼 수 없는 최소한의 핵심 저장소 정보, 그리고 그것뿐.

레이어 2: 집중된 페르소나/스킬 파일 작업 유형에 따라 선택적으로 불러옵니다. 컴포넌트 아키텍처를 작업하는 UX 중심 에이전트는 데이터 파이프라인을 디버깅하는 백엔드 에이전트와 다른 컨텍스트를 읽습니다. 서로 상대방의 컨텍스트는 불러오지 않습니다. 어떤 작업에서든 총 컨텍스트 크기는 제한 범위 안에 유지됩니다.

레이어 3: 유지보수 서브에이전트 코드베이스가 발전함에 따라 프로토콜 파일의 정확성을 유지하는 것이 유일한 역할입니다. 아무도 잘 언급하지 않는 사실이 있습니다. 문서는 썩습니다. ETH 취리히 연구는 갓 생성된 컨텍스트 파일을 사용했는데도 성능 저하를 발견했습니다. 6개월째 손대지 않은 AGENTS.md, 이미 교체된 의존성이나 바뀐 디렉터리 구조를 설명하는 파일은 훨씬 더 나쁜 결과를 낼 것입니다.

주요 코딩 에이전트 중 이 아키텍처를 쉽게 구축할 수 있는 라이프사이클 훅을 제공하는 것은 아직 없습니다. 서브에이전트와 범위가 제한된 컨텍스트로 어느 정도 비슷하게 만들 수 있지만, 깔끔한 해법은 아직 없습니다. 채워지길 기다리는 도구 공백입니다.

자동화된 최적화라는 관점

이 분야에서 가장 도발적인 발견은 Arize AI의 프롬프트 학습 연구에서 나왔습니다. CLAUDE.md 지침을 수동으로 작성하는 대신, 자동화된 최적화 루프를 활용했습니다. 학습 작업에 에이전트를 실행하고, 출력물을 평가하고, 왜 해결책이 실패했는지에 대한 LLM 피드백을 생성하고, 메타 프롬프팅으로 지침을 개선합니다. 이를 반복합니다.

결과: 크로스 저장소 테스트 분할에서 정확도 5.19% 향상, 인-저장소 분할(과거 Django 이슈로 학습, 미래 이슈로 테스트)에서 10.87% 향상이었습니다.

최적화 과정에서 드러난 불편한 함의가 있습니다. 사람이 코드베이스를 이해하는 데 도움이 되는 것과 LLM이 코드베이스를 탐색하는 데 도움이 되는 것은 종종 다릅니다. 당신에게 분명히 유용해 보이는 지침, 예를 들어 "이 서비스는 저장소 패턴을 사용한다"는 모델에게는 노이즈일 수 있습니다. 반면 모델이 실제로 필요로 하는 것, 특정 임포트 경로 명확화나 직관적이지 않은 파일 명명 관례 같은 것들은 이미 몸에 익어버린 탓에 적어야겠다는 생각조차 들지 않을 수 있습니다.

AGENTS.md를 수동으로 작성하는 방식은 당신이 에이전트에게 무엇이 필요한지 안다고 전제합니다. 하지만 경험적 증거는 그렇지 않을 가능성이 높다고 말합니다. 최적화 도구는 당신이 중요하다고 생각하는 것과 실제로 차이를 만드는 것 사이의 간극을 찾아냅니다.

이것이 컨텍스트 파일 작성을 포기하라는 뜻은 아닙니다. 자동화된 최적화 연구는 아직 초기 단계이고, 5%는 의미 있지만 혁신적이지는 않습니다. 다만 무엇을 포함할지에 대한 직관을 가볍게 쥐고, 실제로 검증해볼 필요가 있다는 뜻입니다.

AGENTS.md를 대하는 올바른 마음가짐

AGENTS.md를 아직 해결하지 못한 마찰을 기록하는 살아있는 문서로 생각하세요.

추가하는 줄 하나하나는 AI 에이전트를 헷갈리게 만들 만큼 혼란스러운 코드베이스의 무언가를 가리키는 신호입니다. 그 말인즉슨, 새로 합류한 사람 개발자도 똑같이 헷갈릴 수 있다는 뜻입니다. 그 신호에 대한 올바른 반응은 컨텍스트 파일을 키우는 것이 아니라, 실제 문제를 고치는 것입니다.

에이전트가 새 유틸리티를 자꾸 엉뚱한 디렉터리에 넣나요? 디렉터리 구조가 혼란스러워서 재정리가 필요한 걸 수도 있습니다. 에이전트가 deprecated된 의존성을 계속 집어드나요? 임포트 구조 때문에 잘못된 것을 더 쉽게 선택하게 되는 건 아닌지 살펴보세요. 에이전트가 타입 검사 실행을 자꾸 잊나요? 문서로 지시하는 대신 빌드 파이프라인에서 자동으로 잡게 만드는 게 낫지 않을까요?

AGENTS.md는 영구적인 설정이 아니라 진단 도구가 됩니다. 줄을 추가하고, 에이전트가 이 실수를 반복하는 이유를 파악하고, 근본 원인을 고치면, 그 줄은 삭제해도 됩니다.

한번 시도해볼 만한 방법이 있습니다. AGENTS.md를 거의 비운 채로 시작하고, 딱 하나의 지침만 추가합니다. "이 프로젝트에서 놀랍거나 혼란스러운 것을 발견하면 코멘트로 표시하세요." 에이전트가 제안하는 추가 내용의 대부분은 영구적으로 남겨야 할 것이 아니라, 코드베이스가 불명확한 지점을 가리키는 지표입니다. 그 지점들을 고치세요. 파일은 최소한으로 유지하세요.

연구가 해결하지 못한 것들

두 논문 모두 짚어두어야 할 실질적인 한계가 있습니다.

Lulla 논문은 정확도를 전혀 측정하지 않고 효율성만 측정했습니다. 이 논문만으로 AGENTS.md가 결과물의 품질을 향상시킨다는 결론을 내릴 수 없습니다. 저자들도 이 점을 명확히 밝히고 있습니다. 에이전트가 의미 있는 결과를 냈는지 확인하는 정도의 검증만 했을 뿐, 완전한 정확도 평가는 향후 과제로 남겨두었습니다. 더 빠르고 저렴한 것은 의미 있지만, 코드가 틀렸다면 아무 소용이 없습니다.

ETH 취리히 논문은 갓 생성된 컨텍스트 파일을 사용했는데, 실험 통제 측면에서는 이상적이지만 대부분의 개발자가 실제로 겪는 상황과는 다릅니다. 현실에서는 몇 달째 저장소에 방치되어 일부 내용이 구식이 된 컨텍스트 파일을 마주하게 됩니다. 그런 파일은 논문에서 측정한 것보다 훨씬 나쁜 결과를 낼 것입니다.

두 논문 모두 여러 실무자들이 올바른 아키텍처라고 주장하는 계층적·동적 로딩 방식은 테스트하지 않았습니다. 평가 대상은 오직 "단일 파일 컨텍스트" 방식뿐입니다. 선택적 컨텍스트 로딩을 갖춘 제대로 된 계층 구조 시스템이 다르게 작동할지는 아직 열린 경험적 질문입니다.

모델 발전 속도의 문제도 있습니다. 개발자들은 몇 달마다 기반 모델이 코드베이스 탐색을 더 잘하게 되면서 컨텍스트 파일에 넣는 내용이 줄었다고 말합니다. 6개월 전에는 필수였던 지침이 모델이 발전하면서 군더더기가 됩니다. 오늘 작성하는 AGENTS.md가 다음 분기에는 순수한 오버헤드가 될 수 있습니다.

실용적인 결론

/init 실행을 그만두세요. 저장소에 문서가 전혀 없는 경우라면 없는 것보다는 조금 낫겠지만, 자동 생성된 결과물은 이미 있는 문서와 중복되고 아무 이득 없이 오버헤드만 추가합니다.

AGENTS.md에 줄을 추가하기 전에 먼저 물어보세요. 에이전트가 코드를 읽으면서 이걸 찾아낼 수 있는가? 그렇다면 쓰지 마세요.

에이전트가 무언가를 반복적으로 실수할 때, 컨텍스트 문제로 보기 전에 코드베이스 문제로 접근하세요. 코드를 재구성하거나, 린터 규칙을 추가하거나, 테스트 커버리지를 높이세요. 그 선택지를 모두 소진한 다음에야 AGENTS.md를 꺼내드세요.

CI/CD나 자동화된 리뷰 파이프라인에서 에이전트를 대규모로 실행하고 있다면, 컨텍스트 파일로 인한 15~20%의 비용 오버헤드가 수천 번의 실행에 걸쳐 누적됩니다. 그 트레이드오프가 가치 있다고 가정하기 전에 직접 계산해보세요.

파일이 썩도록 방치하는 대신, 컨텍스트 파일의 정확성을 유지하는 것만을 담당하는 유지보수 에이전트를 구축하는 것을 고려해보세요.

그리고 에이전트에게 무엇이 필요한지에 대한 직관을 가볍게 쥐세요. 당신에게 분명히 유용해 보이는 것이 모델에게는 노이즈일 수 있습니다. 경험적 증거에 따르면, 우리가 에이전트에게 필요하다고 생각하는 것과 실제로 도움이 되는 것 사이의 간극은 상당하고, 아마도 우리가 예상하는 방향과 반대일 것입니다.

코딩 에이전트를 신입 개발자처럼 온보딩하려는 본능, 즉 사무실 투어를 시켜주고, 조직도를 설명하고, 아키텍처를 안내하려는 마음은 충분히 이해할 수 있습니다. 하지만 코딩 에이전트는 신입 사원이 아닙니다. 당신이 프롬프트를 다 입력하기도 전에 전체 코드베이스를 grep할 수 있습니다. 에이전트에게 필요한 건 지도가 아닙니다. 지뢰가 어디에 있는지입니다.

그리고 점점 더, 그것조차 필요 없어질지 모릅니다.

영상으로 보고 싶다면, 이 주제에 대한 Theo의 영상도 훌륭합니다.

You should delete your CLAUDE․md/AGENTS․md file. I have a study to prove it. pic.twitter.com/jOUNE53y7m
— Theo - t3.gg (@theo) February 23, 2026

Matt Pocock의 영상도 마찬가지입니다:

Never run claude /init

It'll burn tokens, go out of date in days, and bloat your system prompt.

Here's why: pic.twitter.com/mVi7VIb84j
— Matt Pocock (@mattpocockuk) February 24, 2026