Quick Checklist (12 Checks)
Fast triage for any AGENTS.md/CLAUDE.md root file.
Scoring: Yes = 1, No = 0, N/A = exclude from denominator. Target: >= 10/12 (or equivalent with N/A).
- Core run/test/build/lint commands exist when applicable
- Commands appear runnable and match project scripts/tooling
- Setup/bootstrap requirements are documented
- At least one project-specific gotcha is documented
- Gotchas include corrective action (what to do instead)
- Conventions that change implementation choices are explicit
- Every line passes the litmus test: removing it would cause the agent to make mistakes
- Root file avoids framework doc dumps/templates
- Linked paths and commands are current (not stale/dead)
- Non-universal detail lives where it loads on demand (nested file, path-scoped rule, skill, or a plain link), and anything every tool must obey stays inline in root rather than behind an
@import - Rules are phrased as the outcome wanted, with absolutes reserved for safety, data loss, format contracts, and observed failures
- Nothing restates harness or model default behavior, and no rule conflicts with a parent file or an installed skill
Quick grade:
- Pass: >= 10
- Borderline: 8-9, escalate to the full criteria
- Fail: <= 7, escalate to the full criteria; likely needs the refactor workflow
Automatic fail regardless of score:
- Commands are mostly broken/stale
- Content is mostly generic advice, template text, or restatements of default agent behavior
- The intended tool does not load the shared instructions: check Claude Code version, built-in mod, Project instructions mode, and leftover project Claude files; absence of a CLAUDE.md wrapper is not a failure