How to write CLAUDE.md and AGENTS.md for coding agents

Short answer: CLAUDE.md (for Claude Code) and AGENTS.md (read by Codex and a growing number of other agents) are plain Markdown files in your repository that every session reads first. Put in how to build and test, where things live, rules the agent must follow and what never to touch. Keep it short, specific and current.

Every coding agent starts a session knowing nothing about your project. A project instructions file is how you tell it, once, what you would otherwise repeat in every prompt.

Disclosure: we build Zokie, an agent IDE that runs Claude Code, Codex, Gemini CLI and Cursor CLI. These files work the same with or without it.

Which file does which agent read?

If your team uses more than one agent, keep the real content in one file and point the others at it, so the rules never drift apart.

What to put in it

How to build, run and test

The exact commands: install, dev server, tests, lint, type check. Agents that can test their own work make far fewer mistakes.

Where things live

A few lines on the layout: "API routes are in api/, shared UI in components/ui/, database queries only in lib/db/."

Rules

Conventions the agent cannot guess: naming, which library to use for dates, how errors are returned, commit message format.

Never

The hard limits: "never edit generated files in gen/", "never run migrations", "never read or print .env".

What to leave out

• Things the code already says. The agent can read your folder structure; describe only what is not obvious.
• Long essays. Every line costs context in every session. One page is plenty.
• Wishes. "Write clean code" changes nothing. "Functions over 80 lines get split" does.
• Secrets. Never put keys or passwords in these files; they are committed to the repository.

A template you can copy

# Project notes for coding agents

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test
- Check before finishing: pnpm typecheck && pnpm test

## Layout
- app/: pages and routes
- lib/: shared logic; database access only in lib/db
- components/ui/: shared UI, reuse before adding new components

## Rules
- TypeScript strict; no `any`
- Dates with date-fns, never moment
- Errors: return { ok: false, error }, never throw from route handlers
- Commit messages: type(scope): description

## Never
- Edit files in gen/ (generated)
- Run database migrations
- Read or print .env files

Keep it alive

Treat the file like code. When you correct the agent twice for the same thing, add a rule. When a rule stops being true, delete it. Review it in pull requests like any other file.

In Zokie, corrections can become team knowledge: on a Team plan, guardrails written once are pushed to every seat, so new teammates and their agents follow the same rules from day one.

FAQ

What is the difference between CLAUDE.md and AGENTS.md?

They do the same job for different agents. Claude Code reads CLAUDE.md; Codex and other tools that follow the AGENTS.md convention read AGENTS.md. Many teams keep one and point the other at it.

Where should CLAUDE.md go?

In the root of your repository, committed to git so the whole team shares it. You can add more in subfolders for area-specific rules, and a personal one in your home folder.

How long should CLAUDE.md be?

Short. Around one page of specific commands, layout notes, rules and limits works better than a long document, because every session reads all of it.

Can CLAUDE.md stop the agent from doing something?

It asks the agent not to, and agents usually follow it. For rules that must never be broken, add a technical guard such as a hook, a permission setting or a protected branch.