How to Use an AGENTS.md File for Client Work with Claude Code
- An AGENTS.md is a plain markdown file in a project root that AI coding agents read automatically when they open the project, so it is the one place project rules live and travel with the code instead of living in your head.
- For client work, it does the same job as a project brief but in a portable, tool-agnostic format: write the rules once and any agent or teammate who opens the repo starts from the same standing context, which stops a paid build from drifting between sessions.
- Keep it to one screen, in five blocks - outcome, stack and limits, commands, conventions, and boundaries - and never put credentials or client data in it, because the file ships with the repository.
What an AGENTS.md File Is
An AGENTS.md is a plain markdown file you put in the root of a project folder that describes how an AI coding agent should behave in that project. When you open the project, the agent reads the file automatically and treats it as standing context for every request you make afterwards. You do not paste it, link to it, or remind anyone it exists. The rules are simply in effect from the first message of the session.
Think of it as the project's operating manual written for a coding agent rather than a human. It names what the project is, the stack it runs on, the exact commands that work, the conventions to follow, and the things that must never be touched. On a personal project that saves you some retyping. On a client project it is infrastructure, because a paid build runs across many separate sessions over weeks, and without a written brief every session starts from nothing and the codebase slowly argues with itself.
AGENTS.md vs CLAUDE.md: Which One to Use
The short answer: they do the same job, and AGENTS.md is the portable version. CLAUDE.md is the file Claude Code reads; AGENTS.md is a tool-agnostic name that a growing set of coding agents read. For client work the practical rule is simple - write your standing brief once, and if you want it to survive a teammate switching tools or a client's own developer opening the repo later, an AGENTS.md carries further than a tool-specific file does.
| Question | CLAUDE.md | AGENTS.md |
|---|---|---|
| Who reads it | Claude Code specifically | A tool-agnostic set of coding agents |
| Where it lives | Project root, travels with the repo | Project root, travels with the repo |
| Best for | A Claude-Code-only workflow | A repo that outlives one tool or one builder |
| What goes in it | Outcome, stack, commands, conventions, boundaries | The same five blocks, written portably |
How the two files compare for a paid build
You do not have to pick a side. Many builders keep one canonical brief and point the other file at it, so there is a single source of truth rather than two files that drift apart. The content is identical either way, which is why the [five-block template for a CLAUDE.md](/blog/claude-md-file-for-client-projects) applies directly to an AGENTS.md. Learn the blocks once and the filename becomes a detail.
The Five Blocks to Put in a Client AGENTS.md
Write the file in five blocks, in this order: outcome, stack and limits, commands, conventions, boundaries. This is the Profit Room's Portable Brief, and the order is the point. Instructions near the top of a long context carry more weight, so the things you least want ignored go first.
- Outcome: one short paragraph on what the project is for and who uses it, in the client's language. This stops technically correct work that solves the wrong problem.
- Stack and limits: the languages, frameworks, versions, and what may not be added. This prevents dependency sprawl and a second way of doing everything.
- Commands: the exact commands to install, run, test, build, and deploy. This kills invented commands and broken verification steps.
- Conventions: file structure, naming, the patterns to copy, and the review rules. This keeps the codebase from being written in four different styles.
- Boundaries: the files, systems, and data that must never be touched. This is the block that prevents the expensive kind of mistake on a live client system.
Keep the whole thing to roughly one screen of text. A long brief is a worse brief - every line you add dilutes the ones that matter, and a file full of aspirational rules nobody enforces trains you to stop trusting it. If a rule has not mattered in three sessions, delete it. This same discipline is what keeps a build inside its agreed shape, which connects directly to [stopping scope creep on a Claude Code project](/blog/stop-scope-creep-on-a-claude-code-project).
Why a Portable Brief Pays Off on Paid Work
The file is the cheapest scope document you will ever write. When the rules of the project are written into the repo, the boundary between what was agreed and what is a new request stops being a memory exercise. If a client asks for something outside the outcome block, you have a written reference for why it is a change rather than a continuation, which makes the [one-page agreement you send before you build](/blog/one-page-agreement-before-you-build) easier to hold to.
It also protects the handoff. A build that ships with a clean AGENTS.md is one a client's own developer, or the next builder you subcontract, can pick up without a call. That reduces the support tail on a delivered project and makes the work look more professional, which is the same instinct behind [delivering a build so clients come back](/blog/deliver-a-build-so-clients-come-back). The brief is part of the deliverable, not scaffolding you throw away.
Short, practical drops on offers, outreach, pricing, and closing clients with Claude Code. No spam, unsubscribe anytime.
Frequently asked
What is an AGENTS.md file used for?
An AGENTS.md is a plain markdown file in a project root that tells an AI coding agent how to behave in that project. The agent reads it automatically at the start of a session, so it becomes standing context for every request. For client work it holds the project outcome, the stack and its limits, the exact commands that work, the conventions to follow, and the boundaries that must not be crossed, so the build stays consistent across many separate sessions instead of drifting each time you reopen it.
Is AGENTS.md the same as CLAUDE.md?
They do the same job. CLAUDE.md is the file Claude Code reads specifically, while AGENTS.md is a tool-agnostic name that a growing set of coding agents read. The content is identical - the same five blocks of outcome, stack, commands, conventions, and boundaries. For a repo that may outlive one tool or one builder, an AGENTS.md carries further, and many builders keep one canonical brief and point the other file at it so there is a single source of truth.
What should I never put in an AGENTS.md file?
Never put credentials, API keys, or client data in it. The file ships with the repository, so anything in it travels to anyone who gets the code. Secrets belong in your environment configuration, and personal tool preferences belong in your own user-level settings, not in a file you may hand to the client or a subcontractor.
How long should an AGENTS.md be?
About one screen of text. A long brief is a worse brief, because every extra line dilutes the rules that actually matter and a file full of aspirational rules nobody enforces trains you to stop trusting it. Keep the five blocks tight, and if a rule has not mattered in three sessions, delete it.
Does an AGENTS.md help with client handoff?
Yes. A build that ships with a clean AGENTS.md can be picked up by the client's own developer or the next builder without a walkthrough call, because the outcome, stack, commands, conventions, and boundaries are all written in the repo. That shortens the support tail after delivery and makes the work look more professional, and it doubles as a written scope reference if the client asks for something outside the original outcome.
Last reviewed September 16, 2026.
Co-founder of the Claude Code Profit Room. Went from shipping software to closing paying clients, and now teaches builders the selling half of the equation.
More from David Iya →
