ETH Zurich 연구 vs 커뮤니티 반응 : CLAUDE.md(AGENTS.md) 쓰면 비용만 낭비된다? 자동 생성하면 오히려 성공률이 떨어진다?

안녕하세요! 갓대희 입니다.

오늘은 최근 개발자 커뮤니티에서 뜨거운 감자가 된 주제인 AGENTS.md와 CLAUDE.md의 올바른 작성법에 대해 알아보려고 한다. "자동 생성하면 안 된다"는 주장도 있고, "그래도 도움이 된다"는 주장도 있다. 과연 진실은 무엇일까?

 

연구 데이터와 커뮤니티 피드백을 바탕으로, 이 파일들이 정말 필요한지, 그렇다면 어떻게 작성해야 하는지 함께 살펴보자.

이런 분들에게 도움이 됩니다

• Claude Code, Cursor, Codex 등 AI 코딩 에이전트를 사용하는 개발자
• /init으로 AGENTS.md를 자동 생성해서 사용하고 있는 분
• 에이전트의 코드 생성 품질을 높이고 싶은 분
• AI 에이전트 사용 시 토큰 비용을 최적화하고 싶은 분
• 팀 단위로 AI 코딩 에이전트를 도입하려는 기술 리더

이 글의 출처

이 글은 Addy Osmani의 "Stop Using /init for AGENTS.md"(2026-02-23)와 GeekNews 토론을 주요 출처로 한다.

ETH Zurich(arXiv:2602.11988)와 Lulla et al.(arXiv:2601.20404)의 학술 연구 결과를 종합하여 작성했으며, 인용된 수치는 모두 해당 원문에서 참조하였다.

목차

1. 들어가며 — AGENTS.md 논쟁의 시작
2. AGENTS.md와 CLAUDE.md란 무엇인가
   • 정의와 역할
   • 사용 사례
3. 자동 생성의 함정 — 연구가 말하는 것
   • ETH Zurich 연구 결과
   • 성능 저하 원인
   • "Lost in the Middle" 효과
   • 앵커링 효과
4. 올바른 작성이 중요한 이유
   • Lulla et al. 연구 분석
   • 토큰 효율성과 실행 속도
   • 사람의 직관 vs LLM의 실제 필요
5. 커뮤니티 반응 — 찬성과 반박
   • Addy Osmani의 주장
   • GeekNews 커뮤니티 의견
6. 포함해야 할 것 vs 제외해야 할 것
   • 포함 기준
   • 제외 기준
7. 실전 예시 — 좋은 AGENTS.md vs 나쁜 AGENTS.md
   • 안티패턴
   • 권장 패턴
8. 시간이 지나면 생기는 문제 — 문서 부패(Documentation Rot)
   • 단일 정적 파일의 한계
   • 문서 부패의 악순환
9. 파일 관리 전략 — 최신 상태 유지법
   • 자동 생성 회피
   • 수동 유지보수
10. CLAUDE.md와의 구분
11. 결론 및 핵심 요약
    • 진단 도구로서의 AGENTS.md

AGENTS.md 제대로 쓰기 가이드
AGENTS.md는 단순한 자동 생성 파일이 아니다. 에이전트가 직접 발견할 수 없는 정보만 담고, 중복을 철저히 제거할 때만 가치를 발휘한다.
이 가이드는 연구 데이터와 실전 사례를 바탕으로, AGENTS.md와 CLAUDE.md를 올바르게 작성하고 관리하는 방법을 제시한다. 

 

1. 들어가며 — AGENTS.md 논쟁의 시작

최근 Claude Code 사용자들 사이에서 논쟁이 일고 있다. AGENTS.md와 CLAUDE.md는 정말 필요한가? 자동 생성해도 되는가?

이 질문이 핵심이 된 계기는 2026년 2월에 공개된 ETH Zurich의 연구 결과였다. 연구팀은 438개 이상의 대규모 벤치마크 태스크를 분석했고, 충격적인 결론에 도달했다.

