AGENTS.md는 길수록 좋을까? 2026년 연구로 검증한 작성법

AGENTS.md를 길게 쓴다고 코딩 에이전트의 정확도가 보편적으로 높아진다는 근거는 없습니다. 다만 지침은 에이전트의 탐색과 테스트 행동, 실행 시간, 토큰 사용량을 바꿀 수 있습니다. 따라서 자동화 도구로 강제할 수 없는 저장소 고유 규칙만 짧고 검증 가능하게 적는 것이 현재 근거에 맞는 작성법입니다.

이 결론은 2026년 8월 17일 기준입니다. 올해 공개된 연구들은 효율 개선, 비용 증가, 정확도 차이 없음이라는 서로 다른 결과를 보고했습니다. 한 연구의 수치를 모든 저장소에 적용하지 않고, 무엇을 측정했는지 나눠 읽어야 합니다.

 

이 글에서 사용하는 주요 용어 정의

용어	이 글에서의 뜻
AGENTS.md	코딩 에이전트에 저장소별 지속 지침을 전달하는 공개 Markdown 형식
컨텍스트 파일	연구에서 AGENTS.md, CLAUDE.md처럼 프로젝트 지침을 제공하는 파일을 묶어 부르는 말
지침 준수	에이전트가 파일에 적힌 명령과 제약에 맞게 행동하는 정도
과제 성공률	각 연구가 테스트나 해결 기준으로 판정한 작업 완료 성능
구성 냄새	중복, 비대화, 충돌처럼 유지보수와 컨텍스트 사용을 해칠 가능성이 있는 패턴. 실제 장애나 성능 저하와 같은 뜻은 아님

 

결론부터: 파일의 존재보다 내용과 평가가 중요합니다

실무에서는 세 가지 원칙으로 시작하면 됩니다.

1. 작업 결과를 바꾸는 저장소 고유 제약만 남깁니다.
2. 린터와 CI가 검사하는 규칙, README에 있는 설명, 드문 작업 절차를 반복하지 않습니다.
3. 기존 파일과 축소한 파일을 같은 과제로 비교합니다.

이 원칙은 “짧을수록 무조건 좋다”는 뜻이 아닙니다. 파일 길이에 관한 보편적인 임계값은 검증되지 않았습니다. 문제는 글자 수보다 관련 없는 정보, 중복, 서로 충돌하는 지침입니다.

성과 지표도 분리해야 합니다. 테스트 통과율이 같아도 실행 시간이나 토큰이 달라질 수 있고, 지침을 더 잘 따르면서 과제 성공률은 그대로일 수도 있습니다. “성능이 좋아졌다”는 한 문장으로 이 차이를 뭉뚱그리면 연구 결과를 잘못 읽게 됩니다.

 

Codex는 AGENTS.md를 어떻게 읽는가

Codex는 작업을 시작할 때 전역 지침과 프로젝트 지침을 연결합니다. OpenAI의 현재 공식 문서에 따르면 전역 범위에서는 AGENTS.override.md가 있으면 이를 읽고, 없으면 AGENTS.md를 읽습니다. 프로젝트에서는 루트부터 현재 작업 디렉터리까지 내려오며 각 디렉터리에서 하나의 지침 파일을 선택합니다. 현재 디렉터리에 가까운 파일이 결합된 프롬프트의 뒤에 놓여 앞선 지침보다 구체적으로 작용합니다.

다음 구조에서 루트 파일은 저장소 전체에, frontend/AGENTS.md는 프런트엔드 하위 작업에 추가로 적용됩니다.

my-repo/
├─ AGENTS.md                 # 저장소 공통 규칙
├─ backend/
│  └─ src/
└─ frontend/
   ├─ AGENTS.md             # frontend 작업에 추가되는 규칙
   └─ src/

 

이 도식은 Codex 기준입니다. 다른 코딩 에이전트가 같은 파일 이름과 우선순위를 쓴다고 가정하면 안 됩니다. 제품별 공식 문서를 따로 확인해야 합니다.

 

AGENTS.md와 README·린터·SKILL.md의 역할

문서마다 책임을 나누면 AGENTS.md가 불필요하게 커지는 일을 막을 수 있습니다.

위치	넣을 내용	예시
AGENTS.md	매 작업에 필요한 저장소 고유 합의	변경 금지 영역, 검증 명령, 패키지별 제약
README	사람이 이해할 프로젝트 개요와 사용법	설치, 아키텍처 소개, 운영 안내
린터·포매터·CI	기계적으로 판정하고 강제할 규칙	서식, 정적 분석, 테스트 통과 조건
SKILL.md 또는 별도 문서	특정 작업에서만 필요한 절차와 자료	릴리스, 보안 감사, 콘텐츠 발행 절차

 

