On this page#
- How we judged them
- The shortlist
- What we rejected and why
- The one nobody talks about
- Choosing by repo shape
- FAQ
How we judged them#
The right cursor agents md setup is the smallest instruction system that preserves repository invariants without fighting the task. Judge each option by scope, authority, maintainability, failure visibility, and recovery cost—not by how comprehensive or polished the file appears.
Here, an agent is an AI coding system built on a large language model: a model that generates output from the context and instructions it receives. An AGENTS.md file changes that context; it does not make the model understand your architecture automatically.
Use these criteria:
- Scope clarity: Can the agent tell exactly which code the instruction governs?
- Invariant coverage: Does the file protect boundaries that tests or types cannot fully express?
- Task relevance: Will the instruction affect decisions the agent must make now?
- Verifiability: Can the agent prove it complied through tests, static checks, or a concrete inspection?
- Conflict risk: Could a nested file, prompt, or repository document contradict it?
- Maintenance cost: Will engineers update the instruction when the code changes?
- Recovery cost: If the instruction is wrong, how much work must be unwound?
The decisive distinction is between constraints and background. “Never import infrastructure code into the domain package” is a constraint. A page describing the company’s history is background. Put constraints close to the code; link background instead of copying it.
That principle is compatible with Cursor’s official documentation, but the documentation cannot identify your repository’s invariants for you. Tool configuration describes how instructions are supplied. Repository owners still have to decide which instructions deserve authority.
Photo by mali maeder on Pexels.
The shortlist#
For a serious repository, the strongest setup usually combines a short root AGENTS.md, narrowly scoped nested files, and executable checks. Each has a different job. Treating them as interchangeable produces either vague guidance or a maze of contradictory rules.
| Option | Genuinely good at | Best for | When not to use it |
|---|---|---|---|
| Root AGENTS.md | Repository-wide commands, boundaries, and non-negotiable conventions | Repositories with a stable build path and shared architectural rules | When the content applies to only one package or repeats existing documentation |
| Nested AGENTS.md | Local constraints that should travel with a directory or subsystem | Monorepos, layered systems, generated code, migrations, and security-sensitive modules | When engineers cannot predict which file governs a path |
| Cursor-native project rules | Cursor-specific behavior, file targeting, and workflows | Teams committed to Cursor that need editor-aware instruction delivery | When the repository must behave consistently across Claude Code, Codex, Cursor, and future agents |
| Task-local brief | Temporary acceptance criteria, allowed scope, and explicit non-goals | Risky migrations, incidents, and changes with unusual constraints | When it becomes a permanent substitute for repository documentation |
| Executable guardrail | Enforcing properties through tests, types, linters, or dependency checks | Any invariant that can be checked mechanically | When the rule is subjective and a failing check cannot explain the intended design |
Start with the root file, but keep it operational. Include the canonical validation commands, high-level package boundaries, forbidden actions, and where deeper instructions live. Do not turn it into an onboarding handbook.
Use nested files only when locality reduces ambiguity. A database migration directory may need rollback and compatibility rules that would distract anyone editing a UI component. The nested file earns its existence because its instructions become more relevant as its scope becomes smaller.
Cursor-native rules can be excellent inside Cursor; Cursor’s documentation is the authority for their mechanics. They are still a portability choice. If several agents touch the same repository, keep durable invariants in repository-native artifacts and reserve tool-specific rules for tool-specific behavior.
If you want packaged starting points rather than inventing the structure from scratch, use the PairFoundry tools as scaffolding. Scaffolding should shorten setup, not replace the review that makes instructions true for your codebase.
What we rejected and why#
We rejected any approach that maximizes instruction volume, relies on prose where enforcement is possible, or silently binds the repository to one agent. These patterns look mature in a demo but deteriorate under parallel work, ownership changes, and routine architectural evolution.
One giant instruction file#
A giant root file is the most common mistake. It forces every task to carry irrelevant material and makes conflicts harder to locate. Worse, important constraints become indistinguishable from preferences about naming, formatting, or response style.
If a rule matters only under one directory, move it there. If it can be enforced, encode it in a check. If it is explanatory, link to the canonical document.
Generated rules accepted without review#
Generated instructions are drafts, not repository truth. A generator can propose useful categories, but it cannot know which apparent pattern is intentional, transitional, or already deprecated unless that knowledge exists in its input.
Review every imperative sentence with two questions: “Is this true?” and “What breaks if the agent obeys it literally?” The available PairFoundry packs can provide structure, but ownership of the final constraints stays with the team.
Copying the README into AGENTS.md#
This wastes context and creates a second source of truth. A README explains the project to humans; agent instructions should identify decisions, commands, boundaries, and stop conditions that affect code changes.
Link the README when background is necessary. Repeat only information whose omission would predictably cause an invalid change.
Tool-only governance#
Making Cursor-specific rules the sole source of architectural truth is the wrong choice for a multi-agent team. The moment a contributor uses another coding agent, the same repository operates under different constraints.
Use tool-specific configuration to improve Cursor behavior, not to hide rules every contributor and automation path must follow. The broader agent landscape belongs in the PairFoundry landscape guide; repository invariants belong with the repository.
Prose-only safety#
“Do not break compatibility” is not a guardrail. It is an aspiration unless the file defines the compatibility boundary and names a way to verify it.
Prefer “preserve the public schema; run the schema compatibility check” when such a check exists. Instructions should direct validation, not impersonate it.
Photo by ThisIsEngineering on Pexels.
The one nobody talks about#
The underrated option is a deliberately small nested AGENTS.md owned by the same people who own the subsystem. It beats a sophisticated global file when a directory has sharp local invariants, because proximity makes both application and maintenance more predictable.
This is especially valuable around generated files, migrations, public APIs, authentication boundaries, and legacy modules with constrained change paths. The file can say which sources are editable, which commands regenerate outputs, what compatibility must remain intact, and when the agent must stop for human review.
Keep it short enough that every line can be treated as authoritative. A useful local file answers:
- What may be changed here?
- What must remain invariant?
- Which files are derived rather than edited?
- How is the change validated?
- Which condition requires escalation?
Do not duplicate the root file. Local instructions should refine the repository baseline, not restate it. If the relationship between root and nested guidance is unclear, the structure has already failed.
Teams new to this discipline should first learn how instruction hierarchy, validation, and task scoping interact. The PairFoundry foundations track is the better next step when the team is not ready to standardize or buy a packaged setup.
Choosing by repo shape#
Choose by where invariants live and how independently parts of the repository evolve. There is no universally best cursor agents md template: a compact service, a monorepo, and a generated SDK need different instruction topologies even when the same agent edits them.
- Single service with one build path: Use a short root
AGENTS.mdplus executable checks. Add nested guidance only for an exceptional area such as migrations. - Monorepo with independent packages: Use a repository baseline and nested files at genuine ownership boundaries. Each package should state its validation path without redefining universal rules.
- Layered application: Put dependency-direction rules at the narrowest shared scope. Enforce them mechanically when possible.
- Generated SDK or client repository: Separate editable sources from generated outputs explicitly. Name the regeneration and verification path.
- Legacy system under active migration: State the permitted direction of change and the compatibility boundary. Avoid sweeping “modernize nearby code” instructions.
- Multi-agent team: Keep durable invariants tool-neutral. Use Cursor-specific rules only for Cursor-specific ergonomics, following Cursor’s documentation for supported behavior.
- High-risk subsystem: Combine local instructions with checks and explicit human-review triggers. More prose alone does not create more safety.
The practical default is simple: root guidance for universal truths, nested guidance for local truths, task briefs for temporary truths, and executable checks for provable truths. Anything else must justify its maintenance and conflict cost.
Photo by Al Nahian on Pexels.
Related reading#
- Cursor AI agents, judged on what they do to your diff
- Claude Code best practice, judged on what they do to your diff
FAQ#
How is AGENTS.md different from Cursor’s official project rules?#
AGENTS.md is the better home for durable, repository-level guidance that should remain useful across agents. Cursor project rules are better for Cursor-specific instruction delivery and targeting. Use Cursor’s official documentation for mechanics, but do not make editor configuration the only record of architectural constraints.
What is the biggest team collaboration failure with agent instructions?#
The biggest failure is invisible conflict: one engineer updates code or architecture while old instructions continue directing agents toward the previous design. Assign ownership, keep rules close to the affected code, and require instruction changes in the same review that changes an invariant.
How do we recover when an agent followed a bad rule?#
Stop expanding the change, identify the instruction that caused the decision, and revert or repair the smallest affected scope. Then correct the rule before retrying. Do not patch the output while leaving the faulty instruction active; that guarantees the same class of failure will return.
When should we avoid AGENTS.md entirely?#
Avoid it when the repository has no stable agent-specific guidance beyond commands already documented and enforced elsewhere. Adding a file merely because other repositories have one creates another stale authority. A task-local brief may be enough until recurring constraints become clear.
Should every repository directory get its own file?#
No. Create a nested file only where a directory has distinct invariants, validation, ownership, or generated artifacts. Blanket distribution makes scope harder to reason about and turns routine refactoring into instruction maintenance. Fewer authoritative files are safer than comprehensive but overlapping ones.