编码智能体指令该放哪：AGENTS.md、Copilot、Claude 与 Cursor 的归属划分

Coding-agent instructions have two jobs that are easy to confuse:

1. Preserve rules that should survive across tasks.
2. Put those rules where the agent you are using will actually load them.

The first job is editorial. The second is product-specific. A beautifully written file has no effect if the current tool or product surface never reads it.

This guide separates the portable layer from the tool-specific layer and gives each rule one owner. That last part matters. Copying the same paragraph into AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and Cursor Project Rules creates four sources of truth that will eventually disagree.

The decision in thirty seconds

The table is a placement rule, not a claim that every product supports every file. GitHub publishes a surface-by-surface support matrix, and that matrix should win over assumptions.

Need a file you can adapt now? Start with the AGENTS.md template, then compare the annotated examples.

Start with the rule’s lifetime: how long should it live?

Before choosing a filename, ask how long the instruction should remain true.

Durable repository rule: “Public API response shapes require explicit approval.” This belongs in tracked repository guidance because it should affect many tasks.

Tool-specific durable rule: “When Copilot edits Astro routes, run npm run build.” This can live in Copilot’s repository instructions if it is genuinely specific to that workflow. If every agent should run the build, put it in AGENTS.md instead.

Path-specific rule: “Files under src/content/blog/ must use the content collection schema.” This belongs in a scoped instruction file when the tool supports one.

Task-only constraint: “Do not touch billing during this refactor.” That belongs in the task brief. Adding it to permanent repository guidance would leave a temporary restriction behind after the work is complete.

Enforced invariant: “Untrusted users cannot read another account’s invoices.” This must be enforced by authorization code and tests. An instruction can remind an agent where the boundary is, but it is not a security control.

What is AGENTS.md?

AGENTS.md is plain Markdown intended to give coding agents project context, commands, conventions, and boundaries. It is documented by products including GitHub Copilot, OpenAI Codex, and Cursor, and the format is stewarded as an open project. Product support still varies, so check the tool you deploy rather than treating the filename as magic.

A useful root file is short and operational:

# Repository guide

## Map

- src/pages: route composition
- src/components: shared UI
- src/content: reviewed editorial content
- public: static assets and platform configuration

## Boundaries

- Ask before changing public URLs, authentication, billing, or migrations.
- Reuse the nearest established implementation pattern.
- Do not add dependencies for a one-off helper.

## Checks

- Astro routes, components, or content: `npm run build`
- Run the narrowest behavior-specific test before a broad suite.
- Report checks that could not run and the remaining risk.

That file answers questions an unfamiliar contributor would ask: where does work belong, what is risky, and what proves a change is complete?

Large repositories can use nested AGENTS.md files when the client supports hierarchical discovery. OpenAI’s Codex documentation, for example, describes layering global guidance with project-specific and directory-level overrides. Do not assume identical precedence in another client; link to that client’s behavior in your own contributor documentation.

What instruction files does GitHub Copilot read?

GitHub documents several instruction mechanisms. The important distinction is scope.

Repository-wide Copilot instructions

Use .github/copilot-instructions.md for guidance that should apply to Copilot throughout the repository:

# Copilot repository instructions

- Follow the shared boundaries in `AGENTS.md`.
- For Astro content or route changes, run `npm run build`.
- In the final response, distinguish passed checks from checks not run.

Keep this file as a Copilot-specific delta. Repeating the full repository map here creates drift.

Path-specific Copilot instructions

GitHub documents NAME.instructions.md files under .github/instructions/. The applyTo frontmatter selects matching paths in supported surfaces:

---
applyTo: "src/content/blog/**/*.md"
---

- Match the blog content schema.
- Link factual product claims to primary documentation.
- Do not claim a procedure was tested unless the repository contains the test evidence.

Path-specific support is not uniform across every Copilot surface. Use GitHub’s support matrix before designing a workflow that depends on it.

Agent instructions

GitHub also documents AGENTS.md as agent instructions, including nearest-file behavior in supported contexts. This is useful when the same repository is edited by Copilot and other compatible agents.

What is CLAUDE.md?

