1 min lesson
Rules, AGENTS.md and context configuration
Rebuild the parts of "Rules, AGENTS.md and context configuration", then say why each one matters.
Step 1 of 3
The single most common support question a DX Engineer fields is some version of "why isn't my rule firing?" Answering it cold, with the precedence and scoping in your head, is a fast credibility test.
Context configuration is how a developer teaches the agent their stack, conventions and constraints. Modern rules live in .cursor/rules/*.mdc: markdown bodies with a YAML frontmatter that controls when each rule applies. Version-controlled, file-scoped and conditional, they replace the older single-file approach.
Learn more
Full explanation
.cursor/rules/api-conventions.mdc
--- description: Conventions for files under src/api globs: - "src/api/**/*.ts" alwaysApply: false --- # API conventions - All handlers return a typed Result, never throw across the boundary. - Validate input with the zod schema colocated next to the handler. - Log with the request id from context, not a fresh one.
Cursor also reads fallback files so a repo can stay portable across tools. The legacy .cursorrules file still works and AGENTS.md is the cross-IDE standard rule file Cursor reads when present.
- File
- .cursor/rules/*.mdcMarkdown-Cursor rule file. The file format for a Cursor rule; set always_apply to false and scope it so the rule only fires on the files that need it instead of burning context every request. Press Enter for the full definition.
- Status
- Modern, preferred
- Scope
- Conditional, file-scoped, multi-rule
- File
- .cursorrules
- Status
- Legacy, still honored
- Scope
- Single file, repo-wide
- File
- AGENTS.md
- Status
- Cross-IDE standard
- Scope
- Repo-wide, portable across agents
| File | Status | Scope |
|---|---|---|
| .cursor/rules/*.mdcMarkdown-Cursor rule file. The file format for a Cursor rule; set always_apply to false and scope it so the rule only fires on the files that need it instead of burning context every request. Press Enter for the full definition. | Modern, preferred | Conditional, file-scoped, multi-rule |
| .cursorrules | Legacy, still honored | Single file, repo-wide |
| AGENTS.md | Cross-IDE standard | Repo-wide, portable across agents |
Teach the .mdc form first; mention the fallbacks so a developer's existing setup isn't broken.