How to write effective AI coding rules
Most AI coding rules files are mediocre. They're either too vague to act on or too long to read. A good one is the opposite: opinionated, specific, current, and short enough to fit comfortably in every tool's context budget.
This is what separates the good ones from the bad ones.
Be specific. The model already knows abstract good practice.
Bad:
Write clean, readable code. Use TypeScript. Follow best practices.
The model knows. What it doesn't know is your project: which version of which framework, where files go, which third-party library you've already evaluated and rejected, which patterns the team has converged on.
Good:
- Next.js 15, App Router only. Never Pages Router.
- Functional components only. No class components.
- Named exports only. Default exports only where Next.js requires (
page.tsx,layout.tsx).- Tailwind for styling. No CSS modules, no styled-components.
- State: TanStack Query for server data, useState for local. No Redux.
Specifics give the model something to act on. Platitudes don't.
Pick a side on debated choices.
Where conventions vary across projects — function vs const arrow components, named vs default exports, comment style, error handling — pick one and say so. The model has no way to guess what your team prefers.
Don't worry about being "wrong." There's no globally right answer to "should I use named exports?" There's only what your project does. Write it down.
Reference real, current versions.
Models are trained on snapshots. Their default for "Next.js" might be the version from 18 months ago. Anchor them to your actual reality:
- Next.js 15.0+
- React 19
- Node.js 20 LTS
- Tailwind CSS 4 (not 3)
Yes, this dates the file. Yes, you'll need to update it when you upgrade. Both are features — they force a periodic review and prevent the AI from drifting into ancient idioms.
Include patterns and anti-patterns, with examples.
A good rules file shows the AI what to do and what to avoid:
## Patterns to follow
- Server Components by default. Mark "use client" only at the smallest leaf needing it.
```tsx
// Good
export default async function Page() {
const data = await fetchData()
return <ClientLeaf initialData={data} />
}
Patterns to avoid
- Don't fetch in useEffect. Use a server component or Server Action.
// Bad
function Page() {
const [data, setData] = useState()
useEffect(() => { fetch('/api').then(...).then(setData) }, [])
}
The "bad" example matters more than people think. Without it, the model still falls into common traps when you don't catch them.
## Don't forget the meta-rules.
Beyond code conventions, the AI also needs *behavioral* rules — how it should act during a session:
- Ask before installing dependencies.
- Run the linter and tests before declaring a task complete.
- Never modify a database migration after it's been committed.
- Don't refactor unrelated code in the same change.
- Edit existing files when possible; only create new ones when needed.
These compound. Every prevented mistake is a turn you didn't waste correcting.
## Keep it short.
The hard cap depends on the AI tool — Copilot truncates around 200 lines, Claude tolerates 600. The practical sweet spot for most projects is **250–400 lines**. Long enough to cover real conventions, short enough that the model actually attends to all of it.
If your file is approaching 600 lines, look for things you can cut. Most rules files are 30% restatement of language defaults the model already knows. Trim those first.
## Make it a living document.
The single failure mode that kills rules files is letting them go stale. Convention drifts: the team adopts Drizzle and the file still says Prisma. The framework upgrades and the file still references old APIs.
Build it into your workflow:
- Update the rules file in the same PR that introduces a convention change.
- Quarterly review: scan for "old" — old framework versions, old library names, old patterns.
- When you upgrade a major dep, search the rules file for its name and update.
A rules file that's drifted six months out of sync is worse than no rules file. The model trusts it confidently, and that trust is misplaced.
## Where to get a good starting point
Don't write one from scratch. The [library on this site](/tools/ai-rules) has 20 hand-curated rules files for popular stacks. Pick the closest match, copy, and edit to fit your project's specifics. Or run [the generator](/tools/ai-rules/generator) and answer eight questions to get a custom one in two minutes.