• 자동 생성 AGENTS.md는 작업 성공률을 0.5~2% 감소시키고(SWE-bench Lite 0.5%, AGENTbench 2%), 비용을 20% 이상 증가시킨다
• 개발자가 직접 작성한 AGENTS.md는 성공률을 4% 향상시킨다.

왜 이 차이가 생기는가?

자동 생성 AGENTS.md는 저장소에서 이미 발견 가능한 정보(디렉토리 구조, 기술 스택, 패키지 목록)를 중복으로 포함한다. 이는 에이전트의 컨텍스트 윈도우를 낭비하고, 토큰 소비를 증가시키며, 중요한 정보를 묻어버린다.

하지만 잘 작성된 AGENTS.md는 다르다. 에이전트가 스스로 발견할 수 없는 정보만 담으면, 실행 시간이 28.64% 단축되고 토큰 소비가 16.58% 감소한다는 것이 증명되었다고 한다.(Lulla et al., ICSE JAWs 2026).

 

2. AGENTS.md와 CLAUDE.md란 무엇인가

정의와 역할

AGENTS.md는 에이전트(AI 코딩 도구)를 위해 저장소 루트에 배치되는 구조화된 컨텍스트 파일이다. Claude Code, GitHub Copilot, 기타 AI 도구가 이 파일을 읽고 프로젝트의 특성을 빠르게 파악한다.

 

CLAUDE.md는 에이전트와 개발자 모두를 위한 프로젝트 지침 파일로, 더 광범위한 컨텍스트를 담을 수 있다. 개발 규칙, 아키텍처 결정, 주의사항 등이 포함된다.

도구마다 이름이 다르지만 역할은 동일하다. 아래 표는 주요 AI 코딩 도구의 컨텍스트 파일을 정리한 것이다.

도구	컨텍스트 파일	설명
Claude Code	CLAUDE.md	세션 시작 시 자동으로 컨텍스트에 로드됨
Cursor	.cursorrules (구버전) 또는 .cursor/rules/ (신버전)	프로젝트 규칙 및 코딩 컨벤션 전달
Codex	AGENTS.md	에이전트 지시사항 및 프로젝트 맥락
범용	AGENTS.md	여러 도구에서 사실상 표준(de facto standard)으로 자리잡아가는 이름

 

사용 사례

실제 동작 방식

에이전트는 저장소에 접근할 때 루트 → 리프 순서로 파일을 읽는다. 즉, AGENTS.md는 가장 먼저 로드되어, 에이전트의 초기 전략을 결정한다.
OpenAI Codex 기준으로 기본 최대 크기는 32 KiB이다(project_doc_max_bytes).

도구마다 컨텍스트 파일을 처리하는 방식이 조금씩 다르다. 이를 이해하면 왜 "가벼운 파일"이 중요한지 더 잘 알 수 있다.

도구	로드 시점	비용 영향
Claude Code	세션 시작 시 CLAUDE.md를 컨텍스트에 자동 주입	매 API 호출마다 입력 토큰에 포함
Cursor	.cursorrules를 에이전트 모드 시 컨텍스트에 포함	모든 에이전트 호출에 포함
Codex	AGENTS.md를 작업 시작 전 로드	작업 전체 기간 동안 컨텍스트 차지

파일이 매번 로드된다는 점이 핵심이다. 파일이 500토큰이면 모든 호출에서 500토큰이 추가된다. 하루에 에이전트를 100번 호출한다면 50,000토큰의 추가 비용이 된다. Anthropic 공식 문서는 CLAUDE.md를 200줄 이하로 유지할 것을 권장한다.

AGENTS.md와 README의 역할을 혼동하는 경우가 많은데, 명확한 차이가 있다:

• README: 인간을 위한 프로젝트 설명 (기능, 설치법, 사용법)
• AGENTS.md: 에이전트를 위한 지침 (에이전트가 모르는 정보만)

 

3. 자동 생성의 함정 — 연구가 말하는 것

ETH Zurich 연구 (2026.02)

ETH Zurich SRI Lab 연구팀(Gloaguen et al.)이 발표한 논문 "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?"는 명확한 답변을 제시한다.

