AGENTS.md crossed 60,000 repositories on GitHub in 2026. That scale provides something valuable: a large, diverse dataset of what works and what does not. Projects like n8n (178K stars), awesome-go (167K stars), and LangFlow (145K stars) have refined their AGENTS.md over months of real-world AI agent usage.
This guide distills what those repos have converged on. Not the format basics — you can find those in our AGENTS.md vs CLAUDE.md comparison — but the design principles and operational patterns that separate high-performing AGENTS.md files from ones that sit in repos and accumulate stale information.
The Core Design Question
Every AGENTS.md decision comes down to one question: are you writing this for the AI agent or for the developer?
The answer is both, and most AGENTS.md failures stem from optimizing for only one.
Over-optimized for the AI: Dense, comprehensive, technically precise instructions. Great for agent behavior. Terrible for developer maintenance. Nobody updates a wall of text nobody reads. Within 3 months, it is factually wrong.
Over-optimized for developer readability: Clean, readable overview of the project. Great for onboarding humans. Useless for agents, which need specific, actionable instructions, not project philosophy.
The best AGENTS.md files read like a well-structured operations runbook: organized for humans to maintain, specific enough for machines to act on.
Pattern 1: Commands First, Context Second
Every top-performing AGENTS.md opens with commands. Not a paragraph about what the project does — commands.
# AGENTS.md
## Commands
```bash
# Install
npm ci
# Development
npm run dev # Start dev server on :3000
npm run dev:api # Start API server on :4000
# Testing
npm test # Unit tests (Jest)
npm run test:e2e # E2E tests (Playwright, requires dev:api running)
npm run test:watch # Watch mode for unit tests
# Quality
npm run lint # ESLint
npm run typecheck # TypeScript compiler check
npm run format:check # Prettier verification
# Build
npm run build # Production build
npm run build:analyze # Bundle analysis
Why code blocks instead of bullet lists? Code blocks are unambiguous. "npm run test" in a bullet could be interpreted as prose. In a code block, it is a literal command.
The n8n AGENTS.md takes this further by including environment-specific variations: `docker compose up` vs. local setup, CI commands vs. dev commands. When Claude is uncertain whether it is running in a Docker environment or locally, it has both options.
## Pattern 2: Write for the Skeptical Agent
Agents are not dumb, but they are literal. Instructions that rely on inference fail more often than instructions that state things explicitly.
**Ineffective:**
```markdown
Follow the existing testing patterns.Effective:
## Testing
Tests live in `__tests__/` adjacent to source files, named `[filename].test.ts`.
We use Jest with ts-jest for TypeScript. No test runner installation needed.
Test structure:
- `describe('[ComponentName]', () => {` for grouping
- `it('should [expected behavior] when [condition]', () => {` for test names
- Use `factory` functions from `__tests__/factories/` for test data — never hardcode IDs
Run a single test: `npx jest --testPathPattern="path/to/file.test"`The second version tells the agent where to find tests, what the naming convention is, how to construct test data, and how to run a single test for iteration. The first version tells the agent to look around and figure it out.
Pattern 3: Scope Boundaries with Reasons
The most universally practiced pattern in high-performing repos: explicit boundaries, with brief explanations of why each boundary exists.
## Boundaries
### Do Not Modify
- `src/generated/` — generated by protobuf, run `make generate` to regenerate
- `migrations/` — use `make migration name=<description>` to create new migrations
- `Makefile` — build system, changes need team review
- `docker-compose.yml` — shared infrastructure, changes need team review
- `.github/workflows/` — CI pipeline, changes need human review
### Do Not Delete
- `*.lock` files — always commit lockfile changes with dependency updates
- `docs/api/` — auto-generated from code, regenerated on build
### Requires Explicit Approval
- Adding new npm/Go/Python dependencies
- Changing test configuration
- Modifying database schema (use migrations instead)The reasons matter for the edge cases. “Generated by protobuf” tells the agent why it should not modify the file — not just that it cannot, but that any modification would be overwritten. This improves compliance when the agent encounters an apparent inconsistency.
LangFlow’s AGENTS.md adds a particularly useful detail: for each protected directory, it specifies what to do instead. “Do not modify migrations/” plus “use alembic revision --autogenerate” gives the agent a path forward.
Pattern 4: Anti-Pattern Cataloguing
Top repos maintain explicit lists of anti-patterns specific to their codebase. These are not general best practices — they are the specific things AI agents tend to do wrong in this particular project.
From a Python microservices project:
## Anti-Patterns
### Authentication
- Never roll custom session handling — use the `SessionManager` class in `auth/`
- Never store secrets in environment variables at runtime — use the secrets manager
- Never bypass the permission middleware with direct database queries
### Database
- Never use raw SQL — use the SQLAlchemy ORM models in `models/`
- Never use `Session.merge()` for updates — use explicit `query().filter().update()`
- Never load all records for filtering — filter at the query level
### Error Handling
- Never catch and swallow exceptions — log and re-raise or return error responses
- Never use bare `except:` — always specify exception type
- Never use `print()` for debug output — use the structured logger: `logger.debug()`
### Performance
- Never make N+1 queries — use `.options(joinedload())` for related objects
- Never load binary assets into application memory — stream through storage serviceThe specificity is what makes this useful. “Don’t make N+1 queries” is standard advice any agent knows. “Use .options(joinedload()) for related objects” is project-specific and directly actionable.
Pattern 5: The “What Success Looks Like” Section
A pattern from some of the most polished AGENTS.md files: a section that describes what correct behavior looks like, not just what to avoid.
## What Good Work Looks Like
When you complete a task:
- All existing tests pass (`npm test`)
- New code is covered by tests (aim for the same coverage level as surrounding code)
- `npm run lint` and `npm run typecheck` pass with no new errors
- The change is minimal — only what the task requires
- Commit message follows Conventional Commits: `type(scope): description`
If you find a bug or improvement opportunity outside the task scope:
1. Note it in a comment
2. Do not fix it
3. Mention it in your response for human follow-upThis establishes a definition of done. Without it, agents make their own judgments about when they are finished — which leads to either under-delivery (stopped too early) or over-delivery (refactored the whole module when asked to fix one function).
Pattern 6: Tool Configuration as Explicit Configuration
A persistent AGENTS.md failure: the file describes the project but says nothing about which tools the agent should use to explore it.
## Navigation
When exploring the codebase:
- Use `grep -r` or `rg` for text search (ripgrep is installed)
- Use `find` for file discovery
- Use `git log --oneline -20` to understand recent changes
- Use `git diff HEAD~1` to see what changed recently
When you need to understand a type or function:
- Check the inline JSDoc/godoc comments first
- If unclear, check the test file for usage examples
- Check `docs/architecture/` for architectural decisions
Do not use web search for project-specific questions — ask instead.This is low-overhead to write but meaningfully improves agent navigation efficiency. Without it, agents often use inefficient exploration strategies (reading every file in a directory) when targeted search would be faster.
Pattern 7: Versioned Decision Records
A pattern adopted by more mature projects: keeping a brief history of architectural decisions in AGENTS.md, so agents understand why the current state exists.
## Decision Log
- **2025-08**: Migrated from Jest to Vitest for 40% faster test runs. The config is in `vitest.config.ts`.
- **2025-10**: Switched from REST to tRPC for internal service communication. See `packages/trpc/`.
- **2026-01**: Moved from class-based React to functional components. All new components use hooks.
- **2026-03**: Adopted Zod for all validation. No more manual validation functions.This prevents agents from “fixing” things that were deliberately changed. Without this log, an agent that sees functional components might “helpfully” note that some parts of the codebase still use class components (legacy code that was not migrated). With the log, it understands the direction and expected inconsistencies.
Pattern 8: Per-Team Section Structure
For larger codebases with multiple teams or domains, a section structure that mirrors the team structure improves clarity significantly.
# AGENTS.md — Platform Monorepo
## Shared Infrastructure
[Commands, boundaries, conventions shared by all teams]
## Frontend (apps/web/)
Owner: Frontend team
- Stack: React 19, TypeScript, Vite
- Tests: Vitest + RTL
[Frontend-specific rules...]
## Backend API (services/api/)
Owner: Backend team
- Stack: Go 1.22, Chi router, PostgreSQL
- Tests: testify
[API-specific rules...]
## Data Pipeline (pipeline/)
Owner: Data team
- Stack: Python 3.12, Prefect, dbt
- Tests: pytest
[Pipeline-specific rules...]When Claude is working in services/api/, it can identify and focus on the Backend API section rather than reading all frontend and data pipeline rules. The owner tag also helps clarify who to ask about ambiguous decisions.
Pattern 9: Security Section as a First-Class Citizen
Security requirements are often buried in general coding standards. The projects with the best security posture surface them as a distinct section.
## Security Requirements
These are non-negotiable. If you encounter a conflict with other requirements,
security requirements take precedence.
### Secrets and Credentials
- Never commit API keys, tokens, passwords, or connection strings
- Use `process.env.VARIABLE_NAME` only through the typed config object in `config/`
- `.env` files are gitignored; `.env.example` is the template
### Input Handling
- All user input goes through the validation schema in `validation/`
- Never construct SQL queries with string interpolation
- Never use `innerHTML` or `dangerouslySetInnerHTML` without explicit sanitization
### Authentication
- All API routes require authentication middleware unless explicitly marked public
- Public routes must be listed in `src/routes/public.ts`
- Authentication logic lives in `auth/` — never duplicate or reimplement it
### Reporting
If you notice a potential security issue while working on something else:
mention it immediately in your response, do not attempt to fix it silently.The “these take precedence” framing is important. Without priority signaling, agents sometimes deprioritize security requirements when they conflict with other goals.
Pattern 10: The Maintenance Commitment
This is meta, not in-file, but important: top repos treat AGENTS.md maintenance as part of the development workflow, not as documentation.
The concrete practices we saw:
Trigger-based updates: When a dependency changes, check if AGENTS.md commands need updating. This happens in the PR that changes the dependency.
Pair with migrations: Any change to migrations/ triggers a check of the AGENTS.md database section. Same for config file changes.
Onboarding as quality gate: When a new developer joins, they read AGENTS.md as part of onboarding. Their questions flag outdated or missing content.
CI drift detection: Some repos add a GitHub Actions check: if specific config files change (package.json, go.mod, requirements.txt) without a corresponding AGENTS.md change, the check creates a reminder issue. See our AGENTS.md CI/CD automation guide for implementation details.
Common AGENTS.md Anti-Patterns
The project README dump. AGENTS.md should not be a duplicate of README.md. Context that helps humans understand the project vision is noise for agents. Keep AGENTS.md operational: what to run, what not to touch, how to work.
Vague project-type claims. “This is a modern web application using best practices” tells the agent nothing. Specifics or silence.
Commands that require human context. “Deploy to staging” as a command is dangerous without clarification. If deployment is not something agents should do, explicitly exclude it. If it is, include every detail needed to do it safely.
Forgetting the negative. Agents are trained on millions of repositories. They have strong priors about how web apps, Go services, and Python scripts should be structured. Your AGENTS.md needs to tell the agent where your project deviates from those priors. The default is the training data. AGENTS.md is your way of overriding it.
Section names that mirror the agent’s assumptions. “Coding Standards” as a section header invites generic advice. “TypeScript Rules for This Repo” is more likely to hold genuinely project-specific content when written and read.
AGENTS.md vs. CLAUDE.md: Which Needs Best Practices More?
An honest assessment: Claude Code users who invest in CLAUDE.md quality get higher returns than those who invest the same effort in AGENTS.md.
This is because CLAUDE.md supports hierarchical loading, the import system, and user-level overrides — features that make it more responsive to detailed configuration. AGENTS.md is necessarily simpler.
But AGENTS.md best practices matter more for teams using multiple AI tools. A well-crafted AGENTS.md means consistent agent behavior across Claude Code, Cursor, OpenAI Codex, and Gemini CLI. CLAUDE.md cannot deliver that.
The right frame: AGENTS.md best practices are about extracting the maximum value from a tool-agnostic format. CLAUDE.md best practices are about extracting the maximum value from a Claude-specific format. Both are worth doing if you use the respective tools.
Starting Point Templates
For a minimal but effective AGENTS.md, start with these four sections:
# AGENTS.md
## Commands
[All commands to build, test, and lint the project]
## Boundaries
[What not to modify and why]
## Project-Specific Conventions
[The conventions that deviate from defaults agents would assume]
## Anti-Patterns
[The specific mistakes agents make in this codebase]Anything else is additive. Add architecture context when it prevents a class of mistakes. Add the security section when the project handles sensitive data. Add the decision log when legacy patterns need explanation.
For tool-specific guidance on integrating AGENTS.md with Claude Code subagents, see our guide on AGENTS.md real-world examples from top repos.