AGENTS.md and Shared Instructions: The Config Layer Your AI Coding Agents Need

Your team has five developers using AI coding agents. One prefers terse commit messages, another writes novels. One tells Claude to use functional patterns everywhere, another relies on class hierarchies. The codebase starts to look like it was written by five different companies, because in a sense, it was.

This is the problem that repository-level instruction files solve. Files like AGENTS.md, CLAUDE.md, and .cursorrules give every agent that touches your repo the same set of ground rules. And the ThoughtWorks Technology Radar now treats this as settled practice: "curated shared instructions for software teams" sits in the Adopt ring as of Vol 34 (April 2026), their highest confidence level.

What AGENTS.md Actually Is

AGENTS.md is a Markdown file you place in your repository root (or in subdirectories for scoped rules) that provides instructions to AI coding agents. Think of it as a README, but the audience is an LLM instead of a human. There's no rigid schema. No required fields. It's just Markdown, and that's the point: LLM-based agents are remarkably good at interpreting free-form, human-readable guidance.

The ThoughtWorks Radar first featured AGENTS.md in Vol 33 (November 2025) at the Trial level. Their description captures it well: "Essentially a README file for agents, it has no required fields or formatting other than Markdown, relying on the ability of LLM-based coding agents to interpret human-written, human-readable guidance."

Typical content in an AGENTS.md file includes:

• Build and test commands — how to compile the project, run the test suite, which linters to execute before committing
• Code style rules — naming conventions, import ordering, preferred patterns
• Architecture constraints — which layers can import what, where business logic lives, what's off-limits
• Forbidden patterns — things the agent should never do (inline imports, force pushes, certain dependencies)
• Git workflow rules — commit message format, branching strategy, how to handle merge conflicts

How Different Tools Consume These Files

Every major AI coding tool now supports some form of repository-level instruction file, but the naming and resolution rules differ.

Claude Code reads CLAUDE.md from the project root and loads it into the system prompt automatically. It also supports AGENTS.md as a convention. Claude Code has a three-tier hierarchy: a user-level config (~/.claude/CLAUDE.md), a project-level file, and directory-scoped files that can add rules for specific packages or modules.

GitHub Copilot uses .github/copilot-instructions.md for repository-level instructions that apply to all Copilot chat interactions. It also picks up AGENTS.md files. Copilot Coding Agent reads these files when working on issues and pull requests in agent mode.

Cursor looks for .cursorrules (or .cursor/rules in newer versions) at the project root. These act as persistent system-level instructions for every interaction within that workspace.

OpenAI Codex reads AGENTS.md as well as its own codex.md file. It follows the same pattern: a markdown file at the repo root, loaded into the agent's context at the start of each session.

The fragmentation is annoying but manageable. Some teams maintain an AGENTS.md as the canonical source and symlink or copy to tool-specific files. Others just pick the file for whichever tool the team standardizes on. The content matters more than the filename.

Repo Context vs. IDE Commands: Two Different Layers

There's a distinction worth drawing between these instruction files and IDE-level custom commands or slash commands. They solve different problems.

An AGENTS.md file is repo context. It's always-on background knowledge that shapes every interaction an agent has with your codebase. It answers "how do we do things here?" Custom commands and slash commands are workflow shortcuts. They're task-specific prompts that a developer triggers on demand. Claude Code's /review command, for instance, might run a structured code review with specific criteria. Cursor's custom prompts can automate refactoring workflows.

Both are shareable. Both should be version-controlled. But the instruction file is passive context; commands are active workflows. The ThoughtWorks Radar groups both under "curated shared instructions" because the underlying principle is identical: treat AI guidance as a team-owned engineering artifact, not an individual's personal prompt library.

Why ThoughtWorks Says Adopt

The Radar's progression tells the story. In Vol 33 (November 2025), AGENTS.md was placed at Trial. Six months later in Vol 34 (April 2026), the broader practice of curated shared instructions sits at Adopt, and AGENTS.md is folded in as a related blip.

ThoughtWorks' reasoning is direct: "Relying on individual developers to write prompts from scratch is emerging as an anti-pattern." Their recommendation is to anchor instruction files into service templates so new repositories inherit the latest agent workflows and rules by default.

They also describe a related practice worth noting: anchoring coding agents to a reference application. A live, compilable codebase serves as the source of truth. As architecture and coding standards evolve, the reference app and its embedded instructions update together. New repos inherit the latest guidance by default. It's version control for your AI conventions, applied at the organizational level.

The confidence is earned. When every developer on a team uses the same shared instructions, the agent output converges toward consistent patterns. Code reviews get faster because the AI isn't fighting your conventions. Onboarding new team members gets simpler because the agent already knows the local rules.

Practical Patterns That Work

After looking at dozens of real-world instruction files (including the one in our own monorepo), a few patterns consistently produce better results.

Start with commands, not philosophy

The most effective instruction files open with concrete commands: how to build, how to test, how to lint. Agents need to run these constantly, and if they have to guess or search for the right incantation, you'll spend tokens on failed build attempts. Put npm run check at the top, not at the bottom after three paragraphs of project history.

Be explicit about forbidden patterns

Positive guidance is good. Negative constraints are better. Agents have strong priors from training data, and sometimes those priors are wrong for your project. If your codebase uses a specific import style, say so. If git add -A is dangerous in your parallel-agent setup because it can sweep up other agents' changes, state that explicitly.

Scope rules to directories

