# Writing Effective AGENTS.md

> The single most impactful file for AI coding agent productivity. A well-written AGENTS.md turns any agent from "confused newcomer" to "productive team member" in one read.

## When to Use

- Starting a new repo
- Onboarding a new AI tool (Claude Code, Cursor, Windsurf, etc.)
- When agents keep making the same mistakes
- When context is lost between sessions

## The Pattern

AGENTS.md is a **universal** agent onboarding document that lives at the repo root. Every major AI coding tool reads it automatically or can be pointed to it:

- **Claude Code** — reads AGENTS.md + CLAUDE.md automatically
- **Cursor** — reads .cursorrules automatically
- **Windsurf** — reads .windsurfrules automatically
- **GitHub Copilot** — reads .github/copilot-instructions.md
- **Codex / Aider / Cline** — can be pointed to AGENTS.md

AGENTS.md is the **canonical source**; all other files are derived from it.

## Structure Template

```markdown
# AGENTS.md — AI Coding Agent Instructions

> **For:** Claude Code, Cursor, Copilot, Windsurf, Aider, Codex
> **Repo:** <repo-name> — <one-line description>

## 1. Project Identity

| Key                 | Value                                  |
| ------------------- | -------------------------------------- |
| **Product**         | <Name>                                 |
| **Stack**           | <e.g., Next.js 16, Fastify 5, SwiftUI> |
| **Package manager** | <npm/pnpm/yarn/pip>                    |
| **Test runner**     | <Vitest/pytest/XCTest>                 |

## 2. Repo Layout

(ASCII tree of key directories — NOT exhaustive, just the important ones)

## 3. Tech Stack Rules

(Framework-specific conventions: ESM, module resolution, etc.)

## 4. Coding Conventions

### MUST follow

- <Rule 1>
- <Rule 2>

### MUST NOT do

- <Anti-pattern 1>
- <Anti-pattern 2>

## 5. File Ownership Map

| Domain | Files             |
| ------ | ----------------- |
| Auth   | src/modules/auth/ |
| ...    | ...               |

## 6. Build & Test Commands

(Copy-pasteable commands the agent can run)

## 7. Common Patterns

(Code templates for adding new features)

## 8. Common Pitfalls

(Things that break often and how to fix them)
```

## Key Principles

### 1. Be prescriptive, not descriptive

Bad: "We use TypeScript"
Good: "ESM everywhere (`"type": "module"`, `.js` extensions in imports)"

### 2. Include concrete examples

Bad: "Follow the module pattern"
Good: "Each module follows `types.ts` → `repository.ts` → `routes.ts`. See `src/modules/auth/` for reference."

### 3. Include MUST NOT rules

Agents need guardrails. Explicitly list what they should never do:

- "Never use `console.log` — use `req.log` or `app.log`"
- "Never hardcode colors — use theme tokens"
- "Never modify tests to make them pass — fix the actual code"
- "Never delete existing comments unless explicitly asked"

### 4. Include build verification commands

Agents need to verify their work. Give them the exact commands:

```
## Build Verification
- Web: `cd web && npm test && npm run typecheck && npm run build`
- iOS: Open .xcodeproj, Cmd+B
- Backend: `python -m pytest tests/ -v --tb=short`
```

### 5. Include the file ownership map

When an agent needs to work on "auth", it should know exactly which files to touch. A table mapping domains to file paths eliminates guesswork.

### 6. Keep it under 500 lines

Too long and agents will truncate or skip sections. Focus on what causes the most mistakes.

## Anti-Patterns

- **No AGENTS.md at all** — Agent wastes 30% of conversation just understanding the codebase
- **README.md as the only guide** — READMEs are for humans; AGENTS.md is for machines (different structure)
- **Stale AGENTS.md** — Update it when architecture changes. Run `/update-agent-docs` workflow regularly
- **Too generic** — "Follow best practices" helps nobody. Be specific
- **Duplicated across editors** — Maintain AGENTS.md as source, derive .cursorrules etc. from it

## Real-World Example

From a 5-product ecosystem (25+ platform-service modules, 847 tests):

```markdown
## 4. Coding Conventions

### MUST follow

- Every Cosmos document MUST include a `productId` field
- Every REST endpoint MUST validate input with Zod schemas
- Every service MUST propagate `x-request-id` headers
- Use `PRODUCT_ID` from `@bytelyst/config` — never hardcode
- Commit messages: `type(scope): description`

### MUST NOT do

- Never use `console.log` — use `req.log` or `app.log` in Fastify
- Never use `any` type — use Zod inference or explicit types
- Never hardcode secrets or API keys
- Never modify tests to make them pass — fix the actual code
- Never add emojis to code unless explicitly asked
```

This set of rules was developed over 50+ sessions and prevents the most common agent mistakes.

## Editor-Specific Notes

| Editor      | Auto-read file                  | Derivation                                     |
| ----------- | ------------------------------- | ---------------------------------------------- |
| Claude Code | CLAUDE.md                       | Subset of AGENTS.md with Claude-specific notes |
| Cursor      | .cursorrules                    | AGENTS.md condensed to rules format            |
| Windsurf    | .windsurfrules                  | AGENTS.md condensed to rules format            |
| Copilot     | .github/copilot-instructions.md | AGENTS.md adapted for Copilot                  |
| Aider       | .aider.conf.yml                 | Config-only, points to AGENTS.md               |
| Cline       | .clinerules                     | AGENTS.md condensed                            |
| JetBrains   | .editorconfig                   | Formatting rules only                          |

## Related Skills

- [02 — Multi-Editor Config](./02-multi-editor-config.md)
- [04 — Workflow Definitions](./04-workflow-definitions.md)
- [19 — Session Summaries & Playbooks](./19-session-playbooks.md)
