Writing rules

A rule is a constraint the assistant must follow inside a scope. Rules are the strongest piece of content in Pathrule: a well placed strict rule blocks a class of mistake before it can land.

This page covers when to write a rule, how to choose scope, priority and enforcement, and the patterns to avoid.

When to write a rule

Reach for a rule when there is a thing the assistant must not do, or a thing it must always do, in a specific part of the codebase.

• "Never use the service role key in browser code."
• "All money values are stored as integers in cents. Never use floats."
• "Migrations must run before the matching code change. No exceptions."
• "JSX files in apps/web use Tailwind classes only. No CSS modules, no inline styles."

If the answer is "it depends on the situation, the assistant should think about it," that is a memory, not a rule. Rules are for non negotiable things.

Scope types

Every rule has a scope type that decides which paths or files it applies to.

• folder. Applies to a directory subtree. Best for area specific rules: anything that lives under apps/api/auth, anything under services/billing.
• file_type. Applies to files matching a glob like *.tsx or **/*.test.ts. Best for cross cutting concerns that are tied to a file kind, not a directory.
• project. Applies everywhere in the workspace. Use sparingly. A project rule rides every prompt.

The scope and the node path the rule is attached to together decide what the assistant sees. A folder rule attached at /apps/web covers anything under apps/web.

Priority levels

Priority decides how aggressively the rule shows up.

• high. Always injected when scope matches. Use for things that cause bugs, security regressions, or compliance issues if violated.
• medium. The default. Surfaces when the hook believes the rule is relevant for the current task. Use for "almost always but not load bearing".
• low. Stylistic. Surfaces when there is room and the topic is on point. Use for taste and convention.

High priority is a budget. If half your rules are high priority, none of them are. Pick the ones that really cannot be violated.

Enforcement: advisory and strict

Enforcement is a separate setting from priority. Priority ranks how strongly a rule surfaces; enforcement decides what happens on a violation.

• advisory. The rule is context. The assistant weighs it and decides how to apply it. Most rules are advisory.
• strict. A strict rule with a matching pattern is enforced by the local hook, which blocks a violating change before it lands and surfaces the rule as the reason. Reach for strict only when a violation must not be allowed through.

Strict enforcement runs through the hook on Claude Code, Cursor, and Codex. The Remote MCP surface has no hooks, so it surfaces every rule as context only.

Structure

A rule has a name and a body. Keep the body imperative and short.

Name: No service role key in browser code

Body:
- Never import SUPABASE_SERVICE_ROLE_KEY in any file under apps/web.
- Use the anon key plus row level security.
- If you need server only access, do it from apps/api or a server action.

The shape that works best in practice is one constraint per rule with a small bulleted body. Long prose rules get skimmed by both humans and assistants.

Reusable, not duplicated

A rule is a workspace level object. It can be attached to multiple nodes through a small join. If you have the same constraint that applies to two distant folders, attach the same rule object to both rather than copy pasting the text.

This is mostly invisible at write time but matters when you need to update the rule: one edit, and every attachment sees it.

Versioning and concurrent edits

Rules carry a version token like memories. Two teammates editing the same rule at the same time will conflict cleanly rather than overwrite each other. The conflict resolution UI gives the same three options: keep mine, take theirs, or three way merge.

How rules show up to the assistant

• High priority rules are injected into the assistant's context for every matching scope. They appear in the Pathrule section of the context surface.
• Medium and low priority rules go through relevance filtering. They are still listed in the rule index the assistant can read, but only the relevant ones ride along on a given turn.

Whether a rule can block a change, rather than just inform the assistant, is set by its enforcement mode (advisory or strict), not by its priority.

Anti patterns

• High priority for everything. Pick the rules that really matter. The rest should be medium.
• Rules that read like memories. "We tend to prefer X" is a memory. "Never do Y" is a rule.
• Rules that overlap. Two high priority rules with conflicting language is worse than one clear rule.
• Project scope used by default. Most rules belong under a folder. Pull a rule up to project only if it really applies everywhere.

What to read next

• Writing memories for facts and decisions that are not constraints.
• Writing skills for reusable procedures the assistant can invoke.
• How hooks work for how the runtime decides which rules to surface.