Agentic Coding Workshops

CLAUDE.md and AGENTS.md: Project Instructions for Agents

By the UXreviewer.io team4 min read

CLAUDE.md and AGENTS.md are Markdown files in your repository that coding agents read to learn how your project works: build and test commands, architecture, conventions and boundaries. CLAUDE.md is used by Claude Code, while AGENTS.md is a shared convention read by ChatGPT Codex and a growing number of other agents. A good file is short, specific, accurate and maintained like code.

Without such a file, every session starts from zero and developers repeat the same explanations in prompts. With a bloated or outdated file, agents follow wrong instructions confidently. This guide explains what to include, what to leave out, how to structure the file and how to keep it current.

CLAUDE.md vs AGENTS.md: which one do you need?

As of late 2026, Claude Code loads CLAUDE.md files automatically, from the repository root and, where present, from subdirectories and user-level locations. AGENTS.md emerged as a tool-neutral convention supported by Codex and several other agents and IDEs. Support details change, so check your tools' current documentation.

If your team uses more than one agent, a practical approach is to keep the shared content in AGENTS.md and have CLAUDE.md reference or import it, adding only Claude-specific notes. The important thing is a single source of truth, so the instructions never contradict each other.

What to include

Focus on information the agent cannot easily infer from the code, or tends to get wrong. A useful set of contents:

A quick way to find the right content is to look at recent review comments on agent-generated pull requests. Corrections that appear repeatedly, such as using the wrong test helper, putting files in the wrong folder or ignoring a logging convention, are exactly what the file should state. Equally, note the questions new human team members ask in their first weeks; agents struggle with the same gaps.

  • Commands: how to install dependencies, run the app, run all tests, run a single test, lint and type-check.
  • Architecture in brief: main folders and what lives where, key modules, data flow in a few sentences.
  • Conventions: naming, file structure, preferred libraries, error handling and logging patterns.
  • Boundaries: generated files, vendored code, migrations or configuration the agent must not edit without asking.
  • Workflow rules: plan before large changes, write tests first for bug fixes, keep commits small.
  • Known pitfalls: quirks of the build, flaky tests, deprecated modules still in the codebase.
  • Definition of done: which checks must pass before the agent reports a task complete.

What to leave out

More text is not better. Every line competes for the agent's attention and your context window. Keep these out of the file:

  • Secrets, tokens, internal URLs with credentials or customer data.
  • Long copies of framework documentation the model already knows.
  • Generic advice such as "write clean code" that changes nothing.
  • Outdated instructions, which are worse than none because agents follow them.
  • Personal preferences of one developer; those belong in local, untracked settings.

Want an expert opinion on your product?

Talk to a UX expert or AI Code Engineer — 30 minutes, free, no obligation.

Book a call for free

A structure that works

There is no single required format, but a predictable order helps both agents and humans. As a rule of thumb, aim for a file a developer can read in a few minutes. A sequence many teams use:

  1. One paragraph describing what the project is and who uses it.
  2. Setup and everyday commands as a short list.
  3. Architecture overview with the most important folders.
  4. Coding conventions as concise, testable rules.
  5. Workflow expectations: planning, testing, commits and pull request descriptions.
  6. Boundaries and areas requiring explicit approval.
  7. Pointers to deeper documentation files for specific subsystems.

Writing rules agents actually follow

Specific, checkable rules work better than abstract ones. "Use the shared fetch wrapper in the api folder for all HTTP calls" is far more effective than "follow our API patterns". Positive instructions, stating what to do, are generally followed more reliably than lists of prohibitions, though hard boundaries should still be explicit.

Give short examples where a pattern is unusual, such as how a new endpoint or component should look. For large monorepos, place additional instruction files in subdirectories so the agent receives relevant context only when it works there. And include user-facing rules too, such as tone for error messages or accessibility requirements for UI components; agents will not infer those on their own.

Maintaining the file over time

Treat the instructions file like code. Changes go through pull requests, someone owns it, and it is updated when the codebase changes. The best trigger for an update is a repeated agent mistake: if reviewers correct the same thing twice, it becomes a rule.

Periodically prune rules that no longer apply and test the file by giving a fresh agent session a typical task. If it asks questions the file should answer, add them. For how instruction files fit into wider team practices, see agentic coding best practices and spec-driven development with AI agents.

Getting help

Drafting a first CLAUDE.md or AGENTS.md together is a standard exercise in the agentic coding workshops run by the UXreviewer.io team, including the Claude Code workshop for development teams. Teams leave with a reviewed file tailored to their repository. Book a call for free if you would like support.

Frequently asked questions

How long should a CLAUDE.md or AGENTS.md file be?

Short enough to read in a few minutes. Many effective files are a page or two; larger projects add subdirectory files or link to deeper documentation instead of growing one huge file.

Can I use both CLAUDE.md and AGENTS.md in one repository?

Yes. Keep shared rules in one place and let the other file reference it, so there is a single source of truth and no contradictions.

Should the instructions file be committed to Git?

Yes, the project-level file should be versioned and reviewed like code. Personal preferences belong in local or user-level files that are not committed.

Does an instructions file guarantee the agent follows our rules?

No. It improves consistency significantly, but agents can still deviate. Automated checks such as linting, tests and code review remain essential.

Book a call for free

From UX audits and Agentic UX reviews to AI development, agentic coding workshops and publishing your AI-built app on the App Store and Google Play — we help you ship. 24/7 call support in English and German.

Related insights

Agentic Coding Workshops

Spec-Driven Development with AI Coding Agents

Prompting an agent with a one-line request works for small fixes. For real features, a short written spec turns agent output from a gamble into a predictable result.