---
title: "AGENTS.md vs CLAUDE.md: Project Instructions for Coding Agents"
date: "2026-06-14"
author: "Graham"
description: "A practical comparison of AGENTS.md and CLAUDE.md: what each file is for, what to put inside, and how to write durable instructions for Codex and Claude Code."
tags: ["Developers", "Power of AI"]
url: "https://powerofai.ca/agents-md-vs-claude-md"
readTime: "6 min"
---

# 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

```text
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](/codex-best-practices): Use AGENTS.md well with Codex.
- [Claude Code Best Practices](/claude-code-best-practices): Use CLAUDE.md well with Claude Code.
- [AI Coding Agents](/ai-coding-agents): Understand the broader coding-agent workflow.

## Sources and official references

- [OpenAI AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md)
- [Anthropic Claude Code memory](https://docs.anthropic.com/en/docs/claude-code/memory)