AI agent context measures whether a repository gives AI coding agents guidance and machine-readable documentation. An agent dropped into an unfamiliar codebase faces the same problem as a new hire — except it reads the onboarding material in milliseconds, every session. Projects that write that material down get measurably better agent output.
- Category: AI Readiness (30% within category)
- Weight in overall index: 0% — part of the independent AI Readiness badge
- Metric key:
ai_agent_context
How the value is computed
| Component | Weight | Evidence |
|---|---|---|
| Agent instructions | 45 | CLAUDE.md, AGENTS.md, .cursor/rules, Copilot instructions, GEMINI.md, or equivalent; a file below ~200 bytes registers as a stub and earns partial credit |
| Machine-readable docs | 15 | llms.txt or llms-full.txt present |
| Legible commit history | 40 | share of human commits that state their intent; full marks from 75% upward |
Why the commit history counts
Written guidance is a file someone had to decide to create, and most projects never have. The commit history is different: every project produces one already, and an agent consults it before changing unfamiliar code — to learn why the surrounding decisions were made, not just what the code does.
A commit counts as stating its intent when its subject is structured — in conventional-commit form, or referencing the issue or pull request behind the change — or when its body explains the change rather than restating the subject. Either form qualifies, because either requirement alone would be parochial: the Linux kernel writes no conventional prefixes and almost always explains itself, while other projects run a fully conventional history with one-line messages. Both are legible; both count.
Commits made by automation are excluded, since machine-generated subjects are uniformly well-formed and say nothing about the project's own practice.
What good agent context contains
An effective instruction file tells an agent what the README tells a human, plus what only maintainers know: how to build and test, which directories matter, project conventions, and the traps ("the container serves built images — rebuild after editing"). The llms.txt convention complements it by giving language models a curated index of the project's documentation.
The stub rule exists because presence signals can be gamed: an empty CLAUDE.md created for the badge is detectably different from a real one, and the methodology weights substance where it is cheap to detect.
Reading the result
- Signals are presence- and size-based from the file tree; content is not graded — the honest limit stated across the AI Readiness category.
- Any of the recognized instruction conventions counts; the methodology is vendor-neutral across agent tooling, mirroring the tool-agnostic stance of security posture.
Improving the value
- Write a substantive
CLAUDE.mdorAGENTS.md: build and test commands, layout, conventions, and known pitfalls. Keep it current — it is documentation with an executable audience. - Add an
llms.txtindexing the project's documentation for language-model consumption. - Reference the issue or pull request in commit subjects, or explain the change in the body. Both are ordinary review discipline; both leave the history readable by whoever — or whatever — maintains the project next.
Related: AI verify loop · AI Readiness