A short, honest set of behavioral guidelines for coding agents (Claude Code, Cursor, and similar tools) — the kind of file you drop into a project so the agent thinks, edits, and verifies its own work more carefully.
This isn't a rebrand of anyone else's file, and it isn't claiming any researcher's endorsement. It grew out of a close read of an earlier, very popular file in this space (a CLAUDE.md inspired by public observations Andrej Karpathy posted about LLM coding failure modes) — specifically, out of documenting what that file got right, what it left unverified, and where its own rules quietly contradicted each other. None of that critique is repeated here as attribution; it's just where the design decisions below came from.
Two things we did differently on purpose:
- No borrowed name. The rules here aren't credited to anyone who didn't write them or agree to have their name on them.
- No manufactured stat. We don't claim these rules cut error rates by some percentage. See
EVIDENCE.mdfor exactly what is and isn't backed by anything real.
| File | Purpose |
|---|---|
CLAUDE.md |
The core guidelines — five rules, each producing something checkable. |
EXAMPLES.md |
Each rule applied to a real task, including the one place two rules can conflict. |
EVIDENCE.md |
What's independently supported, what's a guess, and what we explicitly don't claim. |
CURSOR.md |
How to use this with Cursor instead of Claude Code. |
.cursor/rules/plumbline.mdc |
The condensed project-rule version Cursor auto-loads. |
examples/linkcheck/ |
A real project built under these rules, not a hypothetical — includes the actual bug it found and fixed upstream. |
Claude Code: copy CLAUDE.md into your project root, or append its contents to an existing CLAUDE.md.
Cursor: copy the .cursor/rules/ directory into your project. See CURSOR.md for the manual alternative.
- Say the assumption out loud — state it, don't silently resolve it; restate on long sessions.
- Match the size of the problem — not minimum code, right-sized code; use the codebase's existing patterns.
- Touch only what you're asked — and when that conflicts with rule 2, name the tie-break instead of picking silently.
- Make "done" checkable — a test that actually ran, not a diff that looks plausible.
- If it's product-facing, say what "worked" means — beyond the code running, when there's a user on the other end.
Full text with rationale: CLAUDE.md.
MIT — see LICENSE.
If a rule fought you on a real task, that's more useful feedback than a star. Open a PR or an issue describing what happened — see EVIDENCE.md for what this project is trying to avoid (claims nobody can check).