구분	작업 성공률	비용 변화	평가
자동 생성 AGENTS.md	-0.5~2% ↓	+20% ↑	비추천
개발자 작성 AGENTS.md	+4% ↑	성공률 향상, 비용은 최대 +19% ↑ (가능) ※ Claude Code 제외 시 유효 — Claude Code는 효과 미확인	권장

 

성능 저하 원인

자동 생성 AGENTS.md가 성능을 저해하는 이유는 명확하다:

• 중복 정보: 디렉토리 구조는 에이전트가 `ls -R` 명령어로 직접 탐색 가능
• 패키지 목록: package.json, requirements.txt, uv.lock 등에서 직접 파싱 가능
• 기술 스택: 코드를 읽으면 사용 기술이 명백함
• 컨텍스트 낭비: 이미 알 수 있는 정보가 토큰을 소비하면서, 실제 중요한 지침의 우선순위가 낮아짐

 

"Lost in the Middle" 효과

Liu et al.(2023)의 "Lost in the Middle" 연구에 따르면, LLM은 긴 컨텍스트에서 중간에 위치한 정보를 놓치는 경향이 있다. 컨텍스트의 처음과 끝은 잘 기억하지만, 중간 부분은 주의력이 분산된다.

컨텍스트 윈도우 내 주의력 분포:

[AGENTS.md 시작]  ████████████  <-- 높은 주의력
[중간 부분]       ██████        <-- 주의력 저하 (Lost in the Middle)
[실제 작업 지시]  ████████████  <-- 높은 주의력

문제: AGENTS.md가 길수록 실제 작업에 대한 주의력 총량이 줄어듦

AGENTS.md에 불필요한 정보를 많이 담을수록 정작 중요한 작업 지시에 대한 에이전트의 집중력이 떨어진다.

Addy Osmani의 표현을 빌리면: "AGENTS.md의 모든 줄은 에이전트에게 실제로 요청한 작업과 경쟁한다(Every line in AGENTS.md is a line competing with the thing you actually asked the agent to do)."

 

앵커링 효과 (Anchoring Effect)

자동 생성의 가장 위험한 부작용이다. AGENTS.md에 특정 기술이나 패턴이 언급되면, 에이전트는 그 정보에 편향(bias)되어 모든 작업에서 해당 패턴을 선호하게 된다.

앵커링 효과 예시

• AGENTS.md에 "Legacy module: auth-v1 (Express middleware)"가 적혀 있음
• 에이전트가 새로운 API 엔드포인트를 만들 때, 최신 패턴 대신 레거시 Express 미들웨어 패턴을 사용하려 함
• 결과: 새로운 코드가 레거시 패턴을 따라가는 역행(regression) 발생

자동 생성은 프로젝트의 모든 것을 설명하려 하기 때문에, 레거시 코드도 현재 코드와 동등하게 기술한다. 에이전트는 어느 것이 권장 패턴이고 어느 것이 더 이상 사용하지 말아야 하는지 구분하지 못하게 된다.

 

ETH Zurich 연구의 한계와 의의

ETH Zurich의 결론은 "컨텍스트 파일 자체가 항상 도움이 되진 않는다"는 부정적 결론이다.

즉, 무조건 AGENTS.md를 작성하면 효과가 있는 것은 아니라는 뜻이다. 하지만 이는 자동 생성된 파일에 대한 결론이며, 전략적으로 작성된 파일에 대해서는 다른 연구(Lulla et al.)가 긍정적 결과를 보여주고 있다.

연구 결과에서의 결론: /init 자동 생성 금지

최신 도구들이 제공하는 "AGENTS.md 자동 생성" 기능은 피해야 한다. 이는 성공률을 떨어뜨리고 비용을 증가시킬 뿐이다. 하지만 전략적으로 작성된 AGENTS.md는 실제로 성능을 향상시킨다.

 

4. 올바른 작성이 중요한 이유

Lulla et al. 연구 분석 (ICSE JAWs 2026)

