AGENTS.md vs CLAUDE.md: How to Give AI Coding Agents Better Instructions

Most people blame vibe-coding agents for bad output. Sometimes the agent is the problem. Often, the instructions are the problem.

If every session starts with you explaining your stack, folder structure, testing commands, security rules, and preferences again, you are working harder than necessary.

This is where AGENTS.md and CLAUDE.md matter.

AGENTS.md is used by Codex to load repository-specific guidance before work begins. CLAUDE.md is used by Claude Code to remember project instructions and context. Different files, same basic goal: stop making the agent guess how your project works. If you are also deciding which tool to use for which job, see Claude Code vs Codex.

Quick answer

Use AGENTS.md for Codex. Use CLAUDE.md for Claude Code. Both files should explain your stack, project structure, coding rules, testing commands, security boundaries, and review expectations.

The simplest version:

AGENTS.md = instructions for Codex
CLAUDE.md = instructions for Claude Code

If you use both Codex and Claude Code in the same project, create both files. Keep them similar, but not necessarily identical.

Why instruction files matter

AI coding agents are powerful, but they are not mind readers.

Without instructions, they infer. Inference is useful, but it is also where many bad decisions start.

The agent might:

• Add dependencies you did not want
• Create a new pattern instead of following the existing one
• Edit production config
• Skip tests
• Touch auth logic too casually
• Modify database rules without warning
• Create over-engineered abstractions
• Ignore your deployment constraints
• Use a library that does not fit your stack

A good instruction file reduces this.

It does not guarantee perfect work. It creates guardrails.

Think of these files as the project briefing you wish every junior developer read before touching the repo.

What AGENTS.md is for

Codex uses AGENTS.md for custom instructions. OpenAI’s documentation explains that Codex reads AGENTS.md files before doing work, allowing global guidance and project-specific overrides.

That makes AGENTS.md useful for:

• Repo-specific rules
• Testing commands
• Code review criteria
• Preferred libraries
• Files or areas to avoid
• Security warnings
• PR review guidance
• Style and architecture preferences

A basic AGENTS.md could look like this:

# AGENTS.md

## Project overview
This is a Next.js app using Supabase, Tailwind, and Vercel.

## Rules
- Keep changes small and focused.
- Do not add new dependencies without explaining why.
- Do not modify auth, payment, or Supabase RLS logic without approval.
- Prefer simple readable code over clever abstractions.
- Do not change environment variable names without approval.

## Commands
- npm run lint
- npm run typecheck
- npm run test

## Review focus
- Auth safety
- Database safety
- Edge cases
- Missing tests
- Mobile responsiveness
- Error and loading states

This is not fancy. It is useful. Fancy can wait.

What CLAUDE.md is for

Claude Code uses CLAUDE.md for persistent project instructions and memory. Anthropic documents CLAUDE.md as a way to give Claude Code project context and instructions.

CLAUDE.md is useful for:

• Long-term project standards
• Architecture decisions
• Debugging rules
• Refactoring preferences
• Tool usage expectations
• Testing and deployment instructions
• Security boundaries
• Known project constraints

A basic CLAUDE.md could look like this:

# CLAUDE.md

## Project context
This app is built with Next.js, Supabase, Tailwind, and Vercel.

## Working style
- Investigate before editing when debugging.
- Explain root cause before proposing fixes.
- Keep diffs small and reversible.
- Avoid large rewrites unless explicitly requested.
- Do not over-engineer early MVP features.

## Safety rules
- Do not edit Supabase RLS policies without approval.
- Do not edit auth flows without explaining risks.
- Do not touch production environment files.
- Do not introduce dependencies without justification.

## Checks
After meaningful changes, run:
- npm run lint
- npm run typecheck
- npm run test if tests exist

## Review checklist
- Auth scope
- Database queries
- Error handling
- Loading states
- Empty states
- Mobile responsiveness
- Deployment risk

The main difference is that CLAUDE.md can also become part of a broader Claude Code workflow involving memory, hooks, skills, subagents, and plugins.

AGENTS.md vs CLAUDE.md comparison

The best setup is not choosing one. If you use both tools, use both files.

What to include in both files

Most projects need the same core sections.

1. Project overview

Explain what the project is and what stack it uses.

Example:

