현재 60,000개 이상의 오픈 소스 저장소(repositories)가 AGENTS.md 파일을 보유하고 있습니다. 이는 Codex, Claude Code, Cursor, Copilot 및 기타 약 30개의 도구들이 사용자의 코드를 건드리기 전에 읽는 "에이전트를 위한 README"입니다. 대규모 모노레포(monorepos)에는 이 파일들이 중첩되어 있습니다. 보고에 따르면 메인 OpenAI 저장소에는 88개가 포함되어 있습니다.

문제는 이 파일들이 집합적으로 에이전트에게 무엇을 전달하는지 살펴보는 사람이 거의 없다는 점입니다. 지침(Instructions)은 저장소 루트(root)부터 편집 중인 파일까지 아래로 누적됩니다. 이 지침들은 서로 다른 사람들이, 서로 다른 연도에, 서로 다른 도구들을 위해 작성합니다. 내용이 중복되기도 하고, 서로 모순되기도 합니다. 또한 3번의 리팩터링(refactors) 전에 삭제된 문서로 링크를 걸기도 합니다. 그리고 이 모든 바이트는 매 요청마다 컨텍스트 토큰(context tokens) 비용으로 지불됩니다.

저는 이 체인을 가시화하기 위해 Scopeglass를 구축했고, 이를 8개의 잘 알려진 저장소에 적용했습니다. 모든 분석은 로컬(local)에서 읽기 전용(read-only)으로 수행되었습니다. 이 도구는 네트워크 호출을 하지 않으며 저장소 콘텐츠를 절대 실행하지 않습니다.

수치

*Pluto는 AGENTS.md 쇼케이스 목록에 있었으나 이후 AGENTS.md를 완전히 삭제했습니다. 지침 파일은 저장소 수준에서도 부패(rot)합니다.

방법론: AGENTS.md를 포함하는 모든 디렉토리에 대해, Scopeglass는 전체 루트-대상 체인(root-to-target chain)을 분석하여 바이트 단위의 정확한 크기, 투명한 토큰 추정치(ceil(UTF-8 bytes / 3) — 모델 토크나이저(tokenizer)를 의도적으로 사용하지 않음), 그리고 결정론적 진단(deterministic diagnostics) 결과를 보고했습니다. 진단 결과는 체인 전반에 걸쳐 중복 제거되었습니다. 수치는 2026-07-15 각 저장소의 기본 브랜치 헤드(default branch head)에서 수집되었습니다. 아래는 사용된 스크립트입니다.

눈에 띄는 점

1. 루트에 있는 단 하나의 잘못된 참조가 모든 체인을 오염시킵니다. 깨진 참조(broken references)는 예상보다 드물었지만, 존재하는 경우에는 상속됩니다. Airflow의 루트 AGENTS.md는 에이전트를 .claude/skills/magpie-setup/으로 안내하는데, 이는 심볼릭 링크(symbolic link)입니다. 이 파일이 루트에 있기 때문에, Airflow의 14개 AGENTS.md 체인 모두가 해당 참조를 상속받습니다. 더 깊은 곳에 있는 task-sdk/src/airflow/sdk/_shared/AGENTS.md는 에이전트를 ../../../../shared로 안내하는데, 이는 더 이상 존재하지 않는 경로입니다. 해당 패키지를 건드리는 모든 요청마다, 지침이 에이전트를 벽으로 정중하게 안내하고 있는 셈입니다.

2. 지침이 반복됩니다 — 챔피언은 930줄이나 떨어져서 반복합니다. 중첩된 파일은 조상 파일의 내용을 상속받으므로, 세 단계에 걸쳐 작성된 규칙은 강조가 아니라 세 배의 컨텍스트(context) 비용을 청구하는 것입니다. 가장 눈에 띄는 사례는 모든 새로운 crewAI 프로젝트에 제공되는 crewAI CLI 템플릿 AGENTS.md입니다. 이 파일은 48행에서 "Python >=3.10, <3.14"라고 명시하고, 980행에서 토씨 하나 틀리지 않고 똑같이 다시 명시합니다. 사람은 자신의 지침 파일 980행을 읽지 않지만, 에이전트는 매번 이를 읽습니다. crewAI의 declarative_flow 템플릿 체인에서 식별된 17개의 중복 항목은 대부분 반복되는 구조적 보일러플레이트(boilerplate)로, 사람은 대충 훑고 지나가지만 에이전트는 이를 파싱(parse)하고 비용을 지불합니다.

3. 토큰 비용은 실재합니다. 에이전트가 소스 코드의 단 한 줄을 읽기도 전에, 측정된 가장 큰 체인은 약 18,600 토큰(airflow의 가장 깊은 패키지; crewAI의 템플릿 체인은 이와 100 토큰 이내의 차이)이었습니다. Airflow의 중앙값(median) 체인은 약 12,800 토큰입니다. 만약 당신의 에이전트가 토큰당 비용을 청구한다면, 이는 모든 요청에 대해 기본적으로 부과되는 입장료(cover charge)와 같습니다.

4. 정직한 무효(null): 충돌 제로. Scopeglass의 충돌 휴리스틱(conflict heuristic)은 의도적으로 좁게 설정되어 있습니다(동일한 정규화된 규칙 코어, 반대되는 선행 극성). 8개의 저장소 모두에서 충돌이 단 한 번도 발생하지 않았습니다. AGENTS.md 파일을 유지 관리하는 인기 저장소들은 이 패턴이 포착할 만한 방식으로 스스로 충돌하지 않는 것으로 보입니다. 저에게는 괜찮습니다. 건강한 입력값에 대해 조용히 유지되는 진단 도구가 바로 그 목적이니까요.

이것이 지루한 인프라가 되어야 하는 이유

이것은 저장소들에 대한 비난이 아닙니다. 린터(linter)가 없는 모든 산문 기반 설정(config-by-prose) 시스템에서 발생하는 현상입니다. 우리는 이미 수년 전에 코드 스타일, 임포트(imports), 데드 링크(dead links) 문제를 해결했습니다. 지침 파일(instruction files)은 문서가 보이지 않게 부식되는 가장 최신의 장소일 뿐이며, 읽는 이(에이전트)가 결코 불평하지 않는다는 반전이 있을 뿐입니다.

이를 CI(지속적 통합) 문제로 만드는 방법은 다음과 같습니다:

scopeglass check . --fail-on error --max-tokens 8000

손상된 참조나 초과된 컨텍스트 예산(context budget)에 대해 Exit 1을 반환하며, 시간에 따른 추적을 원한다면 버전 관리된 JSON을 제공합니다. 로컬 전용이며, 결정론적(deterministic)이고, MIT 라이선스입니다.

재현 방법

npm i -g scopeglass
node analyze-agents-md.mjs owner/repo another/repo …

설문 스크립트(각 저장소를 shallow-clone 하고, 모든 AGENTS.md 디렉토리에 Scopeglass를 실행하며, 진단 결과를 중복 제거하고, 이 포스트의 표와 JSON 증거 파일을 생성함)는 gist에 있습니다. 여러분의 모노레포(monorepo)에서 실행해보고 재미있는 점을 발견한다면 꼭 알려주세요.

Scopeglass는 해당 형식이 문서화하는 정전적 조상 체인 의미론(canonical ancestor-chain semantics)이라는 예상 범위를 보고합니다. 특정 벤더가 프롬프트를 어떻게 구성하는지까지 안다고 주장하지 않으며, 충돌 휴리스틱은 의도적으로 좁게 설정되어 있습니다. 이 두 가지 제한 사항은 저장소에 문서화되어 있습니다.