AGENTS.md and CLAUDE.md: shared instructions for AI coding agents

When every developer on a team prompts their coding agent differently, the agents write code differently. One gets told to use functional patterns while another is told to use classes, and one agent's commit messages are terse while another's run to paragraphs. A repository instruction file fixes that by giving every agent that works in the repo the same ground rules, from a file the whole team reviews.

ThoughtWorks put this practice, which they call curated shared instructions for software teams, in the Adopt ring of Technology Radar Vol 34 (April 2026). This guide covers how the major tools find these files, what belongs in one, and the mistakes that make them stop working.

What AGENTS.md is

AGENTS.md is a Markdown file at the root of your repository, and optionally in subdirectories, that tells AI coding agents how to work in that codebase. It has no schema and no required fields. You write instructions in plain language and the agent reads them into its context at the start of a session.

Most files cover the same ground:

• the commands to install, build, test and lint, and what to run before committing
• code style, such as naming, import conventions and preferred patterns
• architecture rules, like which layers may import which and where business logic lives
• forbidden actions the agent should never take in this repo
• the Git workflow, including commit message format, branching and what not to commit

CLAUDE.md, .github/copilot-instructions.md and Cursor's rule files do the same job under different names.

How each tool finds its instructions

The tools have converged on AGENTS.md, but each one resolves files a little differently.

The precedence rules pull in opposite directions: Claude Code prefers CLAUDE.md, Tenki's reviewer prefers AGENTS.md, and Codex reads only AGENTS.md. If you keep two files with different content, your agents follow different rules depending on which tool is running.

Keep one file for every tool

Make AGENTS.md the canonical file. If anyone on the team uses Claude Code, add a CLAUDE.md next to it that imports it:

@AGENTS.md

## Claude Code

- Use plan mode for changes that touch more than one package.

Claude Code expands the @AGENTS.md import and reads the Claude-specific lines after it. Every other tool reads AGENTS.md directly. A symlink (ln -s AGENTS.md CLAUDE.md) also works, but Git checks symlinks out as plain text files on Windows unless core.symlinks is enabled, so the import is safer on mixed teams.

If you have no Claude-specific rules and everyone runs Claude Code v2.1.277 or later, you can skip CLAUDE.md entirely. Watch for a CLAUDE.md or CLAUDE.local.md higher up the tree, though: either one stops Claude Code from reading AGENTS.md.

Instructions versus commands

Instruction files and slash commands (or skills) solve different problems. AGENTS.md is always-on context: it answers "how do we do things here?" for every task. A command is a prompt a developer triggers on demand for one workflow, like "draft a migration" or "write release notes".

Both belong in version control. The difference matters for size: anything only needed for one workflow should live in a command or skill that loads when it's used, not in the file every session reads.

What to put in the file

Commands first

Put build, test and lint commands at the top. The agent runs them constantly, and if it has to guess, it burns time on failed attempts. Give the exact command with its flags; that helps the agent more than a paragraph of project history.

Forbidden actions, stated plainly

Agents have strong defaults from training data, and some of them are wrong for your repo. Say what not to do: "Don't edit files in src/generated/; change the schema and run pnpm codegen." "Don't commit .env* files." "Never force-push to main."

Scoped files in a monorepo

A root file covers what's true everywhere: commit format, CI commands, repo-wide bans. A package-level file adds what's specific to that package, for example "components in packages/ui must not import from apps/*" or "handlers in services/api return errors through AppError".

Tools combine these differently. Codex concatenates root to leaf, Copilot prefers the nearest file, and Claude Code loads a subdirectory's file when it opens files there. Write package files as additions to the root file, never as contradictions of it, and the result is the same whichever tool reads them.

A check to run after every change

"After changing code, run pnpm lint && pnpm typecheck and the affected tests, and fix failures before committing." With that rule in the file, the agent runs your existing checks against its own changes and fixes what they catch.

Decisions, not slogans

"Use TypeScript" says little. "TypeScript strict mode; no any, use unknown and narrow it" is something the agent can follow and a reviewer can check.

