Every time you start a new chat with an AI coding assistant, it knows nothing about your project. It does not know you use TypeScript in strict mode, that tests run with one particular command or that one folder must never be edited by hand. You can repeat all that in every prompt, or you can write it down once in a rules file.
A rules file is a plain Markdown file in your repository. The assistant reads it automatically at the start of every session, so its suggestions follow your project’s rules from the first answer.
Where each tool looks
| File | Read by | Notes |
|---|---|---|
AGENTS.md |
Many coding agents, including OpenAI Codex | An open, tool-neutral format. Put it in the repository root; some tools also read one per folder. |
CLAUDE.md |
Claude Code | In the project root for the team, or ~/.claude/CLAUDE.md for personal preferences across projects. |
.cursor/rules/*.mdc |
Cursor | One file per rule. A short header sets when it applies (always, or for matching files). An older single .cursorrules file in the root is still recognised. |
.github/copilot-instructions.md |
GitHub Copilot | Repository-wide instructions. For specific files, add .github/instructions/<name>.instructions.md with an applyTo pattern. |
If your team uses more than one tool, keep one main file and point the others to it, so the rules never drift apart. Claude Code, for example, can import another file into CLAUDE.md with a line such as @AGENTS.md.
What to put in a rules file
Good rules files are short and specific. Aim for what a new developer would need on their first day:
- The stack: languages, frameworks and the versions that matter.
- Commands: how to install, build, test and lint, exactly as you type them.
- Structure: where the main parts of the code live, and anything generated that must not be edited.
- Conventions: naming, formatting, error handling, how components or modules are organised.
- Do’s and don’ts: libraries to prefer or avoid, patterns you have banned, and why.
- How to check work: which tests to run before saying a task is done.
# AGENTS.md
## Stack
Next.js (App Router), TypeScript in strict mode, Tailwind CSS, PostgreSQL via Prisma.
## Commands
- Install: `pnpm install`
- Test: `pnpm test` (Vitest). Run it before finishing any task.
- Lint: `pnpm lint --fix`
## Conventions
- Server components by default; add "use client" only when needed.
- Database access only in `src/server/`. Never query from components.
- Do not edit files in `src/generated/`: run `pnpm prisma generate`.
## Style
- Named exports, no default exports.
- Errors: throw typed errors from `src/lib/errors.ts`.Tips from experience
- Be concrete. “Use Vitest, not Jest; test files sit next to the code as
*.test.ts” beats “write good tests”. - Explain the unusual. If a rule looks odd, add a one-line reason, or the assistant (and your colleagues) may “fix” it.
- Keep it current. Update the file in the same pull request that changes a convention.
- Never include secrets. Rules files are committed to the repository. Point to where settings live instead.
- Do not paste a whole style guide. Very long files dilute the rules that matter. Link to longer documents instead.
Start from a ready-made rules file
You do not have to write one from scratch. The catalogue has more than 400 rules files for popular stacks, in the AI Coding Rules & Instructions collection. Each one can be downloaded (as an .mdc file for Cursor, or Markdown for other tools), then trimmed to fit your project. A few examples:
- Vue 3 Nuxt 3 TypeScript Rules
- Vitest Unit Testing Rules
- WordPress Claude Stack Rules, a full setup for WordPress themes and plugins with Cursor rules, a CLAUDE.md and Copilot instructions.
Rules files work best alongside skills and custom agents. Our guide What are agent skills? explains how the three fit together.