이 표는 공식 스키마가 아니라 구성 냄새 연구를 실무에 적용한 분류입니다. AGENTS.md 공식 프로젝트도 이 형식을 필수 필드가 없는 Markdown으로 설명합니다. 정해진 목차를 채우는 일보다 에이전트가 실제로 필요한 내용을 제공하는 일이 먼저입니다. 자세한 형식 소개는 AGENTS.md 공식 사이트에서 확인할 수 있습니다.

 

2026년 연구 네 편은 무엇을 발견했나

네 연구의 결론은 겉으로 충돌합니다. 실험 대상과 측정값을 나란히 놓으면 이유를 이해하기 쉽습니다.

연구	범위	주로 측정한 값	보고된 결과	해석할 때의 한계
Lulla 외	10개 저장소, 124개 PR	실행 시간, 출력 토큰, 완료 행동	중앙 실행 시간 28.64%, 출력 토큰 16.58% 감소와 연관	정확도 향상이나 모든 환경의 비용 절감을 뜻하지 않음
Gloaguen 외	SWE-bench 기반 실험과 12개 저장소의 CTXbench 138개 과제	성공률, 추론 비용, 지침 준수	성공률의 일반적 향상 없이 평균 추론 비용 20% 초과 증가	조건과 에이전트가 다른 환경에 그대로 적용할 수 없음
dos Santos 외	컨텍스트 파일이 있는 인기 오픈소스 저장소 100개	구성 냄새 탐지	Lint Leakage 62%, Context Bloat 42%, Skill Leakage 35%	휴리스틱 탐지이며 실제 성능 저하율을 측정한 연구가 아님
Khatri	3개 저장소, 17개 과제, 288회 실행	gold test 기반 정확도	무컨텍스트·항상 주입·선택적 컨텍스트가 정확도를 측정 가능하게 바꾸지 않음	두 에이전트와 제한된 과제 표본의 절제 연구

 

효율이 개선됐다는 연구

Lulla 등은 AGENTS.md 유무를 나눠 10개 저장소의 124개 PR을 분석했습니다. 논문은 파일이 있을 때 중앙 실행 시간이 28.64%, 출력 토큰이 16.58% 낮았고 과제 완료 행동은 비슷했다고 보고합니다. 이는 평균 절감률도, 정확도 상승도 아닙니다. 해당 실험에서 관찰한 운영 효율의 연관 관계입니다. 논문은 2026년 1월 28일 처음 공개됐고 3월 30일 v2로 갱신됐습니다.

 

성공률은 나아지지 않고 비용이 늘었다는 연구

Gloaguen 등은 LLM이 만든 컨텍스트 파일과 개발자가 커밋한 파일을 함께 평가했습니다. 이 연구에서는 컨텍스트 파일이 과제 성공률을 전반적으로 높이지 않았고, 평균 추론 비용은 20% 넘게 증가했습니다. 에이전트는 지침을 잘 따랐지만 저장소 개요는 도움이 되지 않았다는 결과도 보고했습니다. 논문은 2026년 2월 12일 공개됐고 6월 23일 v2로 갱신됐습니다.

이 결과만으로 “AGENTS.md는 항상 비용을 늘린다”고 결론 내릴 수는 없습니다. 앞선 연구는 다른 저장소와 과제를 사용했고 실행 시간과 출력 토큰을 중심으로 측정했습니다.

 

컨텍스트 주입 전략 간 정확도 차이가 없었다는 연구

Khatri의 통제 절제 연구는 Claude Code와 Codex, 3개 저장소의 실제 과제 17개, 288회 실행을 비교했습니다. 무컨텍스트, 항상 주입, 선택적 주입 전략이 어느 에이전트에서도 정확도를 측정 가능하게 바꾸지 않았다고 보고합니다. 저자는 실패 원인을 저장소 지식 부족보다 기능 설계와 정확한 연결 같은 구현 능력에서 찾았습니다. 다만 이는 2026년 7월 28일 공개된 단일 저자의 제한된 표본 연구입니다.

 

왜 결과가 충돌할까

가장 타당한 해석은 파일 유무만으로 결과가 결정되지 않는다는 것입니다. 과제 난이도, 지침 품질, 모델과 에이전트, 평가 지표가 모두 다릅니다. 이는 네 연구를 종합해 내린 실무적 해석이며, 하나의 논문이 보편적 인과관계를 증명한 것은 아닙니다.

