Use project rules

Project rules record stable knowledge once so people and agents can follow it across many tasks. Depending on the tool, the file may be called AGENTS.md, project instructions, rules, or something else.

The filename matters less than the content and whether the tool loads it.

What belongs in project rules

Useful rules cover decisions such as:

• the stack and supported runtime versions
• commands for tests, linting, builds, and development
• important directory or module boundaries
• naming and formatting conventions not enforced by tools
• security and privacy requirements
• generated files that should not be edited by hand
• checks required before work is complete

Prefer facts an agent could not safely infer. The production build runs Node.js 22 is useful. Write good code is not, because it does not tell anyone what to do.

Make every rule actionable

Compare:

Always test your work carefully.

After changing lesson metadata, run npm test -- courses.
After changing a page layout, open it at 375px and 1280px widths.

The second version names the trigger and the action. It can be followed and reviewed.

Rules should also explain surprising boundaries. Keep browser-only tools inside src/tools/<name> prevents an agent from creating a convenient shared file that violates the project’s architecture.

Do not turn rules into a history book

Long files consume attention. Remove obsolete setup notes, completed migrations, and duplicated advice. Keep history in documentation or version control unless it still changes current work.

Watch for contradictions. Use npm near the top and use pnpm for all commands near the bottom forces the agent to guess. Resolve the decision instead of adding another exception.

Back rules with enforcement

A written rule is guidance. A test, formatter, type checker, permission boundary, or CI check is enforcement.

If violating a rule would cause a serious bug, automate the check when possible. For example, a test can reject lesson files without descriptions. A secret scanner can catch committed credentials. The rule explains the reason; the check catches mistakes.

Keep local rules close to the work

A large repository may need a short root file plus focused rules near specific areas. A database migration directory can document its own commands without making every frontend task read them.

Review rules when the project changes. Ask whether each instruction is still true, specific, and worth the context it consumes.