How to set up AGENTS.md for multi-agent development workflows

Every AI coding tool reads some kind of project configuration file. Claude Code reads CLAUDE.md. Cursor reads .cursorrules. Windsurf reads .windsurfrules. And now, with OpenAI's Codex and the broader move toward multi-agent development, AGENTS.md is emerging as the tool-agnostic standard.

The idea behind all these files is the same: give the AI enough context about your project that it produces code matching your actual patterns, conventions, and constraints from the first attempt. The difference is that AGENTS.md is not tied to any single tool, which makes it increasingly relevant as teams use multiple AI coding assistants simultaneously.

Why AGENTS.md exists

The problem is simple. AI coding tools are good at writing code, but they have no way to know your specific conventions unless you tell them. Without configuration, they default to generic patterns that may not match your codebase at all.

Consider what happens when you ask an AI agent to add a new API endpoint to your project. Without context, it guesses your framework, your error handling approach, your naming conventions, your test structure, and your authentication pattern. It might guess correctly on some of these. It will almost certainly get others wrong.

With a well-written configuration file, the agent knows all of these details before it starts. The code it produces matches your existing patterns on the first try.

AGENTS.md is the tool-agnostic version of this configuration. It works with any AI tool that supports reading markdown-based project context, and more tools are adding support as multi-agent workflows become standard practice.

What goes in an AGENTS.md

An effective AGENTS.md covers five categories. You do not need to fill every section for every project, but addressing each one prevents common failure modes.

1. Project overview

Start with what the project is, what it does, and how it is structured at a high level. This gives the agent the mental model it needs to make good decisions about where code belongs and how components interact.

# Project Overview

This is a SaaS application for inventory management.
Backend: FastAPI (Python 3.12), PostgreSQL, Redis for caching.
Frontend: Next.js 15 with TypeScript, Tailwind CSS.
Monorepo managed with Turborepo.

## Directory Structure
- /apps/api — FastAPI backend
- /apps/web — Next.js frontend
- /packages/shared — Shared TypeScript types and utilities
- /packages/db — Drizzle ORM schema and migrations

2. Coding conventions

This is where you prevent the agent from writing code that technically works but does not match your style. Be specific about patterns you use and patterns you avoid.

## Coding Conventions

### Python (Backend)
- Use Pydantic v2 models for all request/response schemas
- Dependency injection via FastAPI's Depends()
- No raw SQL — use SQLAlchemy ORM exclusively
- Type hints on all function signatures
- Docstrings only on public API endpoints

### TypeScript (Frontend)
- Functional components only, no class components
- Use server components by default, client components only when interactivity is needed
- Zustand for client state, React Query for server state
- No barrel exports (index.ts re-exports)
- Prefer named exports over default exports

3. Testing requirements

Tell the agent what tests look like in your project, what commands to run, and what standards to follow. This prevents agents from generating tests that use the wrong framework or follow patterns that conflict with your existing test suite.

## Testing

### Backend tests
- Framework: pytest with pytest-asyncio
- Run: `cd apps/api && pytest`
- Test files mirror source structure: src/routes/users.py → tests/routes/test_users.py
- Use factory_boy for test data, not raw fixtures
- Database tests use a dedicated test database (TEST_DATABASE_URL in .env.test)

### Frontend tests
- Framework: Vitest + Testing Library
- Run: `cd apps/web && npm test`
- Test user behavior, not implementation details
- Mock API calls with MSW, never mock fetch directly

4. Guardrails and constraints

This section prevents the agent from making changes that are technically valid but operationally dangerous. Think of it as the "do not" list.

## Guardrails

- Never modify migration files after they have been applied
- Never delete database columns — add a deprecated flag instead
- Do not add new npm dependencies without checking the bundle size impact
- Never bypass TypeScript strict mode with @ts-ignore
- Do not modify the auth middleware without explicit approval
- Always use parameterized queries — no string concatenation in SQL
- Rate limiting is required on all public API endpoints

5. Architecture decisions

Document the non-obvious decisions that shaped your codebase. Without this context, agents will suggest alternative approaches that conflict with intentional design choices.

## Architecture Decisions