따라서 특정 수치를 목표로 삼기보다 저장소 안에서 직접 확인해야 합니다. 정확도, 실행 시간, 토큰, 지침 위반을 따로 기록하면 어떤 변화가 실제로 유용했는지 판단할 수 있습니다.

 

긴 파일에서 자주 생기는 구성 냄새

dos Santos 등은 AGENTS.md 또는 CLAUDE.md가 있는 인기 오픈소스 저장소 100개를 분석했습니다. 2026년 7월 30일 갱신된 논문 v5는 여섯 가지 구성 냄새를 제시하며, 그중 Lint Leakage, Context Bloat, Skill Leakage가 가장 흔했다고 보고합니다. 아래 수치는 조사 표본 안의 파일 비율이며 전체 저장소의 발생률이 아닙니다.

 

Lint Leakage: 자동 도구가 검사하는 규칙을 반복합니다

“세미콜론을 쓰지 마라”, “포맷을 맞춰라”처럼 린터나 포매터가 이미 판정하는 규칙을 자연어로 되풀이하는 패턴입니다. 도구 설정을 단일 기준으로 두고, AGENTS.md에는 실행할 명령과 통과 조건만 적는 편이 낫습니다.

 

Context Bloat: 모든 작업에 배경을 상시 주입합니다

긴 프로젝트 역사, 상세한 아키텍처 설명, 모든 패키지의 사용법은 현재 작업과 무관할 수 있습니다. 사람을 위한 설명은 README나 설계 문서에 두고, 에이전트가 필요할 때 찾아 읽게 경로만 안내합니다.

 

Skill Leakage: 드문 작업 절차를 전역 규칙에 넣습니다

릴리스나 보안 감사처럼 특정 상황에서만 쓰는 절차를 루트 파일에 넣으면 모든 작업에 같은 내용이 주입됩니다. 별도 문서나 작업별 스킬로 분리하는 편이 책임이 분명합니다.

 

충돌하는 지침도 함께 확인합니다

루트 파일은 “모든 테스트를 실행하라”고 하고 하위 파일은 “단위 테스트만 실행하라”고 하면 어느 조건을 따라야 하는지 모호합니다. 범위를 명시하고 더 가까운 디렉터리에 패키지 고유 규칙을 두십시오. 구성 냄새가 발견됐다는 사실만으로 성능 장애가 입증되는 것은 아니지만, 유지보수할 이유는 충분합니다.

 

실전: AGENTS.md를 15분 안에 줄이는 방법

 

1단계: 각 문장이 바꾸는 작업 결과를 적습니다

문장 옆에 “이 지침이 없으면 무엇이 달라지는가?”를 써봅니다. 답이 프로젝트 소개나 일반적인 품질 당부뿐이라면 삭제 후보입니다. 변경 금지 경로, 필수 테스트, 생성 파일 취급처럼 결과가 달라지는 내용은 남깁니다.

 

2단계: 강제 가능한 규칙은 린터와 CI로 옮깁니다

“코드를 깔끔하게 작성한다”는 판정 기준이 없습니다. 대신 저장소가 이미 제공하는 검사 명령과 성공 조건을 적습니다. 새 도구를 임의로 도입할 필요는 없습니다.

 

3단계: 드문 절차를 분리합니다

배포, 마이그레이션, 감사 절차는 별도 문서나 SKILL.md로 옮깁니다. AGENTS.md에는 해당 작업에서 읽어야 할 문서 경로만 남깁니다.

 

4단계: 가장 가까운 디렉터리로 내립니다

프런트엔드 전용 검사 명령을 모노레포 루트에 두지 마십시오. frontend/AGENTS.md로 옮기면 백엔드 작업에 관련 없는 지침이 섞이지 않습니다.

 

5단계: 수정 전후를 비교합니다

아래 예시는 실제 저장소에서 실행한 결과가 아니라 교육용 가상 예제입니다.

 

수정 전

# 프로젝트 안내
이 프로젝트는 고객 주문을 처리하는 서비스입니다.
항상 깨끗하고 읽기 좋은 코드를 작성하세요.
프로젝트 구조는 README를 참고하세요.
모든 TypeScript 파일은 작은따옴표를 사용하세요.
세미콜론은 사용하지 마세요.
커밋 전에 코드를 포맷하세요.
테스트를 꼼꼼히 작성하세요.
배포할 때는 운영 체크리스트 전체를 따르세요.
프런트엔드 변경은 스냅샷을 갱신하세요.
백엔드 변경은 데이터베이스 호환성을 확인하세요.
의존성은 신중하게 추가하세요.

 

