AGENTS.md는 도움이 될까: 성공률과 토큰 연구가 엇갈린 이유

AGENTS.md에 프로젝트 규칙을 적으면 AI 코딩 에이전트가 저장소를 탐색하는 시간을 줄일 수 있습니다. 반대로 작업과 관계없는 요구까지 상시 지침에 넣으면 비용이 늘고 성공률이 낮아질 수도 있습니다.

2026년에 공개된 연구 결과도 한쪽으로 모이지 않습니다. 한 연구에서는 AGENTS.md가 실행 시간과 출력 토큰을 줄였고, 다른 연구에서는 저장소 컨텍스트 파일이 성공률을 낮추고 비용을 늘렸습니다.

이 연구들이 파일 길이만 바꿔 성능을 비교한 것은 아닙니다. 파일의 유무, 작성 방식, 평가 과제와 측정 지표가 서로 다릅니다. 결과를 함께 보려면 무엇을 실제로 측정했는지부터 구분해야 합니다.

세 연구는 서로 다른 것을 측정했다

On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents는 10개 저장소의 124개 pull request를 AGENTS.md가 있는 조건과 없는 조건으로 비교했습니다.

AGENTS.md가 있을 때 중앙 실행 시간은 28.64%, 출력 토큰은 16.58% 감소했습니다. 두 조건 모두 관련 코드 변경을 만들었지만, 이 연구의 중심 지표는 정답률보다 실행 시간과 출력 토큰이었습니다. 이 결과만으로 AGENTS.md가 성공률까지 높인다고 말할 수는 없습니다.

Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?는 여러 코딩 에이전트와 모델로 실제 저장소 문제를 평가했습니다.

이 연구에서는 저장소 컨텍스트 파일을 제공했을 때 작업 성공률이 낮아지는 경향이 있었고, 추론 비용은 20% 넘게 증가했습니다. 에이전트는 더 많은 파일을 탐색하고 테스트를 넓게 실행했지만, 불필요한 요구사항까지 지키려다 작업이 어려워질 수 있다고 분석했습니다.

Configuration Smells in AGENTS.md Files는 AGENTS.md 또는 CLAUDE.md가 있는 인기 오픈소스 저장소 100개를 분석했습니다.

린터 설정을 지침 파일에 다시 옮긴 Lint Leakage가 62%로 가장 많았습니다. 불필요한 맥락이 늘어난 Context Bloat는 42%, 특정 도구의 사용법이 상시 지침으로 들어간 Skill Leakage는 35%에서 발견됐습니다. 이 수치는 해당 문제가 성능을 얼마나 낮췄는지가 아니라, 연구진이 정의한 문제 패턴이 파일에서 발견된 비율입니다.

연구	대상 파일	중심 측정	관찰된 결과	확인하지 못한 것
효율 연구	AGENTS.md	실행 시간, 출력 토큰	28.64%, 16.58% 감소	정답률 향상 여부
효과 연구	저장소 컨텍스트 파일	과제 성공률, 비용	성공률 하락 경향, 비용 20% 이상 증가	모든 수동 작성 파일의 효과
설정 냄새 연구	AGENTS.md, CLAUDE.md	문제 패턴의 빈도	Context Bloat 42% 등	각 패턴의 성능 영향

결과가 엇갈리는 이유는 측정 대상이 다르기 때문입니다. 저장소 구조와 검증 명령을 미리 알려주면 탐색 시간은 줄 수 있습니다. 그러나 작업과 무관한 요구까지 추가하면 에이전트가 필요 이상의 파일과 테스트를 확인할 수 있습니다. 효율이 좋아졌다는 결과와 성공률이 낮아졌다는 결과는 동시에 성립할 수 있습니다.

공식 문서가 권하는 역할도 제한적이다

2026년 7월 확인한 OpenAI 자료는 Codex가 저장소의 AGENTS.md에서 지속적인 맥락을 얻도록 안내합니다. 코드만으로 추론하기 어려운 명명 규칙, 비즈니스 로직, 알려진 특이점과 의존성이 예시로 제시됩니다. 테스트 방법과 PR 메시지 규칙도 전달할 수 있습니다.

Anthropic은 CLAUDE.md를 매 세션에 들어가는 상시 컨텍스트로 설명합니다. 공식 문서는 파일당 200줄 아래를 목표로 하고, 구체적이며 간결한 지침을 권장합니다. 특정 작업에만 필요한 절차는 skill이나 경로 범위가 있는 규칙으로 옮기도록 안내합니다.

Anthropic의 200줄은 Claude Code의 운영상 권장선이지 성능이 갑자기 바뀌는 한계가 아닙니다. Codex의 AGENTS.md에 같은 숫자를 적용할 근거도 없습니다. 두 제품은 파일 이름과 로딩 규칙이 다릅니다.

공통으로 가져올 수 있는 기준은 줄 수가 아니라 범위입니다. 모든 작업에서 필요한 내용만 루트 지침으로 두고, 특정 작업이나 경로에서만 필요한 내용은 그 범위로 옮깁니다.

루트 파일에 남길 내용

다음 내용은 저장소 전체에서 반복해서 필요할 가능성이 큽니다.

기본 빌드, 테스트와 포맷 명령
코드만 보고 알아내기 어려운 저장소 구조
모든 변경에 적용되는 금지 사항
완료 전에 반드시 통과해야 하는 검증
반복해서 잘못 판단했던 프로젝트 고유 규칙

규칙은 적용 조건과 확인 방법이 분명할수록 낫습니다. 코드를 깔끔하게 작성한다는 지침은 지켰는지 확인하기 어렵습니다. API 응답 스키마를 바꾸면 pnpm test:contract를 실행한다는 지침은 적용 시점과 검증 방법이 분명합니다.

## Verification

- API 응답 스키마를 변경하면 `pnpm test:contract`를 실행한다.
- 데이터베이스 migration을 추가하면 rollback 경로도 확인한다.

루트 파일에서 빼낼 내용

기존 파일이 길다면 다음 항목부터 확인할 수 있습니다.

package.json, 린터나 포매터 설정과 중복되는 내용
특정 배포나 한 디렉터리에서만 사용하는 절차
일반적인 프로그래밍 원칙과 도구의 공식 사용법
현재 코드와 맞지 않는 경로와 명령
같은 의미를 다른 표현으로 반복한 규칙
지켰는지 확인할 수 없는 추상적인 요구

Codex에서는 하위 디렉터리의 AGENTS.md로 적용 범위를 좁힐 수 있습니다. Claude Code에서는 경로별 rules나 skill로 특정 작업의 지침을 분리할 수 있습니다. 파일을 나누더라도 매번 모두 불러온다면 컨텍스트는 줄지 않으므로 실제 로딩 범위도 함께 확인해야 합니다.

결론

AGENTS.md는 저장소 탐색을 줄일 수도 있고, 불필요한 요구를 늘려 성공률을 낮출 수도 있습니다. 현재 연구만으로 특정 길이가 가장 좋다고 말할 수는 없습니다.

루트 파일에는 코드에서 알 수 없는 정보, 반복되는 실수와 검증 가능한 명령을 우선합니다. 작업별 절차와 도구 설명은 필요한 범위에서만 불러오는 편이 낫습니다.

효과를 확인하려면 줄 수보다 실제 작업 결과를 비교해야 합니다. 같은 종류의 과제에서 성공 여부, 실행 시간, 토큰과 불필요한 파일 탐색이 어떻게 달라지는지 측정해야 합니다.

AGENTS.md는 AI 코딩에 도움이 될까