How to Write Project Rules for AI Coding Assistants

Which file does each tool read?

Use AGENTS.md as your default. It’s an open format, now stewarded by the Agentic AI Foundation under the Linux Foundation, and most major tools read it. Add a tool-specific file only when you need a feature that format lacks.

Details checked against each vendor’s documentation on October 16, 2026. See the sources at the end.

If your team uses more than one tool, keep the real content in AGENTS.md. For Claude Code, a CLAUDE.md can import it with a line containing @AGENTS.md, so you maintain one file.

What to put in a rules file

Write down what a capable new teammate would need on day one and couldn’t guess from the code. In practice that is five things.

1. Commands. Exactly how to install, build, test, lint and run the app. Include the command to run a single test; agents use it constantly.
2. Project map. The main folders and what lives in each, in a few lines. Point out generated code and vendored code the AI must not edit.
3. Conventions that differ from the defaults. Naming, error handling, logging, the date library you use, how you structure tests. Skip anything a linter already enforces.
4. Hard limits. Things the assistant must never do, stated plainly: “Never edit files in migrations/ that are already merged.” “Never commit directly to main.” “Don’t add new dependencies without asking.”
5. How to verify work. What “done” means: tests pass, types check, the linter is clean, and new code has tests.

What to leave out

Leave out anything long, obvious or secret.

• Secrets: no API keys, passwords or internal URLs that shouldn’t leak. Rules files are committed to the repository and sent to the model.
• Generic advice: “write clean code” and “follow best practices” change nothing. Be specific or delete it.
• Whole documents: link to the architecture doc instead of pasting it. Claude Code’s documentation, for example, recommends keeping each CLAUDE.md under 200 lines, because longer files use more context and are followed less consistently.
• Rules for one folder: if a rule only matters for part of the codebase, use path-scoped rules (Copilot’s applyTo globs, Cursor’s .mdc globs) or a nested AGENTS.md in that folder. GitHub’s documentation, for example, says Copilot uses the nearest AGENTS.md in the directory tree.

A template you can copy

# AGENTS.md

## Commands
- Install: `npm ci`
- Build: `npm run build`
- Test all: `npm test`
- Test one file: `npx vitest run path/to/file.test.ts`
- Lint and types: `npm run lint && npx tsc --noEmit`

## Project map
- `src/api/` HTTP handlers. Thin: validate input, call a service, return.
- `src/services/` business logic. All database access goes through here.
- `src/db/migrations/` SQL migrations. Never edit a migration that is merged; add a new one.
- `src/generated/` generated from the OpenAPI spec. Do not edit by hand.

## Conventions
- TypeScript strict mode. No `any` without a comment explaining why.
- Errors: throw `AppError` from `src/errors.ts`; never return null for failures.
- Dates: use `date-fns`, store UTC, format only in the UI.
- Tests sit next to the code as `*.test.ts`.

## Hard limits
- Don't add dependencies without asking first.
- Don't change public API response shapes without asking first.
- Never commit to `main`. Never commit secrets or `.env` files.

## Definition of done
- All tests pass, lint and type checks are clean.
- New behavior has tests. Bug fixes include a test that failed before the fix.
- Summarize what changed and anything you weren't sure about.

Let AI do this part. Don't fill in the template by hand. Ask your assistant: “Read this repository and fill in this AGENTS.md for it: the real commands, structure and conventions. Mark anything you're guessing.” Then check every line, because a wrong rule is worse than none.

The free AI Coding Starter Kit includes a longer, annotated version of this template.

Keep it current

Treat the rules file like code: review changes and fix it when the AI gets something wrong. When an assistant repeats a mistake, the fix is usually one specific line in the rules file. Several tools can draft a first version for you; Claude Code’s /init command, for example, analyzes the codebase and writes a starting CLAUDE.md. Edit the draft down before you commit it.