하지만 AGENTS.md 자체를 버릴 필요는 없다. 올바르게 작성된 AGENTS.md는 효율을 크게 향상시킨다. Lulla 등이 10개 저장소에서 124개 PR을 대상으로 AGENTS.md 유무에 따른 성능을 비교한 결과는 다음과 같다(arXiv:2601.20404, ICSE JAWs 2026 제출):

메트릭	개선율	의의
실행 시간	28.64% 단축	더 빠른 피드백 루프
토큰 소비	16.58% 감소	API 비용 절감
작업 성공률	유사한 수준 유지	논문 원문: "comparable task completion behavior"

 

토큰 효율성의 실전 사례

ETH Zurich 연구에서 확인된 수치를 Addy Osmani가 다음과 같이 정리했다. 패키지 매니저 언급의 효과는 다음과 같다:

• AGENTS.md에 "uv 사용"이라고 명시: 작업당 1.6회 사용
• 언급하지 않음: 작업당 0.01회 이하 사용

핵심 통찰

발견 불가능한 정보만 가치가 있다. 에이전트가 자동으로 발견할 수 있는 정보(디렉토리, 기술 스택)는 AGENTS.md에 포함될 필요가 없다. 하지만 "uv를 사용해야 한다"는 지침은 발견 불가능한 정보이므로, 명시하면 에이전트의 행동이 크게 변한다.

 

사람의 직관 vs LLM의 실제 필요

Arize AI의 Prompt Learning 실험(Cross-repo +5.19%, In-repo +10.87% 정확도 향상)은 중요한 사실을 밝혀냈다. 사람이 코드베이스 이해에 도움이 된다고 생각하는 정보와, LLM이 실제로 필요한 정보는 다르다. 이 차이가 AGENTS.md 작성에서 가장 흔한 실수의 근원이다.

사람이 유용하다고 생각하는 정보	LLM이 실제로 필요한 정보
"이 프로젝트는 Next.js 14를 사용합니다"	"App Router에서 use client를 빼먹으면 빌드 에러가 나지 않고 런타임에서 조용히 실패합니다"
"데이터베이스는 PostgreSQL 15입니다"	"uuid_generate_v4()를 사용하려면 CREATE EXTENSION pgcrypto가 필요합니다. 마이그레이션에 포함되어 있으니 새 확장 추가하지 마세요"
"src/components에 UI 컴포넌트가 있습니다"	"Button 컴포넌트는 cva(class-variance-authority)를 사용합니다. 새 variant 추가 시 기존 패턴을 따르세요"
"테스트는 Jest를 사용합니다"	"msw mock은 src/mocks/handlers.ts에 중앙 집중화되어 있습니다. 개별 테스트 파일에서 직접 mock하지 마세요"
"API 엔드포인트는 /api/v2/ 아래 있습니다"	"인증이 필요한 엔드포인트는 withAuth 미들웨어를 반드시 사용하세요. 직접 JWT 검증 로직을 작성하지 마세요"

왼쪽은 "무엇이 있는가(what)"에 대한 답이고, 오른쪽은 "어디서 실수하기 쉬운가(where are the traps)"에 대한 답이다. 에이전트는 "what"은 코드를 읽으면 스스로 파악할 수 있지만, "traps"는 코드만 봐서는 알 수 없다.

Arize AI의 교훈

"사람의 직관으로 AGENTS.md를 채우지 마라. 에이전트가 실제로 실수하는 지점을 관찰하고, 그 지점에 대한 정보만 담아라."

 

ACE 프레임워크: 동적 컨텍스트 로딩

2026년 ICLR에서 발표된 ACE(Agentic Context Engineering) 프레임워크는 한 단계 더 나아간 접근을 제시한다. 기존 정적 프롬프트(ICL) 방식 대비 에이전트 벤치마크에서 10.6% 성능 향상을 달성했다. ACE의 핵심은 동적 컨텍스트 로딩이다: 작업 유형에 따라 필요한 컨텍스트만 동적으로 제공하는 방식이다. 이는 AGENTS.md 작성의 미래 방향을 시사한다.

 

