Agentic Coding Tools

How to Write CLAUDE.md and AGENTS.md Files That Actually Help

A good CLAUDE.md or AGENTS.md file tells a coding agent the few things it cannot easily infer from the code: exact build and test commands, architecture landmarks, team conventions, forbidden actions and how to verify a change. Keep it short, specific and maintained, and it will improve every single agent session in your repository.

neooutput editorial team 4 min read Auf Deutsch lesen

What are CLAUDE.md and AGENTS.md?

They are Markdown files in your repository that coding agents read automatically to understand how to work in your project.

Claude Code reads CLAUDE.md files, which can be placed in the repository root and in subdirectories, and also supports personal memory files that are not committed. AGENTS.md is an open convention read by OpenAI Codex and a growing number of other agents. Content-wise they serve the same purpose: they are onboarding documentation written for an agent, and they often turn out to be useful for new human team members too.

What to include

Include information that is essential, non-obvious and stable.

  • Commands: how to install dependencies, build, run all tests, run a single test, lint and format.
  • Architecture landmarks: where the main modules live, how requests flow, which directories are generated.
  • Conventions that differ from defaults: error handling, naming, state management, logging.
  • Verification: what must pass before a task is considered done.
  • Hard rules: files or directories never to edit, commands never to run, dependencies not to add without approval.
  • Known pitfalls: flaky tests, environment quirks, legacy areas that need special care.

What to leave out

Leave out anything the agent can read from the code itself, anything that changes weekly and generic advice.

Long descriptions of every module, copied API documentation, motivational instructions like 'write clean code' and outdated architecture notes all dilute the signal. Every line in the file consumes context and competes for the agent's attention. A focused file with a few dozen precise lines usually outperforms a sprawling document. If you need detailed documentation, link to it from the file and let the agent read it when relevant.

A practical structure

A simple, consistent structure makes the file easy to scan for both agents and humans.

  1. One-paragraph project overview: what it is, main technologies.
  2. Commands section with exact, copy-pasteable commands.
  3. Project structure: key directories and their purpose.
  4. Conventions: short bullet list of team-specific rules.
  5. Workflow: plan before large changes, keep diffs small, run tests before finishing.
  6. Do not: explicit list of forbidden actions.

Monorepos and nested files

In monorepos, use a short root file for shared rules and nested files in packages for package-specific commands and conventions.

Claude Code picks up CLAUDE.md files in subdirectories when working there, and AGENTS.md conventions also allow nested files, with the closest file typically taking precedence. This keeps each file small and relevant. Avoid repeating root content in every nested file; repetition makes updates error-prone.

Keeping it current

Treat the context file like code: review changes in pull requests and update it whenever an agent repeatedly makes the same mistake.

A useful habit is a short retrospective after agent sessions that went wrong: would one sentence in the context file have prevented it? If yes, add it. Equally, remove lines that no longer apply. Some teams assign an owner per file. If you use both Claude Code and Codex, keep one canonical file and reference it from the other to avoid drift.

Common mistakes

The most frequent mistakes are files that are too long, too vague or never updated.

Other issues include instructions that contradict the actual tooling, secrets or internal URLs that should not be in the repository, and rules written as wishes rather than checkable instructions. 'Run the full test suite with this command before finishing' is actionable; 'make sure everything works' is not. In neooutput's agentic coding workshops, teams write and prune their own context files on their real codebase, which is often the single most impactful hour of the day.

Frequently asked questions

Should I use CLAUDE.md or AGENTS.md?

Use the file your primary tool reads. Claude Code reads CLAUDE.md, Codex and several other agents read AGENTS.md. If your team uses both, keep one canonical file and reference it from the other.

How long should the file be?

As short as possible while covering commands, structure, conventions and hard rules. Many effective files are well under a few hundred lines; brevity improves focus.

Can the agent write the file itself?

An agent can produce a useful first draft by exploring the repository. A human should then prune it, correct it and add the non-obvious knowledge that only the team has.

Should secrets or internal URLs go into the context file?

No. The file is committed to the repository and read by agents that send context to model providers. Keep credentials out entirely and reference internal systems only as far as necessary, without tokens or passwords.

All insights