lockstep
3 min readNaman Jain

AGENTS.md vs README.md: what goes where

AGENTS.md vs README.md: README is for people, AGENTS.md is for coding agents. What belongs in each, an example split, and how CLAUDE.md fits in.

A repository's README has grown to 600 lines: the project pitch, a quick start, contribution rules, and then 300 lines of "when modifying the payments module, always run…" written for coding agents. New contributors scroll past the agent rules; agents read the pitch and the badges. Nobody is well served.

The fix is two files with two audiences. This guide uses the agents.md project's description of the format, checked on 16 November 2026.

The short answer

README.mdAGENTS.md
ReaderPeopleCoding agents
ContainsWhat it is, quick start, contributing, licenseExact setup and test commands, code style, conventions, boundaries
ToneExplanatoryLiteral and specific
LengthConciseAs detailed as agents need
Read byGitHub, new contributors, usersCodex, Cursor, Gemini CLI, Copilot's agents, and many more

The agents.md project describes AGENTS.md as a README for agents: a dedicated, predictable place for the context and instructions coding agents need.

Why keep them separate

From the agents.md site, the format was kept separate to:

  • Give agents a clear, predictable place for instructions
  • Keep READMEs concise and focused on human contributors
  • Provide precise, agent-focused guidance that complements the README and docs

There's also a reading difference. People skim and infer. Agents act on exactly what's written, so they need commands and rules spelled out that a human contributor would find obvious.

An example split

README.md

# Acme Billing

Usage-based billing for SaaS products.

## Quick start
pnpm install && pnpm dev, then open localhost:3000.

## Contributing
See CONTRIBUTING.md. Open an issue before large changes.

AGENTS.md

# AGENTS.md

## Setup
- Install deps: `pnpm install`
- Run tests: `pnpm test`; run `pnpm test -- billing` after billing changes

## Code style
- TypeScript strict mode
- Money is integer cents; never floats

## Boundaries
- Don't edit files under `generated/`
- New migrations must be backward compatible

Where CLAUDE.md fits

Claude Code reads CLAUDE.md. To avoid two copies of the same rules, keep shared instructions in AGENTS.md and put @AGENTS.md in CLAUDE.md to import it, with any Claude-specific notes below. See AGENTS.md examples and CLAUDE.md vs CLAUDE.local.md vs auto memory.

Tips

  • Commands, not descriptions. "Run pnpm test -- billing" beats "make sure billing tests pass."
  • Nest when it helps. Many agents read the nearest AGENTS.md in the directory tree, so a monorepo can have one per package.
  • Link, don't copy. Point to the README or docs for background instead of duplicating it.
  • Review it like code. It changes how every agent behaves.

What neither file holds well

Both files describe how the project works. Neither is a good place for decisions that change and have an owner, such as "billing v1 API frozen until March." A line in AGENTS.md has no owner, no approval, and no record of when it stops being true.

Where Lockstep fits

Lockstep keeps those decisions separate. It captures them from PRDs, Slack, and pull requests, routes each to its owner for approval, and briefs Claude Code sessions on the ones that apply. Briefings are a Claude Code feature; other agents that speak MCP can query the decisions through Lockstep's tools.

See how it works.

Sources checked 16 November 2026

For what AGENTS.md is and isn't, see AGENTS.md. For GitHub Copilot's files, see AGENTS.md vs copilot-instructions.md.

Frequently asked questions

What is the difference between AGENTS.md and README.md?
The agents.md project describes README files as for humans: quick starts, project descriptions, and contribution guidelines. AGENTS.md holds the extra, sometimes detailed context coding agents need, such as build steps, tests, and conventions that would clutter a README or don't matter to human contributors.
Why not just put agent instructions in the README?
The agents.md project kept them separate to give agents a clear, predictable place for instructions and to keep READMEs concise and focused on human contributors. Agents also read instructions literally, so they benefit from exact commands that would be noise for most human readers.
Which tools read AGENTS.md?
The agents.md site lists many, including Codex, Jules and Gemini CLI from Google, Cursor, Zed, Warp, VS Code, Devin, Junie, Amp, Aider, goose, and opencode. Claude Code reads CLAUDE.md and can import AGENTS.md.
How does CLAUDE.md relate to AGENTS.md and README.md?
CLAUDE.md is Claude Code's instruction file. To avoid duplicating AGENTS.md, keep shared instructions in AGENTS.md and import it into CLAUDE.md with @AGENTS.md, adding Claude-specific notes below. The README stays for people.
Should AGENTS.md link to the README?
It can point to the README or docs for background, but keep AGENTS.md self-contained for the commands and rules an agent must follow. Agents act on what's in front of them.

Keep reading