Claude Code documents CLAUDE.md as project memory. It is appropriate for Claude-specific workflow guidance, commands, and project context.

@AGENTS.md

# Claude Code guidance

Claude-specific workflow:

- For a broad request, inspect the affected area and present a bounded plan first.
- Ask before changing dependencies or database schemas.
- Prefer the focused test command documented beside the feature.

The @AGENTS.md import uses Claude Code’s documented file-import syntax. One file owns the shared rule; the tool-specific file imports it and adds only what is different.

Instructions are not the right mechanism for a hard command block. Anthropic’s documentation explicitly points to PreToolUse hooks when an action must be blocked regardless of model judgment. Use prose for guidance and deterministic controls for enforcement.

What rules files does Cursor use?

Cursor’s current documentation describes Project Rules, Team Rules, User Rules, and AGENTS.md. Project Rules live under .cursor/rules/ and use MDC files. Older .cursorrules references should be treated as migration context, not the default for a new repository.

A scoped Project Rule can look like this:

---
description: Editorial checks for technical articles
globs: "src/content/blog/**/*.md"
alwaysApply: false
---

- Verify product behavior against current primary documentation.
- Prefer runnable examples over conceptual pseudocode.
- Record a reviewed date when product behavior changes.

Use AGENTS.md for portable repository guidance and Project Rules for Cursor-specific selection or behavior. Cursor’s own docs are the source of truth for supported MDC metadata because the format can evolve.

How does Codex read AGENTS.md?

OpenAI’s Codex documentation says Codex reads AGENTS.md before doing work and describes layered discovery. That makes AGENTS.md the natural home for Codex project instructions.

Do not group Codex with “other CLI agents” and assume their configuration is equivalent. Codex has its own configuration reference, permission behavior, MCP support, and command-line options. Portable Markdown does not make the surrounding products identical.

Keep one owner for every rule

Use this ownership pattern:

AGENTS.md
  Shared repo map, boundaries, and checks

.github/copilot-instructions.md
  Copilot-specific additions only

CLAUDE.md
  Claude Code-specific additions only

.cursor/rules/*.mdc
  Cursor-specific or path-selected additions only

Task brief
  Current goal, scope, constraints, and acceptance checks

When two files need the same rule, one should point to the other instead of copying the paragraph. If a client does not follow references reliably, keep the duplicated bridge sentence short and treat the shared file as canonical in human documentation.

What belongs in the task brief?

A task brief should expire with the task:

goal: Add canonical links to article pages.
allowed_changes:
  - src/components/BaseHead.astro
  - src/layouts/BlogPost.astro
out_of_scope:
  - URL migrations
  - visual redesign
acceptance_checks:
  - npm run build
review_focus:
  - one canonical URL per page
  - social metadata remains absolute

The brief names the current outcome and boundaries. Permanent instruction files describe how work is done across outcomes.

How do you migrate without creating more drift?

1. Inventory every agent instruction file in the repository.
2. Mark each rule as shared, tool-specific, path-specific, task-specific, or enforceable.
3. Move shared rules into one AGENTS.md.
4. Reduce tool files to deltas and links to the shared contract.
5. Replace legacy Cursor .cursorrules guidance with current Project Rules where appropriate.
6. Move temporary project work out of durable files.
7. Convert critical prose rules into tests, permissions, CI checks, or hooks.

Do not migrate by renaming files blindly. The content and discovery rules matter more than the filename.

Verify behavior with a controlled task

Instruction quality is observable. Use a small task where success is easy to judge:

1. Start a fresh agent session in the product you are testing.
2. Ask the agent to state which repository instructions it loaded or can cite.
3. Give it a one-file change with one documented check.
4. Confirm it inspected the expected location, stayed in scope, and ran the check.
5. Repeat in each product surface your team actually uses.

If an instruction is ignored, first verify that the current surface supports the file and scope. Then shorten ambiguous language. Only after those checks should you conclude that the model failed to follow a valid instruction.

The durable strategy is simple: portable rules in AGENTS.md, small product-specific deltas, scoped files only where support is documented, and task briefs that expire. Everything important enough to enforce belongs in code or policy as well as prose.