How to write a CLAUDE.md or AGENTS.md, with a template

A working CLAUDE.md or AGENTS.md needs five things: build commands, conventions, a three sentence architecture summary, hard constraints and known gotchas. Leave out anything the agent can already read from the code itself. The copy-paste template below covers all five, and Mover OS's free templates (12 kinds of work, one file per tool) start you from a filled-in version.

Last verified 29 September 2026. Every priced or limited claim below links to its source.

How do you start a CLAUDE.md fast?

Claude Code's /init command explores the current codebase and drafts a starting CLAUDE.md covering build commands, test commands, a structure overview and detected conventions, ready for you to review and trim. source, checked 29 September 2026.

Codex has no dedicated bootstrap command documented for AGENTS.md; the file is picked up automatically once it exists on the discovery path, so you write the first draft yourself or copy one from a working project. source, checked 29 September 2026.

What belongs in the file?

Anthropic's own guidance for CLAUDE.md: commands for build, test, lint and running locally, naming and error handling conventions, architecture in about three sentences, hard constraints such as never writing to a production database from tests, and the gotchas every new engineer trips on. source, checked 29 September 2026.

Leave out full API documentation the agent can read directly, changelogs, anything obvious from the file tree, and aspirational rules the team does not actually follow. The same holds for AGENTS.md: OpenAI's own advice is to keep it small and start with only the instructions that matter. source, checked 29 September 2026.

What does a copy-paste CLAUDE.md look like?

This template follows the five parts in Anthropic's own guidance above. Replace every line in square brackets with a fact from your project, delete any section you cannot fill honestly, and keep the result under about 200 lines. The same text works as an AGENTS.md for Codex if you rename the file.

# [Project name]

[One sentence: what this project does and who uses it.]

## Commands
- Install: [command]
- Run locally: [command]
- Test all: [command]
- Test one file: [command]
- Lint and format: [command]

## Conventions
- Naming: [for example, camelCase for functions, PascalCase for types]
- Errors: [how errors are raised and logged here]
- Tests: [where they live and what a new test must cover]

## Architecture
[Three sentences: the main modules, how data flows between them, and where the entry point is.]

## Hard constraints
- Never [action that could damage production data, for example write to the live database from tests].
- Never commit [secrets, generated files or build output].
- Ask before [an irreversible step, for example a schema migration].

## Known gotchas
- [A trap every new engineer hits, and the fix.]
- [A flaky test or slow command, and how to handle it.]

How long can the file be?

Claude Code has no hard cap, but files over roughly 200 lines measurably reduce adherence, per Anthropic's own docs. AGENTS.md has a hard 32 KiB combined cap across every file Codex loads for a project, and anything past that point is silently dropped with no warning shown. If your file is growing past either limit, split it into smaller, topic specific files and reference them, or scope guidance to nested subdirectories rather than one root file. source, checked 29 September 2026.

How do you keep it current?

Anthropic's own advice: update the file after /init, when the agent gets something wrong twice, when conventions change, and on a quarterly skim to delete anything stale, since outdated instructions are worse than none. OpenAI gives the same advice for AGENTS.md: when the agent makes a wrong assumption, correct it in the file and tell the agent to update it, so the fix survives the next session. source, checked 29 September 2026.

Common questions