수정 후

# 작업 규칙
- 설치: `npm ci`
- 검증: `npm test`와 `npm run lint`를 통과하세요.
- `generated/` 아래 파일은 직접 수정하지 마세요.
- 새 런타임 의존성을 추가하기 전에 승인을 요청하세요.
- 프런트엔드 전용 규칙은 `frontend/AGENTS.md`를 따르세요.
- 배포 작업에서만 `docs/release.md`를 읽으세요.

 

포맷 세부사항은 린터에 맡기고, 프로젝트 소개는 README에 남겼습니다. 배포 절차와 프런트엔드 규칙은 필요한 범위로 옮겼습니다. 명령은 예시이며 이 글을 작성하면서 실행하지 않았습니다. 실제 저장소의 패키지 관리자와 스크립트 이름에 맞게 바꿔야 합니다.

 

내 저장소에서 효과를 확인하는 작은 A/B 점검

축소한 파일이 더 나은지는 같은 조건에서 확인합니다. 반복되는 실제 과제 3~5개를 고르고 모델, 에이전트 버전, 프롬프트, 승인 조건을 고정합니다. A에는 기존 파일을, B에는 축소한 파일이나 파일 없는 조건을 사용합니다. 실행 순서가 결과에 영향을 줄 수 있으므로 순서도 기록하십시오.

아래 표는 미실행 기록 템플릿입니다. 수치와 결과를 의도적으로 비워 두었습니다.

과제	조건	테스트 통과	필수 규칙 위반	실행 시간	입력·출력 토큰	재작업 메모
과제 1	A: 기존 파일
과제 1	B: 축소 파일
과제 2	A: 기존 파일
과제 2	B: 축소 파일

 

토큰 수는 사용하는 도구가 제공할 때만 기록합니다. 정확도가 같고 시간이나 토큰, 사람의 재작업이 줄었다면 축소안을 채택할 근거가 됩니다. 중요한 규칙 위반이 늘었다면 전체 파일을 되돌리지 말고 해당 규칙만 복구합니다.

이 점검은 운영 의사결정을 위한 작은 비교입니다. 3~5개 과제만으로 통계적 유의성이나 일반적인 벤치마크 성능을 주장할 수 없습니다. 모델이나 에이전트가 갱신되면 같은 결과가 유지된다는 보장도 없습니다.

 

적용할 때의 한계

2026년 연구들은 저장소, 과제, 모델 표본이 제한되어 있습니다. 일부는 프리프린트이며 후속 검토에서 방법과 결론이 바뀔 수 있습니다. 구성 냄새 연구는 SCAM 2026 학회 참고 정보가 표시돼 있지만, 냄새와 성능 저하 사이의 인과를 측정한 연구는 아닙니다.

지침 파일은 모델의 구현 능력을 대신하지 못합니다. 보안과 권한도 자연어 지침만으로 강제하지 말고 샌드박스, 승인 절차, CI 같은 통제 수단을 사용해야 합니다. 제품별 파일 탐색 방식은 바뀔 수 있으므로 게시하거나 설정을 바꾸기 전에 공식 문서를 다시 확인하십시오.

 

마무리

AGENTS.md의 효과는 파일 유무나 길이 하나로 결정되지 않습니다. 2026년 연구는 실행 효율이 나아진 사례와 성공률 향상 없이 비용이 늘어난 사례, 정확도 차이를 찾지 못한 사례를 함께 보여줍니다. 저장소 고유 제약을 간결하게 적고 직접 비교하는 것이 안전한 결론입니다.

지금 할 일은 단순합니다. 현재 AGENTS.md에서 린터나 CI가 이미 강제하는 규칙 세 개를 찾아 삭제 후보로 표시하십시오. 그다음 기존 파일과 축소안을 같은 과제로 실행해 테스트 통과, 규칙 위반, 시간과 재작업을 따로 비교하면 됩니다.

 

참고 자료

• Custom instructions with AGENTS.md — OpenAI, 게시·수정일 미표시, 2026-08-17 열람
• AGENTS.md — AGENTS.md 프로젝트, 게시·수정일 미표시, 2026-08-17 열람
• On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents — Jai Lal Lulla 외, arXiv v1 2026-01-28, v2 2026-03-30