AGENTS.md File — How Claude Code Reads It

AGENTS.md is a repository-level instruction file that Claude Code can read to understand your project’s conventions, workflows, and constraints before it starts editing code. This guide is from c-ai.chat, an independent Claude reference, not Anthropic, and it explains what agents.md is, how Claude Code uses it, where it helps, and when a different setup is better.

If you are trying to decide whether to add an agents.md file to your repo, the short version is simple: use it when you want Claude Code to follow stable project rules without repeating them in every prompt. If you are new to Claude’s coding tools, start with our Claude Code guide for the broader workflow.

• The short answer
• How it works
• What you’d actually do with it
• Vs. the alternatives
• Other questions readers ask
• The honest take

The short answer

An agents.md file is a plain Markdown file you place in a codebase so Claude Code can pick up project-specific instructions such as coding style, test commands, architecture rules, review expectations, and file-level guardrails. It is most useful for engineers and technical teams who want more consistent AI-assisted changes across repeated coding sessions.

• What it does · gives Claude Code persistent repo instructions
• Where it runs · in repositories used with Claude Code
• What it costs · no separate file fee; Claude plans start at $0/month, API usage is separate
• Who it’s for · developers, teams, and maintainers with repeatable project rules

Think of agents.md as a project briefing sheet for the model. Instead of typing “use pnpm, do not touch generated files, run unit tests before proposing a patch, and keep React components under 200 lines” every time, you write those rules once and keep them with the repository. Claude Code can then use that context when you ask it to inspect, edit, or explain the project.

That does not mean agents.md is magic or always enforced perfectly. Claude still depends on the actual prompt, the visible repo state, tool permissions, and the clarity of your instructions. A weak or vague agents.md file can be ignored, contradicted by later prompts, or interpreted too broadly. If you also use Claude through the API or compare usage tiers, our Claude pricing guide covers the cost side.

How it works

At a practical level, agents.md works as a local source of durable instructions for Claude Code. When Claude is working in a repository, it can read the file and incorporate those directions into how it plans changes, inspects files, chooses commands, and formats output. That makes it closer to a repo-specific operating manual than a one-off prompt.

The best agents.md files are concrete. They tell Claude what commands to run, what commands to avoid, where key directories live, how to validate changes, and what constraints matter most. Good examples include “run pnpm test:unit before suggesting completion,” “never edit files under src/generated/,” “use Zod for schema validation,” or “for database changes, update both migration and type definitions.”

The file is not a replacement for human review, CI, or explicit task prompts. It complements them. You still ask Claude to perform a task, but agents.md reduces repeated setup and helps the model avoid obvious repo-specific mistakes. That is especially helpful in larger projects where a generic coding assistant will otherwise make wrong assumptions.

1. Create the file in your repo

   Add AGENTS.md or agents.md at the repository root, then write clear project rules in plain Markdown with short sections and explicit commands.

2. Document the rules Claude should follow

   Include stack details, test commands, formatting rules, directories to avoid, review expectations, and anything a new teammate would need on day one.

3. Open Claude Code in that repository

   When Claude Code works in the repo, it can read the file and use those instructions as part of its working context for planning and edits.

4. Give a task with a specific goal

   Example: Fix the failing auth tests without changing the public API. Follow AGENTS.md and explain any trade-offs.

5. Review the result against your real checks

   Claude can follow guidance, but you still validate with tests, linting, CI, and code review before merging.

A useful pattern is to keep agents.md stable and task prompts narrow. Put enduring rules in the file. Put the immediate job in your prompt. That split keeps the repo guidance reusable and avoids bloated prompts that mix permanent conventions with temporary requests. If you want a broader view of Claude’s built-in capabilities, see our guide to Claude features.

What you’d actually do with it

The easiest way to understand agents.md is to look at real tasks. The file is most helpful when the repository has non-obvious rules that a general coding model would not guess on its own.

1. Keep Claude from editing generated files

Say your repo contains generated API clients, ORM types, or build artifacts. Without guidance, Claude may edit those files directly because they are visible and convenient. In agents.md, you can state:

# File boundaries
- Never edit anything under src/generated/
- If an API type must change, modify the schema or generator input instead
- After schema changes, run: pnpm generate

Then your task prompt can stay short:

