How to Write Project Rules for an AI Coding Agent

How to Write Project Rules for an AI Coding Agent

Good project rules are concise, scoped, versioned instructions that help an agent find the right commands, patterns, and canonical examples. Critical requirements still belong in code, tests, schemas, permissions, continuous integration, or policy.

An instruction file is context. It is not an enforcement boundary.

flowchart TD
    A["Repeated correction"] --> B{"What consequence does it control?"}
    B --> C["Workflow or convention"]
    B --> D["Required behavior"]
    B --> E["Formatting"]
    B --> F["Access or release"]
    C --> G["Scoped project rule"]
    D --> H["Code, test, type, or schema"]
    E --> I["Formatter or linter"]
    F --> J["Permission, policy, CI, or approval"]

Start with a repeated correction

Do not begin by writing a giant rulebook for every mistake an agent might make.

Collect corrections from real work. The useful candidates are instructions you repeat because the agent misses a project-specific command, uses the wrong architectural pattern, edits generated files, ignores a canonical example, or fails to provide required verification.

Cursor's January 2026 agent best-practices guide recommends starting simple, adding rules after repeated mistakes, keeping them focused, and referencing canonical files instead of copying whole style guides.

That advice is product-specific in format but broadly useful in principle.

Decide where the constraint belongs

Rules are appropriate for guidance that the agent needs while reasoning.

They are weak for consequences that must be prevented or automatically detected.

The phrase "never expose secrets" may belong in a rule as a reminder, but the actual protection belongs in file access, secret management, logging controls, and review.

NIST SP 800-218 provides the broader secure-development rationale for turning expectations into repeatable organizational and technical practices.

Keep one rule tied to one scope

A rule should answer where it applies.

A repository-wide command list can live at the project level. A backend rule can apply only to backend files. A migration rule can apply only when schema or migration paths are involved.

Avoid contradictory global and local instructions. Define which source is authoritative when a rule points to documentation or examples.

For each rule, include the purpose, applicable paths or task type, required action, canonical reference, verification command, and escalation or stopping condition.

Write observable instructions

"Write clean code" is not an instruction a reviewer can verify.

"Follow the error-handling pattern in src/services/example.ts, do not introduce a second result wrapper, and run the focused service tests" is more useful because it names a pattern, exclusion, and check.

The rule should help the agent decide. It should also help a human review whether the rule was followed.

Reference canonical sources

Point to the smallest stable source that demonstrates the expected pattern. This might be a code file, test, schema, architecture decision, runbook, or command.

Do not paste an entire style guide into the agent context. Long duplicated instructions become stale and crowd out task-specific state.

Version project rules with the repository. Pro Git provides the durable history needed to review who changed a rule and why.

If an external document is authoritative, record its owner and freshness boundary. A broken or outdated link silently weakens the rule.

Separate project rules from task context

Project rules should describe durable project facts and repeated workflows.

The current task should carry its own outcome, exclusions, affected behavior, acceptance checks, permitted actions, and stopping point.

Do not turn a temporary exception into a permanent project instruction. Do not put a sensitive incident detail into a global rule simply to help one debugging session.

The combination matters. A project rule can tell the agent how this repository runs tests. The task can tell it which behavior to change and which tests should demonstrate success.

Test the rule

Create a low-risk representative task. Record whether the rule was loaded, whether the agent followed it, and whether the expected verification occurred.

Inspect failures. The rule may be too broad, hidden by conflicting context, scoped to the wrong path, or written as a preference without an observable action.

Do not assume that storing the file means the model used it. Current product behavior can change, which is why this page remains under continuous product review.

Cursor's September 2025 Plan Mode and hooks changelog is a dated source for product features at that release. A changelog entry is not a permanent guarantee.

Prune and promote

Delete rules that no longer match the codebase. Split rules that cover unrelated concepts. Promote requirements into stronger controls when the consequence justifies it.

If a rule repeatedly says to format code, configure the formatter. If it repeatedly says to preserve a response schema, add a contract test. If it repeatedly says not to run a command, restrict the permission. If it defines release approval, enforce it in the protected workflow.

The SLSA 1.2 specification adds a useful provenance perspective. Important source and build properties should be verifiable through the system, not merely requested in prose.

Use a compact rule record

The best project rule reduces repeated confusion without pretending to control what only the repository and organization can enforce.

This guide was developed with AI assistance from the immutable E037 transcript, current Cursor first-party guidance and changelog records, NIST SSDF, Git, SLSA, and the linked instruction-placement framework. Dalton Anderson remains the author. Continuous product, technical, security, current-source, and founder review are mandatory before publication. Publication is not authorized.