5. 커뮤니티 반응 — 찬성과 반박

Addy Osmani의 주장

구글 소프트웨어 엔지니어 Addy Osmani(Google Cloud & Gemini 담당)는 자신의 블로그에서 명확한 가이드라인을 제시했다.

AGENTS.md에 포함해야 할 것

• 비직관적 도구/명령어 (예: pip 대신 uv 필수)
• 테스트 실행 시 필수 플래그 (예: --no-cache)
• 레거시 코드 삭제 금지 목록
• 에이전트가 반복 실수하는 패턴 방지 지침

AGENTS.md에 포함하면 안 될 것

• 디렉토리 구조 (에이전트가 직접 탐색 가능)
• 기술 스택 목록 (package.json, requirements.txt 보면 앎)
• README와 동일한 내용
• 너무 긴 일반적 코딩 스타일 가이드

 

GeekNews 커뮤니티 의견

한국 개발자 커뮤니티(GeekNews, Hada.io)에서도 활발한 토론이 있었다.

 

찬성 의견

• "사람과 LLM의 파싱 구조는 완전히 다르다": 자동 생성 파일은 할루시네이션만 심해짐
• "토큰 효율성이 핵심": 중복 정보 제거가 성능 향상의 핵심

 

회의적 의견

• armila: "모델이 수개월마다 바뀌는데 AGENTS.md 최적화보다 모델 변화가 더 빠르다"
• jaehar16: "기존 README가 이미 있지 않냐"
• sonnet: "AGENTS.md는 기존 README의 에이전트용 재편성일 뿐"

armila의 의견에 대한 반론

모델이 빠르게 변한다는 지적은 타당하지만, "에이전트가 발견할 수 없는 정보만 포함한다"는 핵심 원칙은 모델에 무관하게 유효하다. ETH Zurich 연구도 Claude Code, Codex, Qwen Code 등 여러 모델을 테스트했고, 결론은 일관되었다.

즉, 어떤 모델을 사용하든 중복 정보는 성능을 저해한다.

종합 평가

모든 의견을 종합하면, AGENTS.md 자체는 필요하지만, 어떻게 작성하느냐가 중요하다는 데 동의한다.

자동 생성은 피하되, 전략적으로 작성하면 실제로 성능을 향상시킬 수 있다.

 

6. 포함해야 할 것 vs 제외해야 할 것

의사결정 트리

다음 질문에 답하면 어떤 정보를 포함할지 명확해진다.

Q1: 에이전트가 자동으로 발견할 수 있는가?

• Yes (디렉토리 구조, 패키지 목록) → 제외
• No (비직관적 도구, 특수 플래그) → 포함

Q2: 에이전트가 반복적으로 실수하는가?

• Yes → 포함 (방지 지침 작성)
• No → 필수는 아님

Q3: README에 이미 있는가?

• Yes → 제외 (중복 피하기)
• No → 포함 고려

 

구체적 포함/제외 예시

정보	포함?	이유
디렉토리 구조	제외	ls -R로 직접 탐색 가능
사용 언어 (Python 3.11)	제외	requirements.txt, pyproject.toml에서 명백
"uv를 사용해야 함"	포함	비직관적, 테스트 결과 기준
테스트: --no-cache 필수	포함	특수 플래그, 에이전트 실수 예방
/legacy 디렉토리 삭제 금지	포함	중요한 제약 사항
설치 방법	제외	README에 충분히 설명

 

7. 실전 예시 — 좋은 AGENTS.md vs 나쁜 AGENTS.md

나쁜 예 : 자동 생성 AGENTS.md

# Project Structure
.
├── src/
│   ├── main.py
│   ├── utils.py
│   └── config.py
├── tests/
├── docs/
└── README.md

# Technology Stack
- Language: Python 3.11
- Framework: FastAPI
- Database: PostgreSQL
- Testing: pytest
- Package Manager: pip

# Main Components
- src/main.py: Main application entry point
- src/utils.py: Utility functions
- tests/: Test suite

문제점

