/init으로 AGENTS.md 자동 생성하지 마라 - 오히려 비용만 20% 늘어남

핵심 주장

• AI 코딩 에이전트용 컨텍스트 파일(AGENTS.md)을 /init 명령으로 자동 생성하면, 에이전트 성능이 오히려 떨어지고 비용이 20% 이상 증가함
• 에이전트가 스스로 발견할 수 있는 정보를 중복으로 제공하는 것이 문제의 핵심
• AGENTS.md에는 에이전트가 코드를 읽어서는 알 수 없는 정보만 넣어야 함

연구 결과: AGENTS.md는 도움이 되나, 해가 되나

• Lulla et al. (ICSE JAWs 2026): GitHub PR 124개를 대상으로 AGENTS.md 유무만 바꿔 비교하는 페어드 실험
  • AGENTS.md가 있을 때 실행 시간 28.64% 감소, 출력 토큰 16.58% 감소
  • 이 연구에서 사용된 파일은 개발자가 실제로 유지보수하던 것으로, 프로젝트 고유의 지식이 담겨 있었음
• ETH Zurich 연구: 4개 에이전트를 SWE-bench 등에서 테스트하되, LLM 자동 생성 파일과 개발자 작성 파일을 구분
  • LLM이 자동 생성한 컨텍스트: 작업 성공률 2~3% 하락, 비용 20%+ 증가
    • README 등 기존 문서를 전부 제거한 환경에서는 LLM 생성 파일이 오히려 성능을 2.7% 끌어올림
  • 개발자가 직접 작성한 파일: 성공률 약 4% 향상, 비용 최대 19% 증가
• 결론: 자동 생성 내용이 나쁜 게 아니라 중복이 문제임
  • 같은 정보를 두 번 주면 노이즈만 추가되고, 개발자가 작성한 발견 불가능한 지식만이 실질적 도움이 됨

왜 자동 생성이 해로운가

• 자동 생성된 AGENTS.md는 대부분 에이전트가 이미 스스로 발견하는 정보를 포함함
  • 코드베이스 개요 (Sonnet 4.5 출력의 100%, GPT-5.2 출력의 99%가 이를 포함)
  • 디렉토리 구조, 기술 스택, 모듈 설명
• 이미 알고 있는 정보를 다시 제공하면 토큰만 소비하고 가치가 없음
• 앵커링 효과: 레거시 패턴을 언급하면, 더 좋은 대안이 있어도 에이전트가 그 패턴에 고착됨
  • "Lost in the Middle" 연구(Liu et al., 2024)와 일치 — 긴 컨텍스트는 주의력을 분산시켜 성능을 떨어뜨림

AGENTS.md에 넣어야 할 것 vs 넣지 말아야 할 것

• 넣어야 할 것 (에이전트가 발견 불가능한 정보)
  • 도구 지정: "uv를 패키지 관리에 사용할 것"
  • 비직관적 규칙: "테스트는 반드시 --no-cache로 실행, 안 하면 fixture가 false positive 발생"
  • 시스템 제약: "auth 모듈은 커스텀 미들웨어 사용 중, 표준 Express로 리팩토링 금지"
  • 도구가 문서에 언급되면 에이전트가 작업당 1.6~2.5회 사용하지만, 미문서화 시 0.05회 미만으로 급감함
• 넣지 말아야 할 것 (에이전트가 스스로 발견 가능)
  • 디렉토리 구조, 모노레포 레이아웃
  • 기술 스택 개요, 표준 아키텍처 패턴

정적 파일의 구조적 한계

• 잘 작성된 AGENTS.md라도 근본적 약점이 있음 — 파일은 정적인데 작업은 동적임
• 단일 파일의 지시는 작업 유형에 따라 조건 분기할 수 없음
  • 문서 수정 작업에도 "커밋 전 전체 테스트 실행" 지시가 적용되어 토큰과 시간이 낭비됨
  • CSS 리팩토링에 DB 마이그레이션 경고가 로드되고, 보안 수정에 성능 최적화 힌트가 딸려옴
• ACE 프레임워크(ICLR 2026): 정적 파일 대신 generator/reflector/curator 파이프라인으로 컨텍스트를 동적으로 진화시키는 Agentic Context Engineering 접근법이 정적 방법 대비 12.3% 높은 성능을 기록함

더 나은 구조, 아직 만들어지지 않은

• AGENTS.md와 관련하여 여러 사람이 독립적으로 같은 결론에 도달함
  • 단일 파일이 아니라 라우팅 계층 + 필요 시 로드되는 집중 컨텍스트가 올바른 구조임
• Layer 1 - 프로토콜 파일: 코드베이스 개요나 스타일 가이드가 아닌 라우팅 문서
  • 사용 가능한 페르소나와 호출 조건, 스킬과 담당 작업 유형, MCP 연결과 용도를 정의
  • 에이전트가 발견할 수 없는 최소한의 레포 사실만 포함하고 그 외에는 아무것도 넣지 않음
• Layer 2 - 페르소나/스킬 파일: 작업 유형에 따라 선택적으로 로드됨
  • UX 에이전트와 백엔드 에이전트가 서로 다른 컨텍스트를 로드하고, 상대방의 컨텍스트는 로드하지 않음
