AGENTS.md나 CLAUDE.md를 넣으면 에이전트가 저장소 규칙을 덜 헤맬 수 있다. 반대로 모든 작업에 같은 지침을 밀어 넣으면, 지금 하지 않는 일까지 매번 읽게 된다. 이 글에서 확인한 연구들이 서로 다른 결론처럼 보인 이유도 여기에 있다.
공개 연구 세 편을 나란히 놓으면 결론이 엇갈린다. 한 연구는 실행 시간과 출력 토큰이 줄었다고 보고했고, 다른 연구는 성공률이 낮아지는 경향과 추론 비용 증가를 관찰했다. 또 다른 연구는 AGENTS.md와 CLAUDE.md에 어떤 설정 문제가 반복되는지 살폈다. 차이는 파일의 존재 여부보다 무엇을 측정했고, 지침이 실제 작업과 얼마나 가까웠는지에 있다.
이 글에서는 그 숫자를 2dayapp의 성능으로 옮기지 않는다. 대신 이 저장소에 지침 파일을 둔다면 어떤 정보만 루트에 남기고, 나머지는 어디로 내려야 하는지 정리한다.
숫자보다 먼저 봐야 할 것
세 연구는 같은 질문에 답하지 않았다.
On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents는 10개 저장소의 124개 pull request를 AGENTS.md 유무로 비교했다. 파일이 있을 때 중앙 실행 시간은 28.64%, 출력 토큰은 16.58% 줄었다. 하지만 중심 측정값은 실행 시간과 출력 토큰이었고, 성공률이 올랐다는 결과는 아니다.
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%에서 발견됐다. 여기서 말하는 비율은 성능 저하율이 아니라 연구진이 정의한 패턴의 발견 비율이다.
| 연구 | 측정한 것 | 결과 | 이 결과로 말할 수 없는 것 |
|---|---|---|---|
| 효율 연구 | 실행 시간·출력 토큰 | 28.64%·16.58% 감소 | 성공률 향상 |
| 컨텍스트 평가 | 과제 성공·추론 비용 | 성공률 하락 경향·비용 20% 이상 증가 | 모든 지침 파일의 유해성 |
| 설정 냄새 분석 | 나쁜 패턴의 출현 빈도 | Context Bloat 42% 등 | 각 패턴의 성능 영향 |
그래서 “AGENTS.md는 좋다”와 “AGENTS.md는 나쁘다” 중 하나를 고르는 방식은 맞지 않는다. 저장소 구조와 확인 명령처럼 코드에서 바로 보이지 않는 정보는 탐색을 줄일 수 있다. 작업과 상관없는 정책을 넣으면 반대로 집중해야 할 범위를 넓힌다.
공식 문서도 상시 맥락의 역할을 좁게 본다
OpenAI 자료는 Codex의 AGENTS.md에 명명 규칙, 코드로 알기 어려운 비즈니스 규칙, 알려진 특이점, 의존성, 검증 명령 같은 내용을 둘 수 있다고 설명한다. 공통으로 적용되는 정보라는 점이 핵심이다.
Anthropic은 CLAUDE.md를 세션에 들어오는 프로젝트 맥락으로 설명하며, 구체적이고 간결한 지침을 권한다. 파일당 200줄 아래라는 안내도 있지만, 이것은 Claude Code의 운영 권장선이지 성능이 갑자기 바뀌는 제품 한계가 아니다. Codex 파일에 같은 숫자를 그대로 적용할 근거도 없다.
두 문서에서 공통으로 읽히는 기준은 줄 수가 아니라 적용 범위다. 거의 모든 작업이 읽어야 하는 규칙만 루트에 두고, 특정 디렉터리나 작업에서만 필요한 절차는 그 범위로 내린다.
이 저장소에서 파일을 만든다면
작성 당시 이 저장소에는 AGENTS.md나 CLAUDE.md가 없었다. 연구 결과만 보고 파일을 만들고 성능이 좋아졌다고 말할 수는 없다. 대신 실제 규칙의 출처를 먼저 확인했다. package.json은 검증 명령의 출처이고, deploy.yml은 배포 순서의 출처다. 도입한다면 현재 코드가 이미 드러내지 못하는 규칙부터 작은 파일로 시험하는 편이 낫다.
이 저장소의 package.json에는 pnpm format:check, pnpm lint, pnpm check, pnpm test, pnpm build를 묶은 pnpm verify가 있다. 이런 검증 명령은 “완료 전에 무엇을 실행하는가”라는 규칙의 후보가 될 수 있다. 반면 Astro의 일반 사용법이나 JavaScript 스타일 설명을 다시 넣는 것은 package.json과 도구 설정의 복사에 가깝다.
가령 파일을 만든다면 아래처럼 적용 조건이 보이는 규칙만 남길 수 있다.
## 검증
- 변경을 끝내기 전에 `pnpm verify`를 실행한다.
- 특정 디렉터리에서만 필요한 절차는 그 디렉터리의 규칙이나 별도 문서에 둔다.이 예시는 현재 저장소에 실제로 존재하는 AGENTS.md의 내용이 아니다. 도입 후보를 설명하기 위한 예시다. 이 구분을 하지 않으면 “파일을 만들었다”와 “파일이 작업 결과를 개선했다”를 혼동하게 된다.
이 저장소에 대입하면 루트 파일과 실행 파일의 역할도 나뉜다.
| 정보 | 출처 또는 둘 위치 | 루트 지침에 다시 적을 필요 |
|---|---|---|
pnpm verify를 완료 전에 실행한다는 규칙 |
package.json와 루트 지침 후보 |
명령을 찾기 어렵다면 짧게 연결 |
verify → deploy → indexnow 순서 |
deploy.yml |
배포 작업에만 필요한 상세 절차는 적지 않음 |
| 내부 링크가 실제 산출물에 있는지 확인하는 방식 | check-internal-links.mjs와 테스트 |
실행 코드가 이미 설명하므로 복사하지 않음 |
이 표에서 루트 지침의 후보는 “무엇을 해야 하는가” 한두 줄이지, 워크플로 YAML과 스크립트 전체가 아니다. 실행 가능한 규칙의 원본을 남겨 두고, 루트 파일에는 에이전트가 놓치기 쉬운 진입점만 가리키는 편이 중복을 줄인다.
길어진 파일에서 먼저 덜어낼 것
다음 내용은 루트 지침과 자주 충돌한다.
package.json, 린터, 포매터 설정에 이미 있는 내용- 한 번의 배포나 한 디렉터리에만 필요한 절차
- 일반적인 프로그래밍 조언과 공식 튜토리얼
- 지금 코드와 맞지 않는 경로와 명령
- 같은 규칙을 표현만 바꿔 반복한 문장
- 지켰는지 확인할 방법이 없는 추상적인 요구
Codex는 하위 디렉터리의 AGENTS.md로 범위를 좁힐 수 있고, Claude Code는 경로별 rules나 skill로 절차를 분리할 수 있다. 다만 파일을 쪼개도 매번 모든 조각을 불러오면 비용은 그대로다. 분리의 목적은 파일 수를 늘리는 것이 아니라 실제 로딩 범위를 줄이는 데 있어야 한다.
지금 남는 판단
이 글의 세 연구를 함께 읽고도 확실하게 말할 수 있는 것은 하나다. 상시 지침에는 저장소 전체에 반복해서 필요한 정보만 두고, 효과는 파일의 길이가 아니라 비슷한 작업의 결과로 확인해야 한다.
비교할 값은 성공 여부, 실행 시간, 입력량, 불필요한 탐색처럼 연구가 실제로 측정한 항목이어야 한다. 이 글에는 그 실험을 2dayapp에서 수행한 자료가 없으므로, “우리 저장소에서도 몇 퍼센트 좋아졌다”는 문장을 쓰지 않는다.