ai-coding-rules

ai-coding-rules

Opinionated rules and prompts for every major AI coding assistant — drop one file into your repo and hold your assistant to the same disciplined workflow in every session.

AI coding tools are capable but eager. Left to their defaults they'll happily declare a change "done" the moment it typechecks, quietly widen the scope of a diff, or invent a config key that looks right. This repo is a set of small, ready-to-use rules files that hold them to a stricter standard — the same one across Claude Code, Cursor, Copilot, Cody, Windsurf, and Continue.

Every file here encodes one idea:

A change isn't done when it compiles. It's done when you've watched it do the right thing and a skeptic couldn't poke a hole in it.

That's it. Copy the file for your tool, and you're set.

Why rules matter

A model's default behavior drifts — between sessions, between tasks, and especially between tools. One day it writes tight, scoped diffs; the next it refactors three files you didn't ask about. A rules file is how you stop re-explaining your standards every single prompt.

• Consistency across sessions. The discipline is applied on every request, not just when you remember to ask for it.
• Consistency across tools. These files all encode the same five gates, so switching from Cursor to Claude Code doesn't mean re-teaching your expectations.
• Fewer bad surprises. Plan first, keep diffs small, actually verify, review like a skeptic, and report honestly — the failure modes that waste your afternoon get caught before they reach you.
• It's just a file. Version-controlled, reviewable, editable. Tune it to your stack and it travels with the repo for the whole team.

The five gates, in one breath: plan before editing → match the house style → verify by exercising the change → self-review as an adversary → report honestly what you did and didn't check.

What's inside

Each tool gets its own file in its own folder. Copy it to the path in the last column, at your project's root.

Each file carries a placement note — explaining exactly where it goes and how that tool loads it — and marks where your stack, commands, and conventions go, so the project-specific bits win over the general discipline. (Some notes sit at the top, some in a comment at the bottom.) Tool rule systems evolve, so the notes point you at the current docs in case a path or format changes.

Quick start

# Example: Claude Code
cp claude-code/CLAUDE.md /path/to/your-project/CLAUDE.md

# Example: Cursor
cp cursor/.cursorrules /path/to/your-project/.cursorrules

Then open the copied file and replace the <PLACEHOLDER> markers with your real commands (install, test, build) and any rules specific to your codebase. Commit it. Done.

Prompt library

Rules set the default behavior. For steering a specific task, there are tool-agnostic, copy-paste prompts that pair with the same discipline.

The prompts/ folder has four focused files:

• plan-a-change.md — force a plan and surface the riskiest assumption before any code is written.
• find-root-cause.md — diagnose the actual cause of a bug instead of patching the symptom.
• review-this-diff.md — get an adversarial review of a diff, not a rubber stamp.
• write-tests.md — cover the behavior and the failure paths, in your existing test style.

For a wider set, PROMPTS.md is a single-file library of a dozen prompts covering the same ground plus root-causing bugs, safe refactors, security hardening, dependency upgrades, and PR descriptions.

Paste any of them into any assistant, fill in the bracketed placeholders, and go.

Go deeper

These rules are intentionally small. If you want more depth — especially on Claude Code:

• Guide: claude-code-guide — a free walkthrough of getting real work done with Claude Code.
• Starter: claude-code-starter — a free, MIT-licensed project template to build on top of these rules.

If you end up wanting the full setup, there's a Claude Code Pro Pack with skills, subagents, and workflows — a paid kit for people who've outgrown a single rules file. Everything in this repo stays free and is enough on its own; the Pro Pack is there only if you want it.

Contributing

Improvements welcome — a sharper rule, a fix for a tool whose config format changed, a new tool folder that follows the same five-gate structure. Keep it practical and keep it honest; no hype, no filler. Open an issue or a PR.

License

MIT. Use it, fork it, adapt it for your team. No attribution required.