Skip to main content

CLAUDE.md and AGENTS.md: Writing Context Files for AI Agents

By the OnlineAppCreator editorial team4 min read

Short answer

CLAUDE.md (read by Claude Code) and AGENTS.md (read by OpenAI Codex and a growing number of other agents) are Markdown files that give a code agent persistent project knowledge. Good ones are short, specific and testable: exact build and test commands, architecture pointers, conventions the agent gets wrong without guidance and hard boundaries. They are maintained like code, updated whenever the agent repeats an avoidable mistake.

On this page
  1. What belongs in a context file
  2. Structure and length
  3. Nesting and scope
  4. A process for writing and maintaining the file
  5. Common mistakes
  6. How context files fit into briefs
  7. Build yours in a workshop

Every session with a code agent starts with a blank memory. A context file fixes that by telling the agent what any experienced team member already knows: how to build and test the project, where things live, which conventions apply and what must never happen. Claude Code reads CLAUDE.md files; OpenAI Codex reads AGENTS.md, a format that many other agents also support; Cursor uses project rules. The principles are the same for all of them, and this article covers how to write context files that measurably improve agent output.

What belongs in a context file

Think of the file as the onboarding note for a capable contractor who will never ask a question. The most useful content falls into five groups.

Commands

Exact commands to install dependencies, build, run tests (including a single test), lint, format and start the app locally. This is the highest-value content because it closes the agent's feedback loop. Write them as they are actually typed, not as descriptions.

Architecture pointers

A few lines on the main modules, where business logic lives, how data flows and which directories are generated or vendored and should not be edited. Point to files rather than explaining their contents in detail.

Conventions the agent gets wrong

Do not restate general good practice the model already knows. List the conventions specific to your codebase, such as which HTTP client wrapper to use, how errors are reported, naming patterns or the test framework style. The best entries come from observed mistakes.

Boundaries

Things the agent must not do: change migrations that have already run, modify public API contracts without approval, add dependencies without asking, touch certain configuration files or commit secrets. Phrase them clearly and briefly.

Workflow expectations

How work should be delivered: run tests before declaring done, keep changes focused, write commit messages in a certain format or update the changelog.

Structure and length

Shorter files are followed more reliably. Context files compete with the actual task for the agent's attention, and a long file full of general advice dilutes the important lines. Use headings, short sentences or compact lists and concrete examples. If a section grows large, move it to a separate document and reference it, so the agent reads it only when relevant. A useful test is to read each line and ask whether removing it would change the agent's behaviour; if not, cut it.

Nesting and scope

Both formats support files at several levels. A root file covers the whole repository, while files in subdirectories add specifics for that part, for example a frontend folder with its own conventions. Claude Code also distinguishes between project files committed for the whole team and personal or user-level settings that stay local. In monorepos, nested files keep each team's rules close to its code and stop the root file from turning into a catalogue. Check the current documentation of your tool for the exact lookup order, as behaviour is refined regularly.

One file or two?

Teams using both Claude Code and Codex often ask whether to maintain both files. A practical pattern is to keep the shared content in AGENTS.md and let CLAUDE.md reference it or contain only Claude-specific notes, so there is one source of truth. Some teams use a symbolic link. Whatever you choose, avoid two diverging files that say different things about the same project. Our comparison of Claude Code and OpenAI Codex covers other differences that matter for mixed teams.

A process for writing and maintaining the file

  1. Let the agent draft a first version by exploring the repository; Claude Code, for example, offers an init command for this.
  2. Edit the draft by hand: correct commands, remove generic advice and add boundaries.
  3. Test it with three typical tasks and note every mistake the agent makes.
  4. Add a specific instruction for each repeated mistake, then test again.
  5. Commit the file, review changes to it in pull requests like any code and assign an owner.
  6. Revisit it after major refactors, tool upgrades or whenever the team notices recurring errors.

Common mistakes

The most frequent is copying a long generic template from the internet. It looks thorough but adds noise. Another is writing aspirations rather than facts, such as describing the architecture you want instead of the one you have; the agent will then generate code for a codebase that does not exist. A third is including secrets, internal hostnames or customer names. Context files are committed and shared; treat them as public within your organisation. Our guide to secure agentic coding practices covers this and other guardrails. Finally, many teams write the file once and never touch it again, while the codebase keeps changing.

How context files fit into briefs

A context file is not a substitute for a good task description. It holds what is true for every task; the brief holds what is true for this one. Our article on prompting code agents explains how the two layers work together.

Build yours in a workshop

Writing a first context file is one of the most productive hours a team can spend with an agent. In our agentic coding workshops at neooutput, every team leaves with a tested CLAUDE.md, AGENTS.md or Cursor rules file for its own repository. We maintain the same kind of files in the products we build and launch.

Frequently asked questions

Where should CLAUDE.md be placed?

Usually in the repository root, committed so the whole team shares it. Additional files in subdirectories can add context for specific parts of the codebase, and personal settings can stay outside the repository.

Does Cursor read AGENTS.md?

Cursor primarily uses its own project rules, and support for AGENTS.md has been added to several tools over time. Check the current Cursor documentation; many teams keep shared content in one file and reference it from others.

How long should a CLAUDE.md file be?

As short as possible while still covering commands, architecture pointers, specific conventions and boundaries. Many effective files fit on one or two screens, with longer material linked in separate documents.

Can the agent update its own context file?

Yes, and it can be useful to ask the agent to propose additions after a mistake. A human should still review those changes before they are committed.

Want this done right, the first time?

OnlineAppCreator takes products from idea to operation. Tell us where you stand and get a concrete plan in a free 15-minute call.