• Layer 3 - 유지보수 서브에이전트: 프로토콜 파일의 정확성을 유지하는 전담 에이전트
  • 문서는 부패함 — ETH Zurich 연구도 갓 생성된 파일로 테스트했는데도 성능 하락이 나타남
  • 6개월간 방치된 AGENTS.md가 이미 교체된 의존성이나 변경된 디렉토리 구조를 기술하고 있다면 훨씬 심각함
• 현재 주요 코딩 에이전트 중 이 아키텍처를 쉽게 구현할 라이프사이클 훅을 제공하는 것은 없음 — 서브에이전트와 스코프드 컨텍스트로 근사할 수는 있지만, 아직 채워지지 않은 도구 공백임

자동 최적화

• Arize AI는 CLAUDE.md 지시문을 수동으로 작성하는 대신 자동 최적화 루프를 사용함
  • 에이전트를 학습용 작업에 실행 → 결과 평가 → 실패 원인에 대한 LLM 피드백 생성 → 메타프롬프팅으로 지시문 개선 → 반복
  • cross-repo 테스트에서 +5.19%, in-repo 테스트에서 +10.87% 정확도 향상
• 옵티마이저가 밝힌 불편한 사실: 사람이 코드베이스를 이해하는 데 도움이 되는 것과 LLM이 탐색에 필요한 것은 다름
  • "이 서비스는 repository 패턴 사용" 같은 정보는 개발자에게 당연히 유용해 보이지만 모델에게는 노이즈일 수 있음
  • 반대로 모델이 실제로 필요한 것(특정 import 경로 구분, 비직관적 파일 명명 규칙 등)은 개발자가 내재화해서 적을 생각조차 못 함
• AGENTS.md 수동 작성은 개발자가 에이전트에게 필요한 것을 안다고 가정함
  • 경험적 증거는 아마 모른다고 시사함
  • 옵티마이저는 "중요하다고 생각하는 것"과 "실제로 결과를 바꾸는 것" 사이의 차이를 찾아냄
• 그렇다고 작성을 포기하라는 뜻은 아님 — 5%는 의미 있지만 변혁적이지는 않음. 직관을 느슨하게 잡고 실제로 테스트하라는 뜻

AGENTS.md를 바라보는 올바른 마인드셋

• AGENTS.md를 아직 고치지 못한 과정의 기록으로 볼 것
• 추가하는 모든 줄은 코드베이스에서 AI 에이전트를 혼란시킬 만큼 불명확한 부분이 있다는 신호이며, 이는 새로운 인간 기여자도 마찬가지로 헤맬 가능성이 높음
• 올바른 대응은 컨텍스트 파일을 키우는 것이 아니라 근본 원인을 수정하는 것
  • 에이전트가 유틸리티를 엉뚱한 디렉토리에 넣음 → 디렉토리 구조 자체가 혼란스러운 것이므로 재편할 것
  • 에이전트가 폐기된 의존성을 계속 사용함 → import 구조가 잘못된 것을 너무 쉽게 잡게 만드는 것이므로 수정할 것
  • 에이전트가 타입 검사를 빠뜨림 → 지시에 의존하지 말고 빌드 파이프라인에서 자동으로 잡을 것
• AGENTS.md는 영구 설정이 아니라 진단 도구임 — 줄을 추가하고, 에이전트가 왜 이 실수를 반복하는지 조사하고, 근본 원인을 고친 뒤, 그 줄을 삭제함
• 시도해볼 기법: AGENTS.md를 거의 비운 채 시작하고 "이 프로젝트에서 놀랍거나 혼란스러운 것을 발견하면 코멘트로 남겨라"는 지시 하나만 넣을 것. 에이전트가 제안하는 추가 사항 대부분은 영구 보관할 것이 아니라 코드베이스가 불명확한 지점의 표지임

실용적 권장사항

• /init 실행을 중단할 것 — 레포에 문서가 아예 없는 경우가 아니라면 자동 생성 결과물은 기존 문서와 중복됨
• AGENTS.md에 한 줄을 추가하기 전에 "에이전트가 코드를 읽으면 알 수 있는가?" 자문할 것. 그렇다면 적지 말 것
• 에이전트가 반복적으로 실패할 때 컨텍스트 파일을 키우기 전에 코드베이스 자체를 먼저 수정할 것
  • 코드 구조를 개선하고, 린터 규칙을 추가하고, 테스트 커버리지를 확대한 뒤 — 그래도 안 될 때만 AGENTS.md에 손을 댈 것
• CI/CD나 자동 리뷰 파이프라인에서 에이전트를 대규모로 운용한다면, 15~20% 비용 오버헤드가 수천 회 실행에 걸쳐 복리로 누적됨을 인식할 것
• 에이전트를 신입 사원처럼 온보딩하려는 본능(사무실 투어, 조직도, 아키텍처 설명)은 자연스럽지만, 코딩 에이전트는 신입이 아님 — 프롬프트를 다 입력하기도 전에 코드베이스 전체를 grep할 수 있음. 에이전트에게 필요한 건 지도가 아니라 지뢰의 위치임