# AGENTS.md: writing agent rules that actually load

Rules only help if the agent loads them at the right moment. Decide where each instruction goes before writing it.

## Pick the container
| Instruction | Put it in |
|---|---|
| Applies to every task (build/test commands, hard constraints) | `AGENTS.md` |
| Applies to some files (`*.tsx`, `migrations/**`) | Cursor rule with `globs`; Copilot `.instructions.md` with `applyTo`; or a nested `AGENTS.md` |
| A procedure used sometimes (release, migration, triage) | A skill: `.agents/skills/<name>/SKILL.md` |
| Must never happen (force-push, reading `.env`) | A hook or permission deny rule. Text rules are advice; hooks enforce |

## Cursor rule types (`.cursor/rules/*.mdc`)
Front matter has three keys only: `description`, `globs`, `alwaysApply`.
- Always: `alwaysApply: true`. Use for very few rules; each costs context in every chat.
- Auto-attached: `globs: src/**/*.tsx` and `alwaysApply: false`. Loads when a matching file is in context.
- Agent-requested: `description` set, no `globs`, `alwaysApply: false`. The agent reads the description and decides; write the description as "Use when …".
- Manual: no description, no globs. Loads only when someone types `@rule-name`.

## Writing rules
- One topic per rule file, under ~60 lines. Imperative sentences. Show the exact command or code shape.
- Say what to do, not only what to avoid. Pair each "never" with the alternative.
- Do not restate defaults the agent follows anyway.
- `.cursorrules` is legacy. Move its content into `.cursor/rules/` or `AGENTS.md` and delete it.
- `.cursor/rules` does not apply to Bugbot code review; review rules go in `.cursor/BUGBOT.md`.
- Long rules that are really procedures become skills. Cursor's `/migrate-to-skills` converts agent-requested rules.

Use the `write-cursor-rule` skill to add or fix a rule, and test that it loads.