AGENTS.md vs CLAUDE.md: Project Instructions for Coding Agents

AGENTS.md and CLAUDE.md solve the same human problem: you do not want to explain your repo from scratch every time you open an AI coding agent.

They are project briefing files. Used well, they make agent work calmer, safer, and more consistent.

Quick picks

• Use AGENTS.md for: Codex and repo-wide agent guidance. It is the OpenAI Codex convention for durable project instructions.
• Use CLAUDE.md for: Claude Code project memory. It is the Claude Code convention for recurring project context and commands.
• Put in both: Commands, conventions, risks. If you use both tools, keep the core rules aligned so agents do not behave differently.
• Avoid: Long vague manifestos. Agents need operational instructions they can act on.

What these files should contain

The best project instruction file is short, specific, and boring. It tells the agent how this repo works and how to verify changes.

Think of it as onboarding notes for a developer who can read fast but still needs direction.

• Project purpose and major folders.
• Install, dev, build, typecheck, lint, and test commands.
• Coding style and architecture conventions.
• Generated files, deployment files, and risky areas.
• Content voice if the repo includes writing.
• What the agent must report before finishing.

What not to put there

Do not put secrets, API keys, passwords, or private customer data in project instruction files. Do not turn them into long policy documents the agent has to skim every time.

If a rule is not actionable, rewrite it or remove it.

If you use both Codex and Claude Code

Keep AGENTS.md and CLAUDE.md consistent. You do not need them to be identical, but the commands, style rules, and safety boundaries should agree.

The practical move is to write one source of truth and mirror the important parts into the other file.

Copyable prompts

Project instruction file generator

Inspect this repo and draft AGENTS.md and/or CLAUDE.md. Include overview, commands, conventions, risky files, generated-file rules, verification commands, and final response expectations. Keep it under 120 lines unless the repo truly needs more.

Related Power of AI pages

• Codex Best Practices: Use AGENTS.md well with Codex.
• Claude Code Best Practices: Use CLAUDE.md well with Claude Code.
• AI Coding Agents: Understand the broader coding-agent workflow.

Sources and official references

• OpenAI AGENTS.md guide
• Anthropic Claude Code memory

Related Power of AI pages

Keep reading with AI Finder, Prompt Studio, ChatGPT vs Claude vs Gemini, the AI glossary, and Which AI Should You Use?.