Cursor rules that load

# 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.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `write-cursor-rule`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Cursor rules that load" v1.0.0 — https://loadout.jnw-it.com/loadouts/cursor-rules-that-load/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `write-cursor-rule`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Cursor rules that load" v1.0.0 — https://loadout.jnw-it.com/loadouts/cursor-rules-that-load/ -->

---
description: Use when creating or editing Cursor rules, AGENTS.md files or skills in this repository.
globs: .cursor/rules/**/*.mdc
alwaysApply: false
---

- Front matter keys: `description`, `globs`, `alwaysApply`. Nothing else is read.
- Write `globs` as a comma-separated string of patterns (the documented form). If a rule never attaches, check for a YAML list first.
- Auto-attached rules need `alwaysApply: false`; with `true` the globs are ignored.
- Keep each rule to one topic and under ~60 lines. Move procedures into `.agents/skills/<name>/SKILL.md`.
- After editing, check it loads: open a matching file, start a new chat and ask which rules are active.

---
name: write-cursor-rule
description: Add, split or fix a Cursor rule (.mdc) so it loads at the right time, and check it loads. Use when asked to write a rule, when a rule is ignored, or when converting .cursorrules.
---

# Write a Cursor rule

1. **Decide the container** with the table in AGENTS.md. If it belongs in `AGENTS.md`, a skill or a hook, do that instead and stop.
2. **Pick the type**: always, auto-attached (globs), agent-requested (description) or manual. Default to auto-attached.
3. **Write the file** at `.cursor/rules/<topic>.mdc`, using `references/examples.md` as the pattern. Topic names are kebab-case.
4. **Check the front matter**: only `description`, `globs`, `alwaysApply`; globs as a comma-separated string.
5. **Test it loads**: tell the human to open a file the globs match, start a new chat and ask "Which rules are attached?".
   For agent-requested rules, ask a question the description covers and check the rule is pulled in.
6. **Remove duplicates**: delete the same instruction from `AGENTS.md`, `.cursorrules` or other rules.

## Fixing an ignored rule
- `alwaysApply: true` with globs: globs do nothing. Pick one.
- Globs written as a YAML list: rewrite as one string, `src/**/*.ts, src/**/*.tsx`.
- Description that says what the rule is ("TypeScript rules") instead of when to use it ("Use when editing API handlers").
- Rule too long or contradicting `AGENTS.md`: shorten, and make `AGENTS.md` the single source.

# Example rules

Auto-attached, scoped to React components:

```markdown
---
description: React component conventions.
globs: src/components/**/*.tsx
alwaysApply: false
---

- Function components only; props typed with an exported `type <Name>Props`.
- Data fetching lives in hooks under `src/hooks/`, never inside components.
- Every new component gets a story in the same folder: `<Name>.stories.tsx`.
```

Agent-requested, no globs:

```markdown
---
description: Use when writing or changing a database migration.
alwaysApply: false
---

- Create migrations with `npm run db:new -- <name>`; never edit an applied migration.
- Every migration is reversible: write the down step and run `npm run db:rollback` locally before committing.
```

Always on (keep these rare and short):

```markdown
---
alwaysApply: true
---

- Package manager is pnpm. Never run npm or yarn install.
```

Copilot equivalent of the first example, at `.github/instructions/components.instructions.md`:

```markdown
---
applyTo: "src/components/**/*.tsx"
---

- Function components only; props typed with an exported `type <Name>Props`.
```