Rules

Rules are instructions the agent follows in every conversation, so you don't have to repeat them. Use them for things the agent can't reliably infer from the code: which package manager to use, how tests are organized, naming conventions, or actions it should never take.

Where rules live

Each rule is a Markdown file in a rules folder:

Project rules can be committed with the project so everyone working on it gets them. You can also create and edit rules in the Rules + Skills + Commands settings.

Rule format

A rule is plain Markdown. Optional frontmatter at the top sets its name or turns it off:

---
name: Testing conventions
---

- Use Vitest for unit tests and put test files next to the code as `*.test.ts`.
- Run `pnpm test` to check changes. Don't use npm or yarn in this project.
- Mock network calls. Tests must not reach external services.

Without a name, the file name is used. Add enabled: false to keep a rule without applying it.

How rules are applied

Enabled user and project rules apply in every mode. There's no file-pattern setting, so describe any task-specific conditions in the rule itself. Rules guide the agent; they aren't a substitute for permissions or other security controls.

Writing effective rules

• Keep rules short and specific. They take up context in every request.
• Give one topic per file, with concrete instructions rather than general goals.
• Point to the source of truth instead of copying it, for example "Follow the API conventions in docs/api.md."
• Add a rule when you find yourself correcting the same mistake more than once.