Agent instruction files: what belongs where

Agent instructions now live in several places. The mistake is treating every file as the same kind of memory. Start by deciding whether the rule is shared repo context, tool-specific behavior, a reusable workflow, or an enforced safety boundary.

Use AGENTS.md For Shared Repo Rules

Put setup commands, test commands, repo layout, code style, review expectations, and local safety rules in AGENTS.md when they should help multiple coding agents. Keep the root file short, then add nested files only when a service or package really has different rules.

• Good fit: commands, conventions, project map, review gates.
• Weak fit: secrets, personal sandboxes, temporary credentials.
• Escalate: if a rule needs scripts or references, make it a skill instead.

Use Claude Memory For Claude-specific Context

CLAUDE.md is useful when the guidance is specifically for Claude Code. Use it for recurring project context and repeated corrections. Use .claude/rules/ when the guidance is path-scoped. Do not treat memory as enforcement; use hooks or permissions for hard blocks.

Use Cursor Rules For Cursor Routing

Cursor Project Rules, Team Rules, and User Rules are better when you need Cursor metadata, file-pattern activation, team policy, or personal agent behavior. Cursor can also read AGENTS.md, so use AGENTS.md as the common base and Cursor rules for Cursor-only behavior.

Turn Repeated Workflows Into Skills

A skill is justified when the workflow needs progressive disclosure, bundled references, scripts, assets, or a proof artifact. If it is only one sentence of repo context, keep it in the instruction file.