Update the user profile endpoint to include timezone support. Follow AGENTS.md and avoid direct edits to generated files.

This cuts down on one of the most common AI coding mistakes: changing the symptom file instead of the source-of-truth file.

2. Standardise test and lint workflow

Many repos have project-specific validation steps. One app uses pnpm lint, another uses nx affected:test, another needs a Docker service before integration tests run. Agents.md is a good place to make that explicit:

# Validation
- For frontend changes, run: pnpm test:web
- For backend changes, run: pnpm test:api
- Always run: pnpm lint
- Do not claim a task is complete unless the relevant command output is shown

That helps Claude structure its work and reduces vague “done” responses that skip real verification.

3. Enforce architecture decisions

Suppose your team has a hard rule that data access goes through service layers, not directly from route handlers. Put that in agents.md:

# Architecture
- Route handlers should not query the database directly
- Use services under src/services/
- Shared validation lives in src/lib/validation/
- Prefer extending existing services over adding duplicate helpers

Now Claude has a better chance of producing changes that match the real project shape instead of assembling generic framework code.

4. Speed up onboarding in an unfamiliar repo

Agents.md is also useful when you are new to a repository. It acts like a compressed maintainer note. If the file explains where core modules live, how to run the app, and which directories are safe to change, Claude can use that context to answer better questions such as:

Read AGENTS.md, then explain how authentication is wired in this repo and where I should add a new OAuth provider.

That is often more efficient than asking Claude to infer architecture from scratch.

5. Make repetitive maintenance cheaper in time, not just tokens

Even when you are not paying API rates directly, a persistent instruction file can still lower cost in a practical sense: fewer restatements, fewer wrong edits, fewer review cycles. For teams using Claude programmatically, clearer context can also reduce prompt bloat. Official Claude pricing depends on plan and API usage, with web access starting at $0/month on Free, Pro at $20/month or $17/month annual, Max from $100/month, and API model pricing varying by model. Anthropic also lists prompt caching at 90% off cached input tokens and Batch API at 50% off input and output token rates.

Vs. the alternatives

Agents.md is one way to give a coding assistant durable project context. It is not the only way. Competing tools often use workspace rules, IDE instructions, memory features, or repository docs. The real question is not “which one is smartest?” but “which one makes the fewest wrong assumptions in your workflow?”

Approach	What it is good at	Main limitation	Best fit
AGENTS.md with Claude Code	Repo-specific rules in plain text, easy to version with the codebase	Only helps if the file is maintained and specific	Teams that want persistent, reviewable instructions
Repeated prompt boilerplate	Fast for one-off tasks	Easy to forget details; inconsistent across sessions	Short experiments and throwaway repos
General repo docs like README or CONTRIBUTING	Useful for humans and AI together	Often too broad, outdated, or not task-oriented	Shared baseline documentation
IDE-specific rules in tools like Cursor, GitHub Copilot, or Cody	Tight editor integration and per-workspace guidance	Can be tool-specific and less portable across environments	Teams committed to one editor workflow

Compared with Cursor-style project rules, agents.md has a straightforward advantage: it is just a file in the repository, so it is visible, versioned, and easy to review in pull requests. Compared with a generic README, it can be narrower and more operational, focused on what Claude should do when changing code. Compared with GitHub Copilot or Cody workspace instructions, the trade-off is usually ecosystem preference and tool integration rather than a single winner.

The honest trade-off is maintenance. Any persistent instruction layer gets stale if nobody owns it. If your architecture changes and agents.md still points Claude toward old commands or obsolete directories, the file becomes friction instead of help.

Other questions readers ask

The honest take

For most teams using Claude Code seriously, agents.md is worth having. It is a simple way to move repeat instructions out of chat and into the repository, where they can be reviewed, versioned, and improved. The payoff is not that Claude suddenly becomes flawless. The payoff is fewer avoidable mistakes and less prompt repetition.

If your project is small, temporary, or loosely structured, you may not need it yet. But if your repo has strong conventions, generated files, non-obvious test commands, or architecture rules that matter, agents.md is one of the lowest-effort ways to make Claude Code more useful. For the product itself, use the official Claude site. For broader product context, you can also start with our Claude Code overview.

Independent guide. Not affiliated with Anthropic. For the official Claude product, visit claude.ai.

Last updated: 2026-05-12