Quick answer
If you use more than one AI coding agent, do not start with one giant instruction file for every tool. Start with a small repo-level AGENTS.md that captures the shared contract: project layout, install and test commands, coding conventions, safety boundaries, and the definition of done.
Then add tool-specific files only when the behavior truly differs:
- Use
AGENTS.mdfor portable project instructions that Codex, Cursor, and other agents can read. - Use
CLAUDE.mdwhen Claude Code needs Claude-specific project memory or rules. - Use
.github/copilot-instructions.mdor scoped GitHub instruction files when GitHub Copilot needs repository or organization context. - Use Cursor Rules when the instruction should be scoped by file type, directory, or IDE workflow.
The important distinction: instruction files guide model behavior. They are not hard enforcement. Put non-negotiable checks in scripts, CI, hooks, permissions, or review gates.
Who this is for
This guide is for indie developers, small teams, and solo founders who use AI coding tools but keep repeating the same corrections:
- "Run the tests before saying done."
- "Do not add a new dependency for this."
- "Follow the existing component pattern."
- "Do not touch unrelated files."
- "Write the Chinese copy too."
That repetition is a signal: the rule should move out of chat and into a durable project file. This matters even more when you use several tools at once: Codex for repo tasks, Claude Code for exploration, Cursor for IDE work, and Copilot for suggestions or review.
What changed and why now
AI coding tools have moved from autocomplete into agent workflows. They read repositories, run commands, edit files, call MCP servers, and sometimes work across many steps. Project instructions are now valuable, but easy to overdo.
The demand signal is visible. Google autocomplete shows queries such as agents.md best practices, agents.md vs claude.md, and agents.md vs copilot-instructions.md. Recent Hacker News discussions mention AGENTS.md, shared agent memory, and whether instruction files actually help. Official docs also expose the ecosystem shape: OpenAI documents AGENTS.md, Anthropic documents CLAUDE.md and auto memory, GitHub documents Copilot custom instructions, and Cursor documents Rules plus AGENTS.md support.
For a small product repo, this creates a practical question: where should the rules live?
The practical workflow
Use this order before adding more instruction files:
- Audit repeated corrections. Collect real misses: forgotten commands, unrelated file edits, missed architecture patterns, misunderstood product boundaries, or unverified claims of success.
- Put shared repo facts in
AGENTS.md: layout, ownership boundaries, package manager, build/test/lint commands, product rules, "do not" rules, and completion standards. - Add tool-specific files only for real differences. Use
CLAUDE.mdfor Claude-specific memory or rules, Copilot instructions for GitHub-native behavior, and Cursor Rules for scoped IDE workflows. - Move enforcement into checks. Secrets, deploy permissions, JSON validity, and bilingual file requirements should be verified by scripts, CI, hooks, permissions, or review gates.
- Test in a fresh session. Ask the agent to summarize loaded rules, then give it a small safe task. If it misses the commands or done criteria, shorten the file and make the rules more concrete.
Avoid vague preferences like "write clean code" or "be careful." Replace them with observable checks: run this command, inspect this path, preserve this API, do not edit this directory, report this risk.
Decision tree
Is this rule useful for every tool in the repo?
Yes -> put it in AGENTS.md.
No -> continue.
Is it specific to Claude Code memory or Claude workflows?
Yes -> put it in CLAUDE.md or Claude rules.
No -> continue.
Is it specific to GitHub Copilot behavior?
Yes -> put it in .github/copilot-instructions.md or scoped GitHub instructions.
No -> continue.
Is it specific to Cursor files, globs, or IDE workflows?
Yes -> put it in Cursor Rules.
No -> continue.
Does it need deterministic enforcement?
Yes -> implement a script, CI check, hook, permission, or review gate.
No -> keep it in the smallest relevant instruction file.
Starter AGENTS.md template
# AGENTS.md
## Project context
- Product purpose:
- Main paths:
- Content or product boundaries:
## Commands
- Check:
- Test:
- Build:
## Working rules
- Prefer existing patterns.
- Keep edits scoped.
- Do not deploy, publish, or submit indexing without explicit approval.
## Verification
- Before claiming success, run:
- If a command cannot run, report why and name the remaining risk.
Keep the first version boring. The best file is the one the agent can actually follow.
Common mistakes
- Copying another repo's file. It encodes another team's tools, risks, and review habits.
- Mixing preferences with enforcement. "Never expose secrets" is weaker than secret scanning, ignored env files, and review steps.
- Duplicating the same rule in five places. Shared rules belong in
AGENTS.md; tool-specific files should exist only when the tool needs a different form. - Treating instruction files as permanent. Update them when repeated failures appear, and trim them when rules become stale.
FAQ
Should AGENTS.md and CLAUDE.md contain the same content?
Not usually. Put shared project rules in AGENTS.md. Add CLAUDE.md when Claude Code needs Claude-specific memory, rules, or workflow notes. If both exist, make one reference the shared contract so the files do not drift.
Is AGENTS.md enough for security?
No. It can remind the agent about secrets, permissions, and risky commands, but enforcement belongs in permissions, hooks, CI, secret scanning, and human review.
How long should the file be?
Short enough that a new contributor can scan it. If it grows into a manual, move repeated workflows into scripts, skills, or runbooks.
Where should IndieSeek link this article?
Natural internal links are the Codex Record & Replay principles article for reusable agent workflows and MD+HTML Reader for reviewing AI-generated Markdown or HTML before publishing.
Top comments (0)