The rules I actually run in my own repos with AI coding agents (Cursor, Claude Code, etc.).
Copy this into AGENTS.md, CLAUDE.md or .cursor/rules/ and adapt it to your stack.
Propose options, then wait. When there's more than one way to build it, list the options with tradeoffs and let me pick.
Why: the agent writes the code, but you own the design.
No strong reason? Pick boring. Simple, explicit, hardcoded values or enums beat clever abstractions.
Why: boring code is easy to read, test and delete later.
Plan first, small slices. Write a one-line task list before coding. More than ~5 files? Stop, propose a split, ask which piece is today's.
Why: big changes break many tests at once and are hard to review.
Park the rest. Leftovers and "not now" ideas go to a backlog file, not into this change.
Why: scope creep is how a 1-hour task becomes a broken weekend.
Test first, and agree on how deep. Ask how much testing this change needs (none / one test / edge cases / full). Write the failing test before the code.
Why: a test you write after the code just confirms what the code already does.
Green or it doesn't ship. Refactor only on a green suite. CI runs every test, and deploy waits for all of them.
Why: a deploy that can skip the gate will skip it on the worst day.
Never touch my running environment. Don't start, stop or kill dev servers or databases. Never fix the database by hand: schema changes go in a new migration file, and you never edit one that already ran.
Why: you lose context the agent can't see, and edited migrations break every environment.
Commit only when asked, and only your own files. Other agents may be in the same repo. Never git add -A, never revert, stash or discard someone else's changes. Conventional commit messages, and the body explains why.
Why: a "cleanup" can wipe out another agent's work.
Secrets stay off screen. Never print keys, tokens, .env values or passwords. Point to the variable name, or stop and ask before showing anything sensitive.
Why: logs, chats and screen recordings leak.
Read the handoff, keep it short. At a cold start, read HANDOFF.md (how to run/test, map, decisions, next). Update it only when asked: telegraphic, hard line cap, facts not diary.
Why: a new session starts with zero memory, and a bloated handoff gets ignored.
When something bites twice, write a rule. Turn every repeated bug into a scoped rule with the checklist that prevents it.
Why: the agent won't remember the last time it broke. The rules file will.