• 모두 자동 발견 가능한 정보 (tree 명령어, pyproject.toml, requirements.txt)
• README와 중복 (에이전트와 인간이 모두 이미 알고 있는 내용)
• 토큰만 낭비하고 실제 가치 없음

 

좋은 예 : 전략적 AGENTS.md

# Critical Constraints for Agents

## Package Manager: Use uv, NOT pip
- The project uses uv for dependency management
- pip will NOT work and will cause build failures
- Always use: uv pip install, uv pip freeze

## Testing Requirements
- MUST use --no-cache flag: pytest --no-cache tests/
- Tests fail without this flag due to cached responses
- This is a known quirk of the test infrastructure

## DO NOT Delete
- /legacy/deprecated_api.py is still in use by legacy clients
- Remove only after migration is complete (see docs/migration-plan.md)
- Verify zero references before deletion

## Common Agent Mistakes (Prevent these!)
1. Using pip instead of uv (WRONG)
2. Running pytest without --no-cache flag (WRONG)
3. Deleting files in /legacy without checking refs (WRONG)
4. Modifying config/secrets.yaml directly (always use env vars)

한글로 표현하자면...

# Critical Constraints for Agents

## Package Manager: pip이 아니라 uv 사용
- 이 프로젝트는 의존성 관리를 위해 uv를 사용합니다.
- pip은 동작하지 않으며 빌드 실패를 발생시킵니다.
- 항상 다음 명령을 사용하세요:
  - uv pip install
  - uv pip freeze

## 테스트 요구사항 (Testing Requirements)
- 반드시 --no-cache 플래그를 사용해야 합니다:  
  pytest --no-cache tests/
- 캐시된 응답 때문에 이 플래그가 없으면 테스트가 실패합니다.
- 이는 테스트 인프라의 알려진 특이 사항(known quirk)입니다.

## 삭제 금지 (DO NOT Delete)
- /legacy/deprecated_api.py 는 아직 레거시 클라이언트에서 사용 중입니다.
- 마이그레이션 완료 후에만 삭제 가능합니다 (docs/migration-plan.md 참고)
- 삭제하기 전에 반드시 참조가 0개인지 확인해야 합니다.

## 에이전트가 자주 하는 실수 (반드시 방지)
1. pip 사용 (WRONG)
2. pytest 실행 시 --no-cache 플래그 없이 실행 (WRONG)
3. /legacy 디렉터리의 파일을 참조 확인 없이 삭제 (WRONG)
4. config/secrets.yaml 파일을 직접 수정 (항상 env vars 사용)

장점

• 발견 불가능한 정보: uv 사용 requirement, --no-cache 플래그는 에이전트가 자동으로 알 수 없음
• 에이전트 실수 예방: 반복되는 패턴을 명시적으로 차단
• 효율적: 간결하고, 32KiB 제한 내에 들어옴
• 실제 가치 제공: 지식 기반 개선, 토큰 절감

 

시간이 지나면 생기는 문제 — 문서 부패

설령 AGENTS.md를 완벽하게 작성했다 하더라도, 단일 정적 파일이라는 형식 자체에 근본적인 한계가 있다. 코드베이스는 매일 변하지만, AGENTS.md는 한 번 작성하면 자동으로 갱신되지 않는다.

• payments-v1 모듈이 이미 삭제되었는데 AGENTS.md에는 여전히 "건드리지 마라"고 적혀 있음
• TypeScript 5.5로 업그레이드했는데 AGENTS.md에는 "TypeScript 5.3 사용 중"이라고 적혀 있음
• 새로운 테스트 프레임워크로 마이그레이션했는데 AGENTS.md에는 구 프레임워크 실행 방법이 적혀 있음

시간이 지날수록 AGENTS.md와 실제 코드베이스 사이의 간극(drift)이 커지고, 이 오래된 정보는 앞서 말한 앵커링 효과를 통해 에이전트를 잘못된 방향으로 유도하게 된다.

문서 부패의 실제 사례

