AI 에이전트 지시문 품질 조사
GitHub에서 가장 많은 별을 받은 저장소의 91%는 코딩 에이전트에게, 어떤 파일·명령어·도구를 뜻하는지 한 번도 말하지 않는 지시를 적어도 하나는 줍니다.
4월에는 28,721개 저장소를 측정했으며 , 우리의 한계 섹션에서는 별 10개짜리 개인 프로젝트와 별 50,000개짜리 프로덕션 저장소를 같은 것으로 취급했다는 점을 인정했습니다. 이번에는 반대쪽 끝에서 시작했습니다. 코딩 에이전트를 위한 지침을 제공하는, 영어로 된 별점 상위 10,000개 저장소입니다. 잘 알려진 저장소를 열어 그들이 AGENTS.md를 어떻게 작성했는지 본 적이 있다면, 바로 이런 파일들을 보고 있었던 것입니다.
저장소 10,000개. 에이전트 설정 15,237개. 2026년 9월에 읽었고, 여러분 자신의 저장소에서도 실행할 수 있는 동일한 ails check로 점수를 매겼습니다.
짧게 요약하면 - 저장소의 91.1%는 모호한 지시를 적어도 하나 포함합니다. 에이전트에게 무엇을 하라고 지시하는 문장들 가운데 약 3분의 1이 모호합니다. - 모호함은 여러 발견 항목 중 가장 흔합니다. 저장소의 96.6%에서 적어도 하나의 발견 항목이 나타나며, 중간값 저장소에서는 38개입니다. - 별 개수는 점수를 예측하지 못합니다(9,674개 저장소 기준 스피어만의 rho -0.028). - 하위 에이전트 파일의 점수가 가장 낮습니다. 이들 중 19.6%가 5점 미만이며, 메인 파일은 6.8%입니다. - 에이전트 훅으로 지침을 뒷받침하는 저장소는 7.6%뿐입니다.
저장소의 91%는 적어도 하나의 모호한 지시를 포함합니다
한 인기 있는 Python 프로젝트의 AGENTS.md 하나는 386줄에 이르며, 그 대부분은 꼼꼼하게 작성되어 있습니다. 에이전트가 찾아볼 수 있도록 requirements.txt, torch.inference_mode, 그리고 이 프로젝트의 수많은 자체 모듈을 명시합니다. 또한 의존성에 관해 두 가지 규칙이 있습니다:
둘 다 타당합니다. 두 번째 규칙은 에이전트에게 열어볼 파일과 시험할 조건을 제시합니다. 첫 번째 규칙은 absolutely necessary가 무엇인지 작업 도중 에이전트가 스스로 판단하도록 남겨 두며, 파일 안에는 그 판단을 검증할 근거가 전혀 없습니다.
ails check는 첫 번째 규칙을 CORE:C:0042 , 즉 모호한 지시로 표시합니다. 이는 파일·명령어·도구를 하나도 언급하지 않는 지시나 제약이, 다른 줄들이 파일·명령어·도구를 언급하는 섹션에 있는 경우를 뜻합니다. 두 번째 규칙은 통과합니다.
다른 인기 저장소의 Copilot 지침도 같은 종류의 판단을 요구합니다:
선택지가 있을 때는 더 성능이 좋은 해법을 선택하고, CPU 사이클을 덜 쓰기 위해 RAM 사용을 맞바꾸라
어느 선택지인가요? 무엇을 기준으로 측정하나요? 에이전트가 결정하고, 여러분은 diff를 읽어 보며 그 결과를 알게 됩니다.
검사 가능한 설정이 있는 9,776개 저장소 중 8,910개가 적어도 하나의 CORE:C:0042를 포함합니다(91.1%).
체커는 이 발견 항목을 655,791번 기록했습니다. 이 파일들에 들어 있는 내용의 3분의 2는 설명하거나 보여 주는 것이고, 3분의 1만이 에이전트에게 무엇을 하라고 지시합니다. 지시와 제약만 세어 보면, 약 3개 중 1개가 모호합니다.
모호한 지시는 가장 흔한 발견 항목이며, 유일한 항목도 아닙니다. 저장소의 96.6%는 어떤 종류로든 적어도 하나의 발견 항목을 가지고 있고, 중간값 저장소에서는 38개이며, 다른 네 가지 검사도 저장소의 60% 이상에서 발동합니다.
별점은 점수를 예측하지 못합니다
모든 파일과 모든 설정은 ails check가 읽을 때 0에서 10까지의 점수를 받으며, 이는 모든 발견 사항을 바탕으로 계산됩니다( 점수 계산 방식 ). 인기가 더 나은 지침을 샀다면, 점수는 별점과 함께 올라갔을 것입니다. 별 493개부터 454,882개까지, 그 추세선은 평평합니다.
별점과 점수의 Spearman's rho는 9,674개 저장소에서 -0.028입니다. 별점은 변동의 0.1%도 설명하지 못합니다. 저장소를 별점 기준으로 같은 크기의 10개 그룹으로 나누면 모든 그룹이 같은 자리에 놓이며, 63%에서 66%의 저장소가 7점 이상을 받습니다. 별점이 가장 많은 상위 10분위, 즉 별 12,849개 이상인 그룹은 가장 적은 하위 10분위보다 평균이 약간 더 낮습니다.
유명한 저장소의 AGENTS.md도 다른 누구의 것과 마찬가지로 점수가 매겨집니다. 하나를 복사한다면, 먼저 한 줄씩 읽어보세요.
다음은, 어떤 에이전트를 위해 작성하느냐가 이 그림을 바꾸는지입니다.
누가 어떤 에이전트를 위해 작성하는가
두 가지 설정이 압도적으로 많습니다: AGENTS.md가 62.6%의 저장소에 있고, Claude Code가 61.6%의 저장소에 있습니다. 그다음은 GitHub Copilot이 17.9%이고, Cursor, Gemini, Codex가 뒤를 잇습니다. 4,213개 저장소(43.1%)는 둘 이상의 에이전트를 위해 작성하며, 가장 흔한 조합은 Claude Code와 AGENTS.md의 쌍입니다(2,399개 저장소).
형식은 무엇으로 이루어졌는지도 서로 다릅니다. Gemini를 제외한 모든 에이전트에서 스킬이 파일의 가장 큰 비중을 차지하며, 규칙 파일이 메인 파일보다 많은 유일한 경우는 Cursor입니다.
그 안에 들어 있는 내용의 품질은 에이전트 사이에서 거의 달라지지 않습니다. 모호한 지침의 비율은 어떤 에이전트를 위해 파일이 작성되었든 100개 지침 중 32개에서 36개 사이에 머뭅니다.
| 에이전트 | 설정 수 | 모호한 지침이 있는 경우 | 100개당 모호한 지침 | 5점 미만 |
|---|---|---|---|---|
| Claude Code | 6,030 | 87.4% | 33.7 | 5.3% |
| AGENTS.md (공유) | 6,125 | 91.0% | 32.5 | 5.0% |
| GitHub Copilot | 1,756 | 94.4% | 34.6 | 4.8% |
| Cursor | 734 | 93.2% | 33.4 | 9.6% |
| Gemini (Antigravity) | 430 | 91.4% | 34.2 | 8.8% |
| Codex | 162 | 96.3% | 36.0 | 3.1% |
Codex는 .codex/ 폴더가 있는 저장소를 집계하며, 일반적인 AGENTS.md 설정은 공유 행에 포함됩니다.
실제로 차이가 나는 유일한 열은 마지막입니다. Cursor와 Gemini 설정은 나머지보다 5점 미만에 도달할 확률이 약 두 배 높습니다.
숫자가 실제로 달라지는 곳은 설정 안의 파일들 사이입니다.
서브에이전트 파일이 가장 낮은 점수를 받는다
서브에이전트 파일은 메인 에이전트가 작업을 넘겨주는 전문 역할을 정의합니다: 리뷰어, 디버거, 테스트 작성자 같은 역할입니다. 낮은 점수가 쌓이는 곳이 바로 그 파일들입니다. 서브에이전트 파일의 19.6%가 5점 미만인 반면, CLAUDE.md와 AGENTS.md 같은 메인 파일은 6.8%에 그쳐 거의 세 배 차이가 납니다. 명령과 프롬프트(13.9%), 규칙(13.6%), 스킬(12.1%)은 그 중간에 있습니다.
가장 큰 세 개의 서브에이전트 폴더는 모두 메인 파일 비율을 넘어서며, 그중 Claude Code의 것이 가장 나쁩니다: 서브에이전트 파일 네 개 중 거의 하나가 5점 미만입니다.
서브에이전트 파일은 가장 복잡한 경우도 많습니다. 중앙값 기준으로 하나당 지시문이 19개인데, 메인 파일은 12개입니다.
대규모 TypeScript 모노레포에 있는 한 Copilot 버그 수정 서브에이전트의 점수는 3.9입니다. 품질 게이트는 다음과 같습니다.
게이트는 네 개지만, 파일의 212개 줄 어디에도 그것들을 실행하는 명령은 없습니다. 에이전트는 이 모노레포가 테스트하고, 린트하고, 타입 검사를 하고, 빌드하는 방식을 스스로 파악해야만 그중 하나라도 따를 수 있습니다.
다른 널리 알려진 저장소의 Claude Code 디버깅 서브에이전트는 3.6점을 받습니다. 열려 있는 내용은 다음과 같습니다.
당신은 디버깅을 추측이 아니라 과학적 과정으로 다루는 소프트웨어 디버깅 전문가입니다.
41줄 안에서 프로젝트를 이름으로 언급하는 파일은 CODE_DEBUGGING_SESSION.md뿐인데, 이는 작성하라고 지시받은 보고서입니다. 그 안에는 자신이 속한 프로젝트에 대한 내용이 전혀 없어서, 어떤 저장소에서든 똑같이 읽힐 것입니다. 또 대부분의 서브에이전트가 그렇듯, 해당 줄도 들어 있습니다. 서브에이전트 파일의 57.4%에는 "You are a", "You are an", 또는 "You are the"로 시작하는 줄이 있습니다.
자신의 파일을 확인하려면 npx @reporails/cli check를 실행하고, .claude/agents/, .github/agents/ 또는 .codex/agents/ 폴더에 대한 파일별 점수를 읽어 보세요.
7.6%의 저장소만이 훅으로 지시문을 뒷받침합니다
위의 내용은 모두 에이전트가 따를 수도 있고 따르지 않을 수도 있는 지시문에 관한 것입니다. 훅은 다릅니다. 훅은 에이전트의 하니스가 도구 호출 전과 같은 정해진 순간에 실행하는 스크립트로, 지시문이 요청만 할 수 있는 것을 차단할 수 있습니다. (Prompts steer, hooks enforce는 긴 버전입니다.)
9,784개 저장소 중 746개(7.6%)가 어떤 형태로든 에이전트 훅을 제공합니다. 훅은 Claude Code에 가장 많이 있습니다. 6,030개 설정 중 591개(9.8%)가 하나를 갖고 있습니다. Cursor는 4.9%, Copilot은 1.3%, Gemini는 0.9%입니다.
나머지 92%에서는 에이전트 자체 수준에서 지시문이 지켜졌는지 확인하는 장치가 없습니다.
4월과 일치했던 점
4월의 28,721개 저장소는 GitHub 검색에서 가져왔습니다. 이번 분기의 10,000개는 별표 수가 가장 많은 저장소이며, 더 최신 버전의 검사기로 읽었기 때문에 비교는 규모가 아니라 방향에 관한 것입니다.
| 4월 (28,721개 저장소) | 2026년 3분기 (별표가 가장 많은 10,000개) |
|---|---|
| 프로젝트의 37%는 에이전트를 두 개 이상 설정함 | 유지됨. 저장소의 43.1% |
| 중앙값 지시 파일: 항목 50개, 그중 12개가 지시문 | 유지됨. 중앙값 메인 파일: 항목 55개, 지시문 12개 |
| AGENTS.md가 가장 흔한 지시 파일 | 유지됨. AGENTS.md(11,248개)가 여전히 CLAUDE.md(8,838개)보다 많음; SKILL.md(13,361개)는 이제 둘 다를 앞섬 |
| Cursor 설정은 규칙이 많은 편임 | 유지됨. Cursor 규칙 파일(1,820개)이 Cursor 메인 파일(1,260개)보다 많음 |
| 서브에이전트는 지시문을 가장 많이 담음 | 유지됨. 서브에이전트 파일당 중앙값 19개, 메인 파일은 12개 |
| 서브에이전트는 거의 전부 페르소나 프롬프트임 | 대부분 유지됨. 57.4%가 "You are a/an/the"로 시작하는 줄을 가짐 |
| code-reviewer.md가 가장 흔한 서브에이전트임 | 유지됨. 여전히 가장 흔하며, 41개 저장소에 있음 |
| 89.9%의 설정에는 모호한 지시가 포함됨 | 유지됨. 저장소의 91.1% |
| 가장 많이 복사된 스킬일수록 가장 모호함 | 유지되지 않음. 얼마나 널리 복사됐는지와 얼마나 모호한지 사이의 관련성 없음(5개 이상의 저장소에 복사된 스킬 188개) |
측정 방법
- 표본. Claude Code, Codex, Copilot, Cursor 또는 Gemini용 지시 파일을 제공하는 저장소 중에서, 별표 수 기준으로 위에서부터 뽑은 영어권 GitHub 저장소 10,000개입니다. Claude Code, Codex, Copilot, Cursor 또는 Gemini . 별표 수는 493개에서 454,882개까지이며, 중앙값은 1,551입니다. 파일은 2026년 9월 스냅샷입니다.
- 무엇을 읽었는가. 우리는 모든 저장소를 그 코드 에이전트가 읽는 방식 그대로 읽었습니다. 각 에이전트가 기본으로 불러오는 지시 파일들을, 문서가 지정한 정확한 이름과 경로로 읽었습니다. 즉
CLAUDE.md,AGENTS.md, 규칙, 스킬, 하위 에이전트와 명령이며, 9,784개 저장소의 15,237개 에이전트 설정 전부에 걸쳐 확인했습니다.
- 임포트. 스냅샷 안에 대상이 있는 Claude Code
@path임포트의 텍스트는 임포트한 파일의 일부로 읽습니다. 앞에 점 디렉터리(@.github/…)를 붙여 쓴 임포트는 인식되지 않으며 그대로 문자 그대로 남습니다.
- 범위 밖. 저장소 코드와, 에이전트가 링크를 따라 열었을 때만 읽는 문서들은 제외했습니다.
- 채점기. 모든 점수는 동일한
ails check파이프라인에서 나왔으며, 이는 자신의 저장소에서 직접 실행할 수 있습니다 .
- 분모. 91%와 같은 저장소 비율은 점검된 설정이 있는 9,776개 저장소를 기준으로 셉니다. 대략 3개 중 1개라는 모호한 비율은 해당 설정 안의 지시와 제약을 기준으로 계산하며, 1,894,268개의 지시 중 655,791개의 발견이 있었습니다. 점수 수치는 점수가 산출된 9,674개 저장소를 셉니다.
- 수치에 포함되지 않은 항목. 가장 큰 에이전트 설정 158개(지시 파일이 90개를 넘는 경우, 전체 설정의 약 1%)는 이 수치에 포함되지 않았습니다. 이 중 77개는
ails check가 현재 점수화할 수 있는 10,000 지시 단위를 넘고, 2개는 시간 제한을 초과했습니다. 이들은 스킬과 규칙 라이브러리이며, 192개 파일에 걸쳐 중앙값 15,027 단위를 가집니다. 나머지 79개는 이 수치가 고정된 뒤 점수화되었으며, 데이터셋 업데이트에 추가될 예정입니다.
- 258개의 설정에는 지시나 제약이 없습니다(모든 줄이 설명문이거나, 파일이 비어 있음). 그래서 채점기는 이들에 대해 점수를 반환하지 않습니다.
- 18개의 설정은 점검할 수 없었습니다. 8개는 같은 10,000단위 한도를 넘었고, 10개는 채점 중 오류가 발생했습니다.
- 76개 저장소에서는 하위 폴더의 파일들(하위 에이전트, 명령, 훅)을 9월 스냅샷에 정확히 맞춰 고정할 수 없어, 이미 보유한 파일들을 기준으로 측정했습니다.
- 무엇을 측정하는가. 에이전트가 무엇을 했는지가 아니라, 지시문이 어떻게 작성되었는지를 측정합니다.
자신의 파일을 검사해 보세요
여기까지 와서 누구의 AGENTS.md를 복사해야 하는지 찾으셨다면: 별점 수는 알려주지 않으니, 대신 줄을 읽으세요. 아니면 검사기가 읽게 하세요. 우리가 10,000개 전체에 대해 실행한 것과 같은 검사를 실행하려면 :
npx @reporails/cli check이 도구는 파일별로 발견 사항을 줄 번호와 함께 나열하고, 각 파일에 대해 0에서 10까지의 점수 를 제공합니다. 대부분의 저장소에서 보이는 세 가지 발견부터 살펴보세요. 파일, 명령, 도구를 하나도 지정하지 않은 지시문(CORE:C:0042), 너무 짧아서 등록되지 않는 지시문(CORE:E:0004), 그리고 조건을 완화해 둔 지시문, 즉 "should"와 "try to" 유형(CORE:C:0043)입니다.
이 수치의 근거 데이터는 reporails/reports의 2026-Q3 폴더 에서 공개됩니다. 어떤 발견에 동의하지 않는다면, 행 수를 세어 보세요.
이 시리즈의 다음 편
같은 10,000개 저장소에서 나온 한 가지 습관씩을 다루는 더 짧은 글 4편이 앞으로 며칠에 걸쳐 이어집니다.
/init헤더. 1,604개 저장소(16.4%)는 아직도 Claude Code의/init이 작성하는 줄로 시작하며, 그것이 없는 저장소보다 더 높은 점수를 받습니다.
- "You are…" 285개의 메인 파일이 "You are a…" 줄로 에이전트에게 자신이 누구인지 알려 줍니다. 이들은 어떤 파일 크기에서도 더 낮은 점수를 받습니다.
- 습관들. 저장소의 3분의 1에서 ALL-CAPS를 쓰고, 이모지, "please", TODO, 그리고 129,121단어짜리 메인 파일이 있습니다.
- 숨겨진 귀속. 약 400개 저장소는 에이전트가 자신의 작업에 대한 공로를 가져가지 말라고 지시합니다.
출처
- 원문: https://dev.to/reporails/the-state-of-ai-instruction-quality-q3-2026-19bg (2026-10-13 · Gábor Mészáros)