Monorepos benefit from layered instruction files. A root-level file covers global conventions (commit format, CI commands). Package-level files add specific rules: the packages/ai/ directory might mandate streaming response patterns, while packages/tui/ requires specific rendering conventions. Claude Code supports this natively with directory-scoped files.

Encode testing mandates

One of the highest-value rules you can add: "After code changes, run npm run check. Fix all errors before committing." This turns the agent's own CI into a feedback loop. The ThoughtWorks Radar calls these "feedback sensors for coding agents" and lists them at Trial. The instruction file is where you wire them in.

Include architecture decision context

Don't just say "use TypeScript." Say "we use TypeScript with strict mode, no any types unless absolutely necessary. Check node_modules for external API type definitions instead of guessing." The more specific your constraints, the less the agent fills in gaps with generic patterns.

The Connection to Context Engineering

Instruction files are one piece of a larger discipline the Radar now calls context engineering, which also moved to Adopt in Vol 34. Where context engineering is the broad architectural concern of managing everything an AI agent sees, instruction files are the simplest, most concrete implementation.

They're the static layer. You write them once, refine them over time, and they provide a consistent baseline. More dynamic approaches build on top: progressive context disclosure loads detailed instructions only when the agent needs them for a specific task. Agent Skills package modular instructions with executable scripts. But the instruction file at the repo root remains the foundation everything else builds on.

The Radar describes the feedback flywheel as a complementary practice: teams capture what went well and what failed during agent sessions, then fold those lessons back into their shared instructions. Over time, the instruction file becomes a living document that encodes your team's accumulated experience with AI-assisted development.

Anti-Patterns: How Instruction Files Go Wrong

The same Radar that advocates for shared instructions also puts "agent instruction bloat" in the Caution ring. These two blips aren't contradictory. They're two sides of the same practice: do this, but do it carefully.

The file that never stops growing

ThoughtWorks warns that context files "tend to accumulate over time as teams add codebase overviews, architectural explanations, conventions and rules." Each addition feels useful in isolation. But LLMs attend less to content buried in the middle of long contexts, so instructions deep in a bloated file get missed. The research they cite suggests hand-written instruction files consistently outperform LLM-generated ones. Don't use Claude to write your CLAUDE.md.

Instructions that contradict each other

When multiple people contribute to the instruction file without coordination, you get contradictions. One section says "prefer functional patterns," another says "use class-based services." The agent will pick one, and you won't know which until you see the output. Treat the file like you'd treat a style guide: one owner, periodic reviews, explicit resolution of conflicts.

Vague guidance that doesn't constrain anything

"Write clean code" is not an instruction. "Follow SOLID principles" barely narrows the output space. Effective instructions are specific enough that you could verify compliance mechanically: "No any types." "Run npm run check after changes." "Never use git add -A." If you can't imagine what violating the rule looks like, the rule isn't doing anything.

Duplicating what the linter already enforces

If your ESLint config already bans console.log, you don't need the instruction file to repeat that. The instruction file's job is to encode things that tools can't express: architectural intent, workflow conventions, and the why behind decisions. Let linters and type checkers handle the mechanical stuff.

A Minimal Starting Template

If you don't have an instruction file yet, here's a structure to start from. Resist the urge to make it comprehensive on day one. Start minimal, add rules when you observe the agent making mistakes, and prune rules that aren't pulling their weight.

# AGENTS.md

## Commands
- Build: `npm run build`
- Test: `npm run test`
- Lint + typecheck: `npm run check`
- After code changes: run `npm run check` and fix all errors before committing

## Code Style
- TypeScript strict mode, no `any` types
- Use top-level imports only — no dynamic imports for types
- Prefer named exports

## Architecture
- Business logic lives in `src/core/`, never in route handlers
- Database queries go through the repository layer
- No circular dependencies between packages

## Git
- Commit messages: `type(scope): description` (e.g., `fix(auth): handle expired tokens`)
- Only stage files you modified — never `git add -A`
- Always rebase on main before merging

## Forbidden
- No `git reset --hard` or `git checkout .` (destroys other agents' work)
- No inline `await import()` calls
- Never remove functionality to fix type errors — fix the types instead

That's roughly 30 lines. You can read it in under a minute. An LLM can internalize it completely without any important rules falling out of the attention window.

Making It Stick

Writing the file is the easy part. Keeping it useful over months requires a few habits.

Review it like code. Changes to the instruction file should go through pull requests. If someone adds a new rule, the team should see it and agree.

Prune quarterly. Set a calendar reminder to read through the file and ask: is this rule still relevant? Is the agent actually following it? Has a linter rule made it redundant? Remove anything that's dead weight.

Add rules reactively. When an agent makes a mistake that a rule would have prevented, that's when you add the rule. Don't try to anticipate every possible failure mode upfront. The feedback flywheel approach works well here: observe, learn, encode.

Distribute via templates. If your organization scaffolds new services from a template repo, put the instruction file in the template. This is exactly the pattern ThoughtWorks describes: "the template becomes a powerful distribution mechanism for AI guidance." New projects get your accumulated best practices from day one.

If your team's CI runs on Tenki runners with faster builds, that's especially relevant for instructions that tell agents to run checks before committing. Shorter feedback loops mean agents spend less time waiting and more time iterating on fixes.

The bar for getting started is low. Create an AGENTS.md with your build commands and three rules you wish your agents already followed. Commit it. See what changes. You can refine from there.