{
  "version": "1.0.1",
  "updated": "2026-07-14",
  "rules": [
    {
      "id": "lint-leakage",
      "name": "Lint leakage",
      "severity": "warn",
      "weight": 3,
      "maxPenalty": 15,
      "evidenceTier": "measured",
      "evidenceUrl": "https://arxiv.org/abs/2606.15828",
      "lastVerified": "2026-07-14",
      "summary": "Style rules a linter or formatter already enforces. Found in 62% of mined AGENTS.md files; never send an LLM to do a linter's job.",
      "recommendation": "Delete the rule and point to the linter instead, e.g. \"run `eslint --fix`; the linter config is the source of truth.\"",
      "scope": "file"
    },
    {
      "id": "directory-tree",
      "name": "Directory tree / codebase tour",
      "severity": "warn",
      "weight": 5,
      "maxPenalty": 15,
      "evidenceTier": "measured",
      "evidenceUrl": "https://arxiv.org/abs/2602.11988",
      "lastVerified": "2026-07-14",
      "summary": "Repo maps and directory listings increased agent exploration without improving file discovery in the ETH ablation. The agent can run `ls`.",
      "recommendation": "Delete the tree. Keep at most one line per genuinely non-obvious location (\"API handlers live in src/api/handlers/\").",
      "scope": "file"
    },
    {
      "id": "vague-rules",
      "name": "Vague / aspirational rule",
      "severity": "warn",
      "weight": 2,
      "maxPenalty": 12,
      "evidenceTier": "official",
      "evidenceUrl": "https://code.claude.com/docs/en/best-practices",
      "lastVerified": "2026-07-14",
      "summary": "Anthropic's exclude list names self-evident practices like \"write clean code\". Vague words (\"appropriately\", \"best practices\") give the agent nothing testable.",
      "recommendation": "Replace with a concrete, verifiable instruction (exact command, path, or example) or delete the line.",
      "scope": "file"
    },
    {
      "id": "no-commands",
      "name": "No runnable commands",
      "severity": "error",
      "weight": 15,
      "maxPenalty": 15,
      "evidenceTier": "measured",
      "evidenceUrl": "https://arxiv.org/abs/2602.11988",
      "lastVerified": "2026-07-14",
      "summary": "Exact build/test/lint commands are the one content class proven to change agent behavior (tools named in the file get used 1.6x as often). This file has none.",
      "recommendation": "Add a commands section first: exact build, test, and lint invocations with flags, in backticks.",
      "scope": "file"
    },
    {
      "id": "enforcement-prose",
      "name": "Hard rule as advisory prose",
      "severity": "info",
      "weight": 1,
      "maxPenalty": 3,
      "evidenceTier": "official",
      "evidenceUrl": "https://code.claude.com/docs/en/best-practices",
      "lastVerified": "2026-07-14",
      "summary": "\"Unlike CLAUDE.md instructions which are advisory, hooks are deterministic\" (Anthropic). NEVER/ALWAYS rules on mechanically-enforceable behaviors are requests, not laws.",
      "recommendation": "Keep the line if you accept ~advisory compliance; for zero-exception rules add a hook, lint rule, or CI check.",
      "scope": "file"
    },
    {
      "id": "secret-leak",
      "name": "Possible secret",
      "severity": "error",
      "weight": 15,
      "maxPenalty": 30,
      "evidenceTier": "community",
      "evidenceUrl": "https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/",
      "lastVerified": "2026-07-14",
      "summary": "A token-shaped string in an instruction file ships to every agent session and usually to git.",
      "recommendation": "Remove the credential, rotate it, and reference an env var name instead.",
      "scope": "file"
    },
    {
      "id": "emphasis-overuse",
      "name": "Emphasis overuse",
      "severity": "info",
      "weight": 4,
      "maxPenalty": 4,
      "evidenceTier": "community",
      "evidenceUrl": "https://www.humanlayer.dev/blog/writing-a-good-claude-md",
      "lastVerified": "2026-07-14",
      "summary": "IMPORTANT/YOU MUST works because it is rare. Past a handful of uses the emphasis dilutes and nothing stands out.",
      "recommendation": "Keep emphasis on the 1-3 rules that genuinely matter most; demote the rest to plain statements.",
      "scope": "file"
    },
    {
      "id": "pointer-without-instruction",
      "name": "Doc pointers without a read instruction",
      "severity": "warn",
      "weight": 3,
      "maxPenalty": 6,
      "evidenceTier": "community",
      "evidenceUrl": "https://alexop.dev/posts/stop-bloating-your-claude-md-progressive-disclosure-ai-coding-tools/",
      "lastVerified": "2026-07-14",
      "summary": "Progressive-disclosure link lists get ignored unless a load-bearing instruction tells the agent to read them before starting.",
      "recommendation": "Prefix the list with an explicit imperative, e.g. \"IMPORTANT: read the relevant doc below before starting work.\"",
      "scope": "file"
    },
    {
      "id": "size-cost",
      "name": "Length past 200 lines",
      "severity": "warn",
      "weight": 5,
      "maxPenalty": 10,
      "evidenceTier": "heuristic",
      "evidenceUrl": "https://code.claude.com/docs/en/memory",
      "lastVerified": "2026-07-14",
      "summary": "Anthropic's official target is under 200 lines. Honest caveat: a 1,650-session factorial study (arXiv 2605.10039) found no compliance effect from file size — the argument for brevity is token cost (+14-23% per session in the ETH study), not adherence.",
      "recommendation": "Cut code-derivable content first (trees, stack restatements, style rules); push sometimes-relevant knowledge into on-demand docs or skills.",
      "scope": "file"
    },
    {
      "id": "duplicate-rules",
      "name": "Duplicate rule",
      "severity": "warn",
      "weight": 2,
      "maxPenalty": 8,
      "evidenceTier": "official",
      "evidenceUrl": "https://code.claude.com/docs/en/memory",
      "lastVerified": "2026-07-14",
      "summary": "Near-identical instructions accumulate as files grow by accretion; each duplicate spends budget without adding signal.",
      "recommendation": "Keep one occurrence, delete the rest.",
      "scope": "file"
    },
    {
      "id": "contradiction-lite",
      "name": "Contradictory instructions",
      "severity": "error",
      "weight": 5,
      "maxPenalty": 10,
      "evidenceTier": "official",
      "evidenceUrl": "https://code.claude.com/docs/en/memory",
      "lastVerified": "2026-07-14",
      "summary": "Contradictory rules get resolved arbitrarily (Anthropic docs) — the agent follows one and ignores the other, inconsistently.",
      "recommendation": "Pick one convention, delete the other, and let a linter or lockfile enforce it where possible.",
      "scope": "file"
    },
    {
      "id": "boundaries-missing",
      "name": "No boundaries declared",
      "severity": "info",
      "weight": 3,
      "maxPenalty": 3,
      "evidenceTier": "community",
      "evidenceUrl": "https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/",
      "lastVerified": "2026-07-14",
      "summary": "GitHub's 2,500-repo analysis found explicit boundaries (always do / ask first / never do) the strongest single pattern; \"never commit secrets\" was the most commonly helpful constraint.",
      "recommendation": "Add a short boundaries section: what the agent must never do, and what needs asking first.",
      "scope": "file"
    },
    {
      "id": "codex-cap",
      "name": "Exceeds Codex 32 KiB cap",
      "severity": "error",
      "weight": 5,
      "maxPenalty": 5,
      "evidenceTier": "official",
      "evidenceUrl": "https://learn.chatgpt.com/docs/agent-configuration/agents-md",
      "lastVerified": "2026-07-14",
      "summary": "OpenAI Codex stops reading at project_doc_max_bytes (32 KiB default) — everything past the cap is silently truncated.",
      "recommendation": "Cut below 32 KiB, or split into nested per-directory files.",
      "scope": "file"
    },
    {
      "id": "dead-command",
      "name": "Dead command",
      "severity": "error",
      "weight": 5,
      "maxPenalty": 15,
      "evidenceTier": "measured",
      "evidenceUrl": "https://arxiv.org/abs/2602.11988",
      "lastVerified": "2026-07-14",
      "summary": "The file references a script that does not exist in package.json. Agents follow file-named tools 1.6x as often — a dead command sends every session down a broken path.",
      "recommendation": "Fix the command to match package.json scripts, or delete it.",
      "scope": "repo"
    },
    {
      "id": "stale-path",
      "name": "Stale path",
      "severity": "error",
      "weight": 3,
      "maxPenalty": 12,
      "evidenceTier": "community",
      "evidenceUrl": "https://github.com/giacomo/agents-lint",
      "lastVerified": "2026-07-14",
      "summary": "The file references a path that does not exist in the repo. Stale content is the top drift failure mode as code moves and the file doesn't.",
      "recommendation": "Update the path or delete the reference.",
      "scope": "repo"
    },
    {
      "id": "readme-redundancy",
      "name": "Duplicates README",
      "severity": "warn",
      "weight": 2,
      "maxPenalty": 14,
      "evidenceTier": "measured",
      "evidenceUrl": "https://arxiv.org/abs/2602.11988",
      "lastVerified": "2026-07-14",
      "summary": "The ETH ablation's key finding: context files help only when non-redundant with existing docs (+2.7% with docs stripped, ~0 with them present). This line restates the README the agent already reads.",
      "recommendation": "Delete the line; keep only what the README and code cannot tell the agent.",
      "scope": "repo"
    },
    {
      "id": "bridge-missing",
      "name": "Invisible to Claude Code",
      "severity": "warn",
      "weight": 6,
      "maxPenalty": 6,
      "evidenceTier": "official",
      "evidenceUrl": "https://code.claude.com/docs/en/memory",
      "lastVerified": "2026-07-14",
      "summary": "Claude Code reads CLAUDE.md, not AGENTS.md (feature request #6235 is open since Aug 2025). This repo has AGENTS.md with no CLAUDE.md bridge, so the most-used agent never sees it.",
      "recommendation": "Add a one-line CLAUDE.md containing `@AGENTS.md`. A symlink also works for reading; the import is slightly safer because Claude Code refuses to WRITE through symlinks (issue #66559), which only matters if you let it update the file.",
      "scope": "repo"
    },
    {
      "id": "import-resolution",
      "name": "Unresolved @-import",
      "severity": "error",
      "weight": 4,
      "maxPenalty": 8,
      "evidenceTier": "official",
      "evidenceUrl": "https://code.claude.com/docs/en/memory",
      "lastVerified": "2026-07-14",
      "summary": "A CLAUDE.md @-import points at a file that does not exist in the repo, so the import silently loads nothing.",
      "recommendation": "Fix the import path or remove the import.",
      "scope": "repo"
    }
  ]
}