코딩 에이전트는 README.md를 읽을까? — 2026년 4월 실측 현황

한 줄 답: "자동으로는 안 읽는다"

이 질문이 계속 반복된다. Claude Code를 열면 자동으로 README.md를 먹는 걸까? 답은 "자동 로드는 아니다"다. 주요 에이전트들은 자기 전용 규약 파일(CLAUDE.md, AGENTS.md, .cursor/rules/)을 세션 시작 시 자동 로드한다. README는 필요하면 도구 호출(read_file, grep)로 선택적으로 읽는다.

2026년 2월 ETH Zurich 연구가 오히려 "컨텍스트 파일이 성능을 떨어뜨릴 수 있다"는 반전 결과를 내놓으면서 논쟁은 더 복잡해졌다. 그래서 지금은 "무엇을 자동 로드하느냐"보다 "무엇을 최소한으로 쓰느냐"가 실무 화두다.

에이전트별 자동 로드 파일

에이전트	README.md 자동 로드?	자동 로드 파일	비고
Claude Code	❌	CLAUDE.md (글로벌 + 프로젝트 + local)	@README.md import로 연결 가능
OpenAI Codex	❌	AGENTS.md (+ override 체인)	테스트 커맨드 자동 실행 학습
Cursor	❌	.cursor/rules/*.mdc	Rule Type "Always"로 강제 포함 가능
Aider	❌	없음 (repo map 동적 생성)	그래프 랭킹으로 심볼 주입
GitHub Copilot CLI	❌	AGENTS.md 또는 copilot-instructions.md
Pi / Factory CLI	❌	AGENTS.md 또는 CLAUDE.md	둘 다 지원 추세

공통점은 하나다. 어느 에이전트도 README.md를 1차 자동 로드 파일로 삼지 않는다. 필요하면 도구로 명시적으로 읽는다.

Claude Code의 실제 동작

공식 메모리 문서에 따르면 Claude Code가 세션 시작 시 자동 concat해서 컨텍스트에 주입하는 파일은 세 가지다.

• ~/.claude/CLAUDE.md — 글로벌 (모든 프로젝트)
• 프로젝트 루트 CLAUDE.md
• CLAUDE.local.md — 개인 설정, git ignore 권장

README.md를 컨텍스트에 넣고 싶으면 CLAUDE.md 안에서 @README.md 한 줄로 import할 수 있다. 런치 시 expand된다. 이게 README를 Claude Code에 주입하는 공식 방법이다.

# CLAUDE.md 최상단
@README.md
@docs/architecture.md

# 이 아래는 Claude Code 전용 지시사항
...

공식 권장 길이는 200줄 이내다. 길수록 adherence가 떨어진다는 벤치마크 결과 때문이다.

ETH Zurich 연구의 반전

2026년 2월 발표된 AGENTbench 연구(arxiv 2602.11988)는 업계를 뒤흔들었다. 핵심 결과를 요약하면:

• 컨텍스트 파일이 오히려 성능을 떨어뜨린다 — 여러 에이전트·LLM에서 no-context 대비 성공률 하락 + 추론 비용 20%+ 증가
• 사람이 쓴 AGENTS.md — 평균 +4% 개선 (미미)
• LLM이 자동 생성한 AGENTS.md(/init 산출물) — 평균 -3% 저하
• 권장: LLM 자동 생성 파일은 버리고, 수동 작성하되 최소한만

이 결과가 나온 뒤 HN 커뮤니티(47034087)에서 수백 댓글이 달린 격론이 있었고, "경험적으로 /init 결과는 쓰레기", "최소주의가 정답"으로 수렴했다.

Prompt Injection — README는 공격 벡터가 된다

README를 에이전트가 읽으면 악성 지시 삽입이 가능해진다. 이건 이미 실증된 문제다.

• HiddenLayer 보고서 — Cursor가 README의 숨겨진 지시를 따라 권한 확인 없이 grep으로 API 키를 훑고 유출
• Tracebit 실험 — GPL 전문 속에 악성 지시 몇 줄 숨김. 사람 검토로는 안전해 보이는데 에이전트는 실행
• 난독화 기법 — markdown 주석(렌더 시 안 보임), Unicode 비가시 문자, HTML 태그, base64, 공백 조작

구조적 한계도 있다. LLM은 instruction과 data를 같은 neural pathway로 처리한다. 하드웨어나 프로토콜 수준 분리는 불가능하다. 에이전트가 외부 README를 읽을 때마다 실행 공간이 오염될 수 있다.

실무 권장 — 역할 분리

파일	대상	내용
README.md	사람	프로젝트 소개, quick start, 기여 가이드
AGENTS.md / CLAUDE.md	에이전트	빌드 커맨드, 테스트 실행법, 컨벤션, 금지사항
CONTRIBUTING.md	사람 + 에이전트	중복 내용 회피, 한쪽에서 @ 참조

단, Upsun의 반론도 있다. "AI 전용 파일 난립이 드러낸 진실은 README 자체가 부실했다는 것. 새 표준보다 README를 잘 쓰는 게 먼저". 이 주장도 일리가 있다. README를 명확한 실행 커맨드와 구조 설명으로 채우면, 에이전트가 도구 호출로 읽어도 대부분 상황에서 충분하다.

연구 결과 vs 실무 체감 — 어느 쪽을 믿어야 하나

HN 논쟁에서 흥미로운 지점이 있었다. "ETH 연구는 AGENTbench라는 특정 벤치마크에서의 결과일 뿐, 프로덕션 레포에서는 CLAUDE.md가 확실히 도움이 된다"는 반박이다. 이 반박의 근거는 두 가지다.

1. 벤치마크 태스크는 단편적이라 "일반 지침"이 오히려 방해. 실제 프로젝트는 맥락이 필요한 복잡한 태스크가 많음
2. ETH 실험은 "긴 context 파일"을 넣었을 때 결과라서, 짧은 파일(100줄 이내)은 다를 수 있음

2026년 4월 현재 실무 합의는 대략 이렇게 정리된다.

• 짧은 CLAUDE.md/AGENTS.md (100~200줄) — 도움이 됨
• 긴 파일 (300줄+) — 효과가 사라지거나 오히려 해가 됨
• LLM 자동 생성 (/init) — 쓰지 말 것
• README는 자동 로드 기대하지 말 것. 필요 시 @ import

정리

질문에 대한 답을 단도직입적으로 정리하면:

• 코딩 에이전트가 README.md를 자동으로 읽는가? → 아니오. 어느 주요 에이전트도 README를 1차 자동 로드 파일로 삼지 않음
• LLM이 반드시 README를 읽는가? → 아니오. 필요하면 도구 호출로 읽고, 필요 없으면 건너뜀
• 생략할 때가 많은가? → 많음. 특히 AGENTS.md/CLAUDE.md로 지시가 충분하면 README는 안 건드림
• 그럼 README를 어떻게 써야 하나? → 사람용으로 쓰되, "실행 가능한 커맨드"를 풍부하게. 에이전트가 나중에 도구로 읽어도 도움이 되도록

역설적으로 README를 잘 쓰면 AGENTS.md를 따로 쓸 필요가 줄어든다. 새 메타 파일을 추가하기 전에 README부터 점검하는 게 실무에서 가성비가 좋다. 메타 파일 박물관을 만들지 말자는 Upsun의 조언은 여전히 유효하다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.