AI 지침 품질 현황: 2026년 3분기

GitHub에서 가장 많은 별을 받은 레포지토리 중 91%가 코딩 에이전트에게 어떤 파일, 명령어 또는 도구를 의미하는지 명확히 밝히지 않은 지침(instruction)을 최소 하나 포함하고 있습니다.

지난 4월에는 28,721개의 레포지토리를 측정했으며, 저희의 자체 제한 사항 섹션에서는 10스타 사이드 프로젝트가 50,000스타 프로덕션 레포와 동일하게 계산된다고 인정했습니다. 이번에는 다른 쪽 끝에서 시작했습니다. 즉, 코딩 에이전트를 위한 지침을 배포하는 상위 10,000개 영어권 레포지토리입니다. 만약 잘 알려진 레포를 열어 AGENTS.md가 어떻게 작성되었는지 확인해 본 적이 있다면, 바로 이 파일들을 보고 계신 것입니다.

레포 10,000개. 에이전트 설정 15,237개. 2026년 9월에 읽었으며, 여러분의 레포지토리에서 실행할 수 있는 동일한 ails check로 점수를 매겼습니다.

요약

• 레포지토리의 91.1%가 최소 하나 이상의 모호한 지침을 가지고 있습니다. 에이전트에게 무엇을 할지 알려주는 줄 중에서 약 3분의 1이 모호합니다.
• 모호함(Vague)은 여러 항목에서 가장 흔하게 발견되는 결과입니다: 레포의 96.6%가 최소 하나 이상의 결과를 가지고 있으며, 중앙값 레포에서는 38개였습니다.
• 별 개수는 점수를 예측하지 못합니다 (9,674개 레포에 걸쳐 Spearman's rho -0.028).
• 서브 에이전트 파일의 점수가 가장 낮습니다: 메인 파일 대비 19.6%가 5점 미만이며, 이는 6.8%였습니다.
• 레포지토리 중 단지 7.6%만이 지침을 에이전트 후크(agent hook)로 뒷받침합니다.

레포의 91%가 최소 하나 이상의 모호한 지침을 포함하고 있습니다

인기 있는 Python 프로젝트의 AGENTS.md 파일은 386줄에 달하며, 대부분이 신중하게 작성된 내용입니다. 이 파일은 에이전트가 참조할 수 있도록 requirements.txt, torch.inference_mode 및 수십 개의 자체 모듈을 명시합니다. 또한 의존성에 관한 두 가지 규칙도 가지고 있습니다.:

An AGENTS.md from a popular Python project, lines 11 to 12:

둘 다 합리적입니다. 두 번째 방식은 에이전트에게 열 파일과 테스트할 조건(condition)을 제공합니다. 첫 번째 방식은 '절대적으로 필요하다(absolutely necessary)'는 판단을 에이전트가 작업 중간에 스스로 내리도록 남겨두며, 그 호출 내용을 확인할 파일도 없습니다.

ails check는 첫 번째 방식을 CORE:C:0042라는 모호한 지침(vague instruction)으로 플래그 지정합니다. 이는 다른 줄들이 파일, 명령어 또는 도구를 명시하는 섹션에서 아무것도 명시하지 않은 지시사항이나 제약 조건입니다. 두 번째 방식은 통과합니다.

다른 인기 있는 저장소의 Copilot 지침도 비슷한 종류의 판단을 요구합니다:

옵션이 있을 때는 더 성능 좋은 솔루션을 선택하고, RAM 사용량을 줄이는 대신 CPU 사이클을 희생하라 (When there is an option, opt for more performant solutions and trade RAM usage for less CPU cycles)

어떤 옵션? 어떻게 측정할까? 에이전트가 결정하며, 그 결정 내용은 diff를 읽어야 알 수 있습니다.

우리가 검사할 수 있는 9,776개의 저장소에서 8,910개는 최소한 하나의 CORE:C:0042를 가지고 있었습니다 (91.1%).

A grid of 100 squares with 91 filled: 91.1% of 9,776 repos carry at least one vague instruction.

체커는 해당 내용을 655,791번 발견했다고 보고했습니다. 이 파일들에 있는 내용의 3분의 2는 설명하거나, 이유를 제시하거나, 보여주는 것이고; 3분의 1은 에이전트에게 무엇을 할지 지시합니다. 이러한 지침과 제약 조건만을 세어보면 약 3개 중 1개가 모호합니다.

Every 100 items in an instruction file: 66 describe, explain or show; 34 tell the agent what to do, and 11 of those are vague.

모호한 지침이 가장 흔하게 발견되는 내용이며, 유일한 경우는 아닙니다. 저장소의 96.6%가 어떤 종류의 발견 사항을 최소 하나 가지고 있으며, 중앙값(median) 저장소에서는 38개의 문제가 발견되었고, 다른 네 가지 검사 항목은 60% 이상의 저장소에서 작동했습니다.

Share of 9,784 repos with each finding: Specificity Gap, CORE:C:0042, names no file, command or tool, 91.1%; Instruction Elaboration, CORE:E:0004, too short to register, 87.8%; Modality Weakness, CORE:C:0043, hedged, 70.3%; Content Dilution, CORE:C:0041, 62.5%; Direction Imbalance, CORE:D:0002, 61.8%; Topic Overlap, CORE:C:0044, 33.1%.

스타가 점수를 예측하지는 못한다

모든 파일과 fails check로 읽어 들인 모든 설정은 발견된 모든 항목(점수 작동 방식)을 바탕으로 0점에서 10점 사이의 점수를 받습니다. 만약 인기가 더 나은 지침을 만들었다면, 별점과 함께 점수가 상승했을 것입니다. 493개 별점에서 454,882개로 가더라도 이 선은 평평합니다.

9,674개의 리포지토리 전체에서 별점과 점수 간의 스피어만 로(Spearman's rho)는 -0.028입니다: 별점은 변동성의 0.1%도 채 차지하지 못합니다. 리포지토리를 별점으로 열 개의 동일한 그룹으로 나눈 후, 모든 그룹이 같은 위치에 놓이며, 리포지토리의 63%에서 66%가 7점 이상을 기록했습니다. 가장 많은 별점을 받은 상위 10개 그룹(12,849개 별점 이상)은 가장 적게 별점을 받은 하위 10개 그룹보다 평균 점수가 약간 낮습니다.

Share of repos scoring 7 or above, by star decile: flat between 63% and 66% from 493 stars to 454,882.

유명한 리포지토리의 AGENTS.md도 다른 어떤 것과 다름없이 점수를 받습니다. 만약 하나를 복사한다면, 반드시 줄 단위로 먼저 읽어보세요.

다음으로: 직접 작성하는 에이전트가 상황을 바꿀까요?

어떤 에이젠트를 위해 누가 작성하는가

두 가지 설정이 지배적입니다: 리포지토리의 62.6%에서 AGENTS.md를, 그리고 61.6%에서 Claude Code를 사용합니다. Copilot이 17.9%로 그 뒤를 따르고, 그다음으로 Cursor, Gemini, Codex가 있습니다. 4,213개의 리포지토리(43.1%)는 두 개 이상의 에이젠트를 위해 작성되었으며, 가장 흔한 조합은 Claude Code와 AGENTS.md의 쌍입니다(2,399개 리포지토리).

Left: share of 9,784 repos with a setup for each agent, AGENTS.md 62.6%, Claude Code 61.6%, GitHub Copilot 17.9%, Cursor 7.5%, Gemini 4.4%, Codex 1.7%. Right: agents per repo, 1 agent 5,571 repos, 2 agents 3,201, 3 agents 822, 4 agents 152, 5 agents 38.

형식은 구성 요소에서 차이를 보입니다. Gemini를 제외한 모든 에이젠트의 경우 Skills가 가장 큰 파일 비중을 차지하며, Cursor만이 규칙(rule) 파일이 메인 파일보다 많은 유일한 경우입니다.

Share of instruction files by type for each agent. Skills are the largest share for Claude Code (39%), AGENTS.md (51%), Copilot (46%), Cursor (53%) and Codex (63%); Gemini's main files lead at 47%. Cursor's rules (23%) outnumber its main files (16%).

내용의 품질은 에이전트 간에 거의 차이가 없습니다. 모호한 지침(vague instruction) 비율은 파일이 작성된 어떤 에이전트를 기준으로 하든 100개 지침당 32~36% 사이를 유지합니다.

Vague instructions per 100, by agent: every agent between 32 and 36.

변동하는 유일한 열은 마지막 열입니다: Cursor와 Gemini 설정은 나머지 에이전트보다 'Below 5'에 해당하는 경우가 약 두 배 더 많습니다.

숫자가 변하는 곳은 설정 내부의 파일들 사이입니다.

서브-에이전트 파일 점수가 가장 낮음

서브-에이전트 파일(sub-agent file)은 메인 에이전트가 작업을 위임하는 전문가를 정의합니다: 검토자(reviewer), 디버거(debugger), 테스트 작성자(test writer). 이러한 파일에서 낮은 점수들이 쌓이고 있습니다. 서브-에이전트 파일의 19.6%가 5점 미만의 점수를 받은 반면, CLAUDE.md나 AGENTS.md 같은 메인 파일은 6.8%로 거의 세 배 적습니다. 명령어 및 프롬프트(commands and prompts)는 13.9%, 규칙(rules)은 13.6%, 기술(skills)은 12.1%를 차지합니다.

Share of files scoring below 5, by file type: sub-agents 19.6%, commands and prompts 13.9%, rules 13.6%, skills 12.1%, main files 6.8%.

가장 큰 세 개의 서브-에이전트 폴더 모두 메인 파일 비율보다 높게 나타났으며, Claude Code의 것이 가장 나쁩니다: 그 서브-에이전트 파일 중 거의 4분의 1이 5점 미만의 점수를 받았습니다.

Share of sub-agent files scoring below 5, by folder: .claude/agents 22.9% of 1,914 files, .codex/agents 19.9% of 181, .github/agents 10.9% of 671, against 6.8% of 25,095 main files.

서브-에이전트 파일은 또한 가장 많은 작업을 처리합니다. 중앙값(median) 기준으로 서브-에이전트 파일은 19개의 지침을 담고 있는 반면, 메인 파일은 12개입니다.

한 Copilot 버그 수정 서브 에이전트는 대규모 TypeScript 모노레포에서 3.9점을 받았습니다. 이 에이전트의 품질 게이트는 다음과 같습니다:

A Copilot bug-fixing sub-agent in .github/agents/, lines 37 to 41:

네 개의 게이트가 있지만, 파일의 212줄 어디에도 이들 중 어떤 명령어도 없습니다. 에이전트는 단 하나의 명령을 따르기 전에 이 모노레포가 어떻게 테스트하고(tests), 린트(lints)하며, 타입 검사(type-checks)하고 빌드하는지 알아내야 합니다.

또 다른 유명한 레포의 Claude 코드 디버깅 서브 에이전트는 3.6점을 받았습니다. 이 에이전트는 다음과 같이 시작합니다:

당신은 디버깅을 추측이 아닌 과학적 과정으로 다루는 전문가 소프트웨어 디버거입니다.