Rules

Rules are each AI tool's own rule mechanism. In Cursor, for example, rules are .mdc files in .cursor/rules/, and their frontmatter decides when they apply.

Why it is an alternative

Almost every tool reads AGENTS.md; Rules only work in the tool they were written for. So our default is write AGENTS.md first, and turn only the local rules it cannot hold into Rules. Scoped rules really pay off when a team uses one tool and has many rules.

How they apply (Cursor as an example)

The frontmatter has three fields:

• alwaysApply: true: loaded every time, the same role as AGENTS.md.
• globs: loaded only when matching files are read or edited, e.g. tests/**/*.ts.
• description: what the rule covers; the agent uses it to decide whether to read it.

Note that rule files must be .mdc files with frontmatter; plain .md files are ignored. The old single-file .cursorrules is no longer in the official docs, so do not use it in new projects.

Writing a good rule

• One file, one concern. Keep testing conventions and migration conventions in separate files.
• Write checkable requirements. "Test names describe behavior in plain language" beats "write good tests".
• Keep it short. More rules mean more conflicts, and the agent is more likely to skip them.

---
description: Conventions for writing and changing tests
globs: ["tests/**/*.ts", "src/**/*.test.ts"]
alwaysApply: false
---

- Name each test with a sentence describing the behavior under test, not the function name.
- One behavior per test; keep arrange, act, and assert separate.
- When fixing a bug, first write a failing test that reproduces it, then change the implementation.
- Never weaken assertions, skip tests, or delete tests to make them pass.
- Do not hit the real network or a real database in tests; use the project's existing test doubles.