한 달 전 AGENTS.md에 "Prisma ORM을 사용한다"고 적었다. 그런데 2주 전 팀이 Drizzle ORM으로 마이그레이션을 시작했다. AGENTS.md는 업데이트되지 않았고, 에이전트는 여전히 Prisma 스타일의 쿼리를 생성한다.

더 심각한 사례: AGENTS.md에 "E2E 테스트는 Cypress를 사용한다"고 적혀 있는데, 실제로는 3개월 전 Playwright로 전환했다. 에이전트가 Cypress 문법으로 테스트를 작성하면 아예 실행조차 되지 않는 코드가 만들어진다.

문서 부패의 악순환

1. AGENTS.md 작성 (정확함)
   ↓
2. 코드베이스 변화 (계속 진화)
   ↓
3. AGENTS.md가 현실과 괴리 (문서 부패)
   ↓
4. 에이전트가 오래된 정보 기반으로 작업 (앵커링)
   ↓
5. 잘못된 코드 생성 (성능 하락)
   ↓
6. 개발자가 수동으로 AGENTS.md 업데이트...
   ↓
7. 2번으로 돌아감 (반복)

이것이 AGENTS.md를 "살아있는 문서"로 관리해야 하는 이유다. 코드가 바뀔 때마다 AGENTS.md도 함께 갱신하는 루틴을 만들지 않으면, 이 악순환에서 벗어나기 어렵다.

 

8. 파일 관리 전략 — 최신 상태 유지법

자동 생성 회피

많은 개발자 도구들이 "AGENTS.md 자동 생성" 기능을 제공한다. 이를 피하는 방법.

• Claude Code의 `/init`: 사용하지 말 것. 자동 생성 결과는 성능을 저해함
• GitHub Copilot의 자동 제안: "AGENTS.md를 생성할까요?" 물어보면 거절
• 수동 작성이 표준: AGENTS.md는 프로젝트별로 수동 작성해야 함

 

수동 유지보수 체크리스트

AGENTS.md를 최신 상태로 유지하려면:

매월 검토 사항

• 새로운 도구/패키지 매니저 도입 여부 확인
• 테스트 실행 시 필수 플래그 변경 확인
• 레거시 코드 상태 업데이트
• 에이전트가 반복 실수하는 새로운 패턴 추가

Git 관리

• AGENTS.md 변경을 별도 커밋으로 추적
• PR에서 AGENTS.md 변경사항을 명시적으로 검토
• 마이너 버전 업데이트 시 AGENTS.md 버전 갱신

Best Practice

AGENTS.md는 프로젝트 설정서(Configuration)이다. 마치 docker-compose.yml이나 .github/workflows를 관리하듯이, 신중하게 관리해야 한다.

 

9. CLAUDE.md와의 구분

CLAUDE.md는 더 광범위한 범위를 커버할 수 있다:

구분	대상 사용자	내용 범위
AGENTS.md	AI 에이전트	발견 불가능한 지침 (도구, 플래그, 제약)
CLAUDE.md	에이전트 + 개발자	아키텍처, 규칙, 의사결정, 노트, 지침

CLAUDE.md는 에이전트용 지침보다 광범위한 정보를 담을 수 있다. 다만 Anthropic 공식 문서는 파일당 200줄 이하를 권장한다 — 길수록 컨텍스트를 많이 소비하고 준수율이 낮아지기 때문이다. 여기서도 중복은 피해야 한다.

 

10. 결론 및 핵심 요약

지금까지 살펴본 연구 데이터와 커뮤니티 의견을 종합하면, AGENTS.md는 다음과 같은 원칙으로 관리해야 한다:

AGENTS.md 작성 핵심 원칙

• 포함: 에이전트가 발견할 수 없는 정보 (비직관적 도구, 특수 플래그, 제약사항)
• 제외: 에이전트가 자동으로 발견할 수 있는 정보 (디렉토리, 기술 스택, 패키지 목록)
• 목표: 토큰 절감 (16.58%), 실행 속도 단축 (28.64%), 성공률 향상
• 금지: 자동 생성 (성공률 -0.5~2%, 비용 +20% 이상 — ETH Zurich 연구 기준)
• 관리: 수동 작성, 매월 검토, 프로젝트 변화에 따른 업데이트

 

