Writing a project rules file
A project rules file is the text your agent reads before every task in this repository. AGENTS.md is the harness neutral name; Claude Code reads CLAUDE.md. The content is the same either way.
The highest value section is commands
If your file contains only one thing, make it the commands.
## Commands - `npm test` run the test suite - `npm run typecheck` check types - `npm run dev` start the dev server Before saying a change is complete, run `npm test` and `npm run typecheck`.
A wrong or missing command costs a full exchange every time: the agent guesses, the guess fails, it reports the failure, you correct it. Getting this section right pays for the whole file.
Point at files, do not describe patterns
Weak: "We use a layered architecture with clear separation of concerns."
Strong: "Route handlers stay thin. Business logic goes in src/services/. Copy the shape of src/services/billing.ts."
The model can read billing.ts. It cannot read your intent.
Fill "do not" from experience only
Start that section empty. Every time you correct the agent about the same thing twice, add a line.
A rule that came from a real mistake in your codebase is worth ten rules you imagined in advance, and it keeps the file short enough that the rules near the middle still get read.
Say what needs asking
## Ask first - Adding a dependency - Changing CI or config - Deleting files - Anything touching auth, payments, or user data
This is guidance rather than enforcement. Real enforcement lives in permissions and approvals. Both are worth having, because the file explains the reasoning and the permissions catch the mistake.
Length is a feature
Aim for under a hundred lines. Past that, you are competing with yourself for the model's attention, and instructions in the middle get followed least.
If your file is growing, that is usually a sign the knowledge belongs in a skill that loads only when relevant, rather than in a file loaded on every task.
Project facts, not personal preference
Project facts go in the project file, because they are true for everyone working on the repository. Personal preferences go in your global file, at ~/.claude/CLAUDE.md or the equivalent.
Putting "always explain your reasoning to me" in a shared repository file imposes your working style on your colleagues.
Keep it in version control
The file is part of the project. When conventions change, it changes in the same commit, and reviewers can see that it did.
Starting point
The templates section has filled in rules files for web apps, data projects, monorepos, and about a dozen specific stacks. Start from the closest one and delete what does not apply.