Agent context

Question: Does a section restate what the repository’s files show, give generic advice, repeat what linters check, or record past work?

• Runs: when selected: --rule agent-context, --rule documentation or --rule all · Fails the check by default: considers, once selected
• Right on projects JevGate was never tuned on: considers 92% (22 of 24) (how it is measured)
• Right on the projects it was tuned on: considers 94% (64 of 68)
• Looks at: agent instruction files that a harness loads: AGENTS.md, CLAUDE.md, GEMINI.md, and Claude, Cursor, Copilot, Windsurf and Cline rules
• Evidence unit: one file’s heading sections, with the repository’s manifests, linters and directories
• Acceptable: Project-specific commands, constraints, decisions and workflows the code does not show
• Names: documentation/agent-context, agent-context, agent_context · Version: 3

When a finding is right

A finding says a section of an instruction file, which coding agents load at the start of every session, restates what the repository’s files show, gives generic advice, repeats what a configured linter checks, or records past work. It is right when an agent would learn the same from the code: the stack, the manifest’s commands, a tour of the directories, a changelog kept in CLAUDE.md. It is wrong when the section tells agents something the files do not show, or when it is a pointer to a detailed document that costs a few tokens. Most of the findings labeled wrong or debatable were sections so short they cost almost nothing.

A section of fewer than 15 tokens is a note. Agent-context considers are the one documentation level that fails the check by default once these rules run; 23 of their 24 labels on unseen projects come from the maintainer’s own repositories.

Findings it got wrong

Labeled wrong by reading the code, on open-source projects the rules were tuned on.

shiori: .cursorrules

• Where: .cursorrules:3 in go-shiori/shiori at 9a9a426.
• Finding (consider): Section Run the entire test suite restates what the repository’s files show; only lists commands the manifests already show. Cursor and Cline load it at the start of every session (about 4 tokens).
• Why it was wrong: The section is one line, make unittest, about 4 tokens. The target is in the Makefile, but the line sends agents to the target that adds the race detector and the right build tags instead of a bare go test; removing it saves nothing.
• Since: a note since 0.21.0, which makes a section of fewer than 15 tokens a note (changelog).

cookiecutter-django: What This Project Is

• Where: AGENTS.md:5 in cookiecutter/cookiecutter-django at 1ec1d82.
• Finding (consider): Section What This Project Is only describes the project, which agents read from its files. Codex, GitHub Copilot, Cursor, Windsurf, Cline and Claude Code load it at the start of every session (about 79 tokens).
• Why it was wrong: The section says the repository is not a Django application but a Jinja2 template whose {{cookiecutter.project_slug}}/ files Cookiecutter renders. That framing keeps agents from running Django commands at the root or “fixing” the template tags in .py files, and at 79 tokens it is worth keeping.
• Since: not addressed; reported the same way from 0.20.0 through 0.25.0.