진단 도구로서의 마인드셋

Addy Osmani가 제안하는 가장 중요한 마인드셋 전환은 이것이다:

AGENTS.md = 영구적인 설정 파일이 아니라, 아직 수정되지 않은 코드베이스 냄새(code smell)의 목록

AGENTS.md에 새로운 줄을 추가해야 한다는 것은, 코드베이스에 에이전트(그리고 아마도 새로 합류한 개발자)를 혼란스럽게 만드는 무언가가 있다는 신호다.

• "이 함수 이름이 혼란스럽지만 실은 X를 한다"고 적어야 한다면 → 함수 이름을 바꾸는 것이 해결책이다
• "이 모듈은 레거시라 특별한 처리가 필요하다"고 적어야 한다면 → 레거시 모듈을 리팩토링하는 것이 해결책이다
• "테스트를 이 방식으로 실행해야 한다"고 적어야 한다면 → 테스트 설정을 기본값으로 만드는 것이 해결책이다

즉, AGENTS.md를 키우는 것이 아니라, AGENTS.md가 불필요해지도록 코드베이스를 개선하는 것이 올바른 방향이다. Addy Osmani의 비유를 빌리면: "에이전트에게 필요한 것은 지뢰의 위치다." 에이전트는 코드를 읽고 구조를 파악하는 능력을 이미 갖추고 있다. 정말 필요한 것은 "어디에 함정이 있는지", "어떤 것을 건드리면 안 되는지"에 대한 정보다.

AGENTS.md에 적으려는 내용	근본적 해결책
"getUserData 함수는 이름과 달리 사용자 세션 정보를 반환합니다"	함수 이름을 getUserSession으로 변경
"테스트 실행 시 --no-cache 옵션을 빼면 안 됩니다"	package.json의 test 스크립트에 --no-cache를 기본으로 포함
"이 API는 에러 시 200 OK에 error 필드를 넣어 반환합니다"	적절한 HTTP 상태 코드를 반환하도록 API 수정

AGENTS.md = 기술 부채 목록

이상적인 AGENTS.md는 비어 있는 파일이다. AGENTS.md에 항목이 많다는 것은 코드베이스에 개선할 부분이 많다는 신호다. 따라서 AGENTS.md를 관리하는 최선의 방법은:

1. 필요한 항목을 추가한다 (임시 가이드)
2. 코드를 수정해서 해당 항목을 불필요하게 만든다 (근본 해결)
3. 불필요해진 항목을 삭제한다 (정리)
4. 반복한다

 

최종 체크리스트

AGENTS.md를 작성할 때 다음을 확인하자:

필수 확인 항목

• [ ] 자동 생성하지 않았는가? (수동 작성)
• [ ] 디렉토리 구조 나열이 없는가?
• [ ] 기술 스택 목록 나열이 없는가?
• [ ] README와 중복되는 내용이 없는가?
• [ ] 발견 불가능한 정보만 담고 있는가?
• [ ] 32 KiB 크기 제한 내에 들어가는가?
• [ ] 에이전트가 반복적으로 실수하는 패턴이 있는가?

 

참고 자료

• ETH Zurich 연구: "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" (2026.02) – https://arxiv.org/abs/2602.11988
• Lulla et al.: ICSE JAWs 2026, 124개 GitHub PR 분석 – https://arxiv.org/abs/2601.20404
• Addy Osmani: https://addyosmani.com/blog/agents-md/
• GeekNews 커뮤니티: https://news.hada.io/topic?id=26972
• OpenAI Codex 공식 문서: https://developers.openai.com/codex/guides/agents-md/

 

AGENTS.md를 올바르게 관리하면, AI 코딩 도구의 생산성을 크게 높일 수 있다. 자동 생성의 함정을 피하고, 전략적으로 작성하자. 그것이 당신의 프로젝트와 에이전트 모두를 위한 효과적인 선택이 될 것이다.