AGENTS.md and Cursor Rules Examples for AI Coding Agents

A coding agent needs more than a feature request. It needs to know which commands are safe, where architectural decisions live and what counts as finished. Without that context, an assistant can produce a plausible change that ignores the conventions holding your repository together.

Project instruction files make those expectations reusable. Their value comes from precision and maintenance, not length. A short set of verified rules beats several pages of generic advice that conflict with the actual codebase.

Establish which instructions the agent reads

Instruction discovery differs between products. An AGENTS.md file, an editor-specific rules directory and a hosted assistant's project settings are not automatically interchangeable. Check the installed tool's documentation and inspect its effective context where the interface supports that. Do not assume a filename is universal simply because another agent recognises it.

The AGENTS.md specification explains the convention, while Cursor's rules documentation describes its own mechanisms. Use those sources to verify scope and activation rather than copying a configuration from an old tutorial. Features and supported formats can change independently of your repository.

Keep one canonical source for shared engineering expectations. Tool-specific adapters can point to that source or reproduce a deliberately small subset when inclusion is unsupported. If you duplicate a rule, record who maintains both copies. Otherwise a migration command or testing requirement will eventually disagree between tools.

Start with a clean session and ask the agent to identify the applicable instructions before assigning a small task. This is a useful diagnostic, not proof of compliance. Confirm behaviour through the resulting patch and command history rather than trusting a confident summary.

Write rules around observable decisions

Useful instructions answer questions an agent will actually face. Which package manager does this repository use? Which module owns API access? May a task introduce a dependency? Which generated files must remain untouched? Replace “write clean code” with a concrete constraint such as “reuse the shared request client rather than calling fetch directly from components.”

Separate mandatory constraints from preferences. Security boundaries, data handling and deployment restrictions should not look equivalent to import-order preferences. Explain exceptions and escalation: if a required command cannot run, the agent should report the blocker rather than silently substituting another check.

A compact starting point might look like this:

Scope: application source and component tests.
Use existing service modules for network requests.
Do not add dependencies or edit generated API types without approval.
Run the documented targeted test command for changed behaviour.
Report commands actually run and checks not completed.
Stop and ask before migrations, deployments or credential changes.

Treat these as examples to adapt, not universal repository instructions. Executable commands must match your environment, including working directory and setup requirements. A rule pointing to a nonexistent script teaches the agent to improvise precisely where you wanted consistency.

Link to existing architecture documents instead of embedding them wholesale. The instruction file should help an agent locate the right evidence quickly, not become a second, less reliable version of the engineering handbook.

Scope local rules without creating contradictions

A monorepo may need different conventions for a browser application, a backend service and infrastructure code. Put local constraints near their ownership boundary when the agent supports scoped instructions. Explain what the local file adds and what remains governed by the shared rules.

Avoid relying on undocumented precedence. If two files disagree about a package manager or test command, repair the conflict instead of hoping the agent chooses correctly. Keep directory-specific rules narrow enough that someone reviewing a change can identify the relevant instructions without reading every package in the repository.

Use a concrete boundary example during review. Suppose the web application consumes generated API types. A root rule may ban manual edits to generated files, while a service rule explains the generator. The web agent should request regeneration through that workflow, not copy service internals into the browser to satisfy a type error.

Use the JSON to TypeScript tool on a sanitised example response to draft an interface when documenting that boundary. Compare its output with the real schema before including it in instructions. Sample-derived types do not establish required fields, nullable values or every possible response shape.

Keep fixtures synthetic. A convenient response copied from production can accidentally turn customer information into persistent model context or a committed instruction example.

Separate guidance from actual permissions

Instruction files are not a sandbox. “Never deploy” is useful guidance, but access controls should still prevent an unattended agent from deploying. Restrict credentials, network access, writable directories and command approvals according to the task. The more consequential an action, the less you should rely on natural-language compliance alone.

Repository content can also contain untrusted text: issue descriptions, external documentation, comments and test fixtures. A malicious instruction embedded in that material should not acquire authority merely because the agent reads it. Explicitly describe which sources are task data and which configuration defines approved behaviour.

Apply the same principle to dependency installation and database access. Require approval for new packages, destructive commands and operations against shared environments. For deeper review checks, use the workflow in security risks in AI-written code. A well-written rules file reduces ambiguity; it does not replace security review.

The GitHub responsible-use documentation provides a useful product-specific perspective on limitations and human oversight. Verify equivalent controls for whichever assistant you adopt through the AI coding assistants directory.

Test and maintain instructions like configuration

Give instruction ownership to a team or named role. Review the files when commands, architecture or deployment procedures change. A stale rule can be worse than no rule because it supplies apparently authoritative guidance that contradicts the current system.

Build a small set of representative tasks: add a component test, update a service call and fix a type error without changing generated files. Run them after major instruction revisions. Evaluate the patch, tool use and final report against explicit expectations. Do not score only whether the agent repeats the rules back.

Watch for context overload. Long lists of rare exceptions make the important constraints harder to find and consume space needed for the actual task. Move specialist detail into linked documents and retain a short routing instruction explaining when to read them. Remove rules that duplicate automated formatting or linting without adding useful context.

Require honest completion reports. The agent should distinguish tests executed from tests recommended, explain environment blockers and identify any requested behaviour it could not verify. That makes the instructions useful at handoff rather than merely at task start.

Finally, record why unusual constraints exist. One sentence explaining that a directory is generated from a partner schema can prevent repeated attempts to “clean up” intentional duplication. Preserve the decision, not the historical argument that produced it.

Key takeaways

• Verify how your chosen agent discovers and scopes repository instructions.
• Keep shared rules canonical, concise and tied to observable decisions.
• Document real commands, ownership boundaries and escalation paths.
• Enforce consequential permissions outside natural-language instructions.
• Test rule changes against realistic tasks and maintain them alongside code.