- We use a CQRS-lite pattern: separate read and write models for performance-critical paths
- Background jobs run via a task queue (Celery + Redis), not cron jobs
- File uploads go to S3 via presigned URLs — the backend never handles file bytes
- WebSocket connections are managed by a separate service (/apps/ws), not the main API
- We chose Drizzle over Prisma because we need raw SQL escape hatches for complex reporting queries

AGENTS.md vs CLAUDE.md: what to use when

If your entire team uses Claude Code, a CLAUDE.md file is all you need. Claude Code reads it automatically at session start, and you get the full benefit of project-specific configuration.

If your team uses different tools — some on Claude Code, others on Cursor or Codex — maintaining tool-specific files becomes tedious and error-prone. AGENTS.md solves this by providing a single source of truth that multiple tools can read.

The practical approach many teams use:

1. Write your primary configuration in AGENTS.md
2. Create a minimal CLAUDE.md that imports or references it: Read and follow the conventions in AGENTS.md.
3. Do the same for .cursorrules or other tool-specific files

This way you maintain one canonical document and each tool picks it up through its own mechanism.

Layered configuration for monorepos

Monorepos need a layered approach. A single root-level file cannot cover the conventions of a Python backend, a TypeScript frontend, and a Go microservice simultaneously without becoming unwieldy.

The pattern that works:

my-project/
  AGENTS.md              # Shared: git workflow, CI, code review standards
  apps/
    api/
      AGENTS.md          # Python-specific: FastAPI patterns, pytest config
    web/
      AGENTS.md          # TypeScript-specific: React patterns, Vitest config
    mobile/
      AGENTS.md          # React Native-specific patterns
  packages/
    shared/
      AGENTS.md          # Shared package conventions

Root-level configuration covers what applies everywhere: git commit conventions, PR review requirements, CI pipeline details, security baseline. Service-level files cover framework-specific conventions, local testing commands, and service-specific architecture decisions.

Most AI coding tools merge these layers automatically. When an agent works in apps/api/, it reads both the root AGENTS.md and the local one, with local rules taking precedence where they conflict.

Common mistakes in AGENTS.md files

Too vague

Statements like "write clean code" or "follow best practices" add no value. The agent already tries to write clean code. What it needs is specific guidance about your definition of clean: your naming conventions, your error handling approach, your file organization rules.

Too long

A 5,000-word configuration file costs tokens on every interaction and buries important rules in noise. Focus on conventions that the agent would get wrong without guidance. If a rule matches what any competent developer would do by default, skip it.

Outdated

Configuration files that reference deprecated libraries, old directory structures, or abandoned patterns cause more harm than having no configuration at all. The agent follows the instructions faithfully, producing code that matches an old version of your project.

Treat AGENTS.md like code. Review it when you make architectural changes. Update it when conventions evolve. Delete rules that no longer apply.

Missing the hard-won knowledge

The most valuable content in a configuration file is the stuff that is not obvious from reading the code. Why you chose this ORM over that one. Why authentication works this unusual way. Why you never use library X even though it seems like the obvious choice. This context prevents agents from "improving" things back to generic patterns that you intentionally moved away from.

Scoring your configuration

Whether you use AGENTS.md, CLAUDE.md, or both, the effectiveness of your configuration depends on coverage. Missing categories mean the agent guesses in those areas, and guesses are inconsistent.

ContextKit Analyze scores your configuration file across five categories: structure, architecture, conventions, testing, and guardrails. It identifies specific gaps and suggests concrete improvements. The analysis runs entirely in your browser — your configuration never leaves your machine.

If you are starting a new project and want a solid baseline, ContextKit Generate creates a complete configuration from your project description in about a minute. It produces output in CLAUDE.md format, but the content works equally well as an AGENTS.md since the structure and purpose are identical.

What comes next

The trend is clear: AI coding agents are becoming a standard part of development workflows, and teams increasingly use more than one. A shared configuration format eliminates the overhead of maintaining separate files for each tool.

AGENTS.md is not yet an official standard, but it is the closest thing to one as of 2026. OpenAI's Codex supports it, and Claude Code can be instructed to read it. The content structure (project overview, conventions, testing, guardrails, architecture decisions) is universal regardless of which file name you use.

The practical advice: start with whichever file your primary tool reads, write it well, and extend to a shared format when your team needs cross-tool consistency. The content matters more than the filename. A thorough CLAUDE.md will serve you better than a superficial AGENTS.md every time.