What are AI coding rules files?

A rules file is a plain markdown document at the root of your project that tells your AI coding assistant what your project is, how it's built, and how it expects you to work. Every modern AI tool reads one.

Why every AI tool needs one

AI coding assistants are good at writing code in the abstract. They're only as useful as the context you give them about your specific codebase. A rules file at the repo root tells the model the things it can't infer from one file: which framework version you're on, where files go, what naming conventions you follow, what patterns you prefer, what patterns you've already tried and rejected.

Without it, the AI guesses. It uses Pages Router conventions when you're on App Router; it imports a default export when your project uses named-only; it adds a class component to a codebase that has been functional for two years. Each correction wastes a turn — and a turn you spend correcting is a turn you don't spend building.

The supported tools and their files

Each AI tool reads its own file at its own path. The content is 90% the same across all of them — the differences are mostly cosmetic.

What separates a good rules file from a bad one

Bad rules files are platitudes — "write clean code," "follow best practices," "use TypeScript." The model already knows. Good rules files are opinionated and specific to the project: which framework version, where files go, which library is forbidden, which patterns the team has already tried and rejected.

Good rules files also include behavioral rules for the AI itself. "Ask before installing dependencies." "Run the linter and tests before considering a task complete." "Never modify migrations after they're committed." These are project policies the model would otherwise violate confidently.

How long should it be?

150–500 lines for most stacks. Copilot tolerates roughly 200 lines before truncating; Claude tolerates around 600. Cursor and Windsurf are in between. The library files in this tool target 250–400 lines as a sweet spot — long enough to cover real conventions, short enough to fit in every tool's budget.

Should it be committed to git?

Yes. It's project documentation that benefits every developer using the AI tool. The exception is personal-global instructions (e.g. ~/.claude/CLAUDE.md) which are user-scoped and stay out of the repo.

Where to start

Three options: