AI coding tools like Codex and Claude Code work better when they understand your project.

That is what AGENTS.md and CLAUDE.md are for.

  • AGENTS.md gives AI coding agents instructions about your repository.

  • CLAUDE.md gives Claude Code project-specific instructions.

These files can explain:

  • what the project does,

  • where important code lives,

  • which commands to run,

  • how the architecture works,

  • which coding conventions to follow,

  • how to test changes,

  • and what files should not be modified.

Instead of writing these files manually, you can let Codex or Claude Code inspect your repository and create them for you.

The Important Rule

The AI should inspect your repository before writing anything.

It should never guess your:

  • commands,

  • package manager,

  • architecture,

  • file paths,

  • technologies,

  • or coding conventions.

Your repository should always be the source of truth.

Copy and Paste This Prompt

Run Codex or Claude Code from the root of your project and paste:

Analyze this repository and create:

- AGENTS.md
- CLAUDE.md

First, inspect the repository before creating anything.

Review relevant files such as:

- README and documentation
- package manifests and lockfiles
- project configuration
- source directories
- test configuration
- linting and formatting configuration
- CI/CD workflows
- environment examples
- database schemas and migrations
- existing AGENTS.md or CLAUDE.md files

Use the repository as the source of truth.

Do NOT invent commands, paths, technologies, architecture, or coding conventions.

Create a concise AGENTS.md that explains:

1. Project Overview
   - What the project does.

2. Repository Structure
   - Important folders, apps, packages, and their purpose.

3. Technology Stack
   - Only technologies verified in the repository.

4. Development Commands
   - Install
   - Development
   - Build
   - Test
   - Lint
   - Format
   - Typecheck
   - Database commands, if applicable

Only include commands that actually exist.

5. Architecture
   - Explain where new features normally belong.
   - Explain important architectural boundaries.

6. Coding Conventions
   - Document patterns actually used by the project.

7. Rules for AI Agents
   - Inspect nearby code before editing.
   - Follow existing patterns.
   - Keep changes focused on the requested task.
   - Avoid unrelated refactoring.
   - Update tests when behavior changes.
   - Do not manually edit generated files.
   - Do not expose secrets.
   - Avoid new dependencies unless necessary.

8. Testing and Validation
   - Explain which verified commands should be run before finishing a change.

9. Environment and Secrets
   - Explain environment-variable setup without copying real secrets.

10. Important Documentation
   - Link to existing project documentation instead of duplicating it.

Keep AGENTS.md short, practical, and easy for an AI coding agent to scan.

Also decide whether nested AGENTS.md files are needed for areas such as:

- apps/web
- apps/api
- packages/ui
- services/backend

Only create them if those areas have significantly different commands, architecture, or conventions.

Then create CLAUDE.md.

Avoid copying all of AGENTS.md into CLAUDE.md.

Use AGENTS.md as the main shared project instructions when possible, and keep CLAUDE.md focused on Claude-specific guidance.

If AGENTS.md or CLAUDE.md already exists:

- preserve useful information,
- fix outdated or incorrect instructions,
- remove unnecessary duplication.

Before finishing:

- verify all paths exist,
- verify all commands exist,
- verify the package manager is correct,
- verify documented architecture matches the code,
- make sure no secrets were copied,
- make sure AGENTS.md and CLAUDE.md do not contradict each other.

Do not modify application code.

When finished, summarize:

- files created or updated,
- important project details discovered,
- commands documented,
- conventions captured,
- nested AGENTS.md files created, if any.

Why This Works

A weak prompt says:

Create an AGENTS.md for my project.

A better prompt says:

Inspect my project first, verify how it actually works, then document it.

The workflow becomes:

Inspect Repository
      ↓
Understand Project
      ↓
Verify Commands
      ↓
Identify Conventions
      ↓
Create AGENTS.md
      ↓
Create CLAUDE.md
      ↓
Verify Everything

Keep AGENTS.md Simple

Your AGENTS.md does not need to contain everything about your project.

It only needs to help the AI answer:

  • What is this project?

  • Where is the code I need?

  • What pattern should I follow?

  • What should I avoid changing?

  • What commands should I run?

  • How do I verify my work?

If detailed documentation already exists, link to it instead of copying it.

Final Tip

Treat AGENTS.md as the AI onboarding guide for your repository.

A good file tells Codex or Claude Code:

where to look, how to work, what not to break, and how to verify the result.