Anti-patterns

The same Radar volume that moved shared instructions to Adopt put agent instruction bloat in the Caution ring. Most of the ways these files fail are versions of that.

The file that never stops growing

Each addition feels useful on its own: a codebase overview, an architecture explainer, another convention. Past a certain length, rules get missed. Claude Code's docs recommend keeping each CLAUDE.md under 200 lines, and Codex stops reading at 32 KiB by default.

The overviews are usually the first thing to cut. A February 2026 study from ETH Zurich found that agents followed the instructions in context files well, but that repository overviews didn't help, and that context files overall raised inference cost by more than 20% without generally improving task success. The authors conclude context files are most useful for non-standard practices, which is a good test for any line you're about to add.

Rules that contradict each other

When several people add rules without coordinating, you get "prefer functional patterns" in one section and "use class-based services" in another. The agent picks one, and you find out which from the output. Give the file an owner and resolve conflicts when you spot them.

Guidance too vague to check

"Write clean code" and "follow SOLID principles" don't narrow anything. A good rule is specific enough that you can tell when it was broken: "No any types." "Run the typecheck before committing." If you can't picture what a violation would look like, the rule probably isn't changing what the agent does.

Repeating the linter

If ESLint already bans console.log, the instruction file doesn't need to say so. Use the file for what tools can't enforce: architectural intent, workflow conventions, and the reasons behind decisions.

A starter template

The template below is deliberately small. Add a rule when you see an agent make a mistake the rule would have prevented, and remove rules that aren't earning their place.

# AGENTS.md

## Commands

- Install: `pnpm install`
- Build: `pnpm build`
- Test: `pnpm test` (one package: `pnpm --filter <name> test`)
- Lint and typecheck: `pnpm lint && pnpm typecheck`
- After changing code, run lint, typecheck and the affected tests. Fix failures before committing.

## Code style

- TypeScript strict mode. No `any`; use `unknown` and narrow it.
- Named exports only.
- API errors go through `AppError` in `src/lib/errors.ts`.

## Architecture

- Business logic lives in `src/domain/`. Route handlers parse input, call the domain, and format the response.
- Only `src/db/` imports the database client.

## Git

- Conventional Commits: `type(scope): summary`, e.g. `fix(auth): refresh expired tokens`.
- Keep each commit to the task at hand. Never commit `.env*` files.
- Never force-push to `main`.

## Don't

- Don't edit `src/generated/`; change the schema and run `pnpm codegen`.
- Don't add a dependency without explaining why in the PR description.
- Don't delete or skip a failing test to get CI green.

## Review

- Flag handlers in `src/api/` that read user data without an authorization check.
- Ignore `src/generated/**` and lockfiles.

That's about 35 lines: short enough to read in a minute and to review properly in a pull request.

Keeping it useful

Review changes to the file the way you review code. When edits go through pull requests, the team sees new rules before agents start following them.

Every few months, read the file and ask of each rule whether it's still true, whether the agent is following it, and whether a linter has made it redundant.

You don't have to predict every failure up front. When an agent makes a mistake a rule would have prevented, write that rule then.

If new services start from a template repository, put the instruction file in the template so every new repo starts with the current rules. The Radar entry calls the template "a powerful distribution mechanism for AI guidance".

Use the same file for code review

The agent that reviews a pull request needs the same rules as the agent that wrote it. Tenki Code Reviewer reads your repository's AGENTS.md or CLAUDE.md and applies it to every review, on top of its standard bug, security and quality checks. There's nothing to configure: commit the file and the next review uses it. In a monorepo, it also picks up the files in the directories above each file it reviews, so package-level rules apply where they belong.

When both files exist, the reviewer uses AGENTS.md and ignores CLAUDE.md. That's one more reason to make AGENTS.md the canonical file and have CLAUDE.md import it. A "Review" section like the one in the template gives the reviewer focus areas and paths to skip. See Custom context for more examples, and the pricing page for costs: each review is $1.00 from workspace credits.