## Project overview
This is a client-facing dashboard for clinic appointment follow-up. The stack is Next.js, Supabase, Tailwind, and Vercel.

This stops the agent from treating the repo like a generic sandbox.

2. Tech stack

Be specific.

## Stack
- Next.js App Router
- TypeScript
- Supabase Auth and Postgres
- Tailwind CSS
- Vercel deployment

If you prefer a specific package or pattern, say it.

If you do not want a package, say that too.

3. Non-negotiable rules

This is where you prevent expensive mistakes.

## Non-negotiable rules
- Do not touch production environment files.
- Do not edit auth logic without explaining the risk.
- Do not edit Supabase RLS policies without approval.
- Do not add dependencies unless necessary.
- Do not make large rewrites without a plan.

These are the rules that protect the project from “helpful” damage.

4. Commands

Tell the agent how to check its work.

## Commands
- npm run lint
- npm run typecheck
- npm run test
- npm run build

If a command is slow or unreliable, mention it.

Note: npm run build is slow. Run it only before deployment-level changes.

5. Review checklist

This is useful for both Codex and Claude Code.

## Review checklist
Before considering work complete, check:
- Does the feature handle loading states?
- Does it handle empty states?
- Does it handle errors?
- Is data scoped to the correct user?
- Are database writes validated?
- Are tests needed?
- Could this break deployment?

This gives the agent a standard for “done.”

Without that, “done” often means “I edited files and stopped talking.”

What not to put in these files

Do not turn AGENTS.md or CLAUDE.md into a novel.

Bad instruction files are too long, too vague, or full of motivational nonsense.

Avoid:

• Long business essays
• Generic coding advice
• Contradictory rules
• Outdated setup steps
• Secret keys or private credentials
• Personal notes that do not affect code
• Huge pasted docs that should be linked instead

The goal is guidance, not therapy for the repo.

Example: combined setup for a serious project

If I were setting up a Next.js and Supabase project, I would create both files.

AGENTS.md

# AGENTS.md

## Project
Next.js and Supabase SaaS dashboard.

## Rules
- Keep changes focused.
- Prefer simple readable code.
- Do not add dependencies without explaining why.
- Do not touch auth, billing, RLS, or env files without approval.
- Summarize changed files after every task.

## Commands
- npm run lint
- npm run typecheck
- npm run test

## Codex review focus
- Bugs
- Missing tests
- Security risks
- Database safety
- Regression risk

CLAUDE.md

# CLAUDE.md

## Project
Next.js and Supabase SaaS dashboard.

## Working style
- For debugging, investigate before editing.
- For refactoring, preserve behavior.
- Keep diffs small and reversible.
- Explain root cause before applying fixes.

## Safety
- Do not edit auth, billing, RLS, or env files without approval.
- Do not introduce new architecture unless requested.
- Do not over-engineer MVP features.

## Checks
Run lint and type checks after meaningful changes.

## Review checklist
- Auth scope
- Database access
- Error states
- Loading states
- Empty states
- Mobile layout
- Deployment risk

They overlap because the project rules are the same. They differ because the workflows are different.

Codex gets more task and review guidance.

Claude Code gets more investigation and refactoring guidance.

How often should you update them?

Update these files whenever the project gains a rule you do not want to repeat.

Examples:

• You changed the preferred folder structure
• You added a testing command
• You discovered a risky area of the app
• You decided not to use a certain dependency
• You changed deployment rules
• You added a new database safety requirement
• You learned that a previous pattern was bad

A good habit:

When the agent makes a mistake twice, add a rule.

That is how your instruction files become useful instead of decorative.

Final verdict

AGENTS.md and CLAUDE.md are not magic. They are project guardrails.

Use AGENTS.md to guide Codex.

Use CLAUDE.md to guide Claude Code.

Use both if both tools touch the repo.

The goal is simple: make the agent follow your project instead of making your project follow the agent.

That is how you reduce random dependencies, messy patterns, risky edits, and repeated explanations.

AI coding agents are powerful. Give them rules, or they will invent their own. And they will do it with confidence, which is always the dangerous part.

References

• Codex AGENTS.md
• Codex best practices
• Claude Code memory and CLAUDE.md
• Claude Code overview
• Claude Code hooks guide