# AI agent context

> How inspect.software measures agent guidance — CLAUDE.md, AGENTS.md, Cursor rules, Copilot instructions, llms.txt, and whether the commit history states its intent. Part of the AI Readiness badge.


**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](/wiki/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](/wiki/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](/wiki/security-posture).

## Improving the value

- Write a substantive `CLAUDE.md` or `AGENTS.md`: build and test commands,
  layout, conventions, and known pitfalls. Keep it current — it is
  documentation with an executable audience.
- Add an `llms.txt` indexing 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](/wiki/ai-verify-loop) ·
[AI Readiness](/wiki/ai-readiness)