A solo developer can write whatever they want in AGENTS.md and iterate daily. A team of 20 engineers cannot. Someone has to decide what goes in, who can change it, and how disagreements get resolved. That governance gap is where most team AI instruction files quietly fail — they start with good intentions and end up as stale text that nobody reads.
We reviewed 200+ public AGENTS.md files across teams of different sizes. The patterns that worked were consistent; the failures were also consistent. This guide distills them into three concrete templates, a tier system for categorizing rules, and a change management workflow your team can actually follow.
Why Teams Need AGENTS.md Standards
Individual AGENTS.md files have one author and one reader (the AI agent). Team AGENTS.md files have multiple authors, multiple AI tools reading them, and real consequences when they’re wrong.
The problems that emerge without standards are predictable:
Contradictory rules. Two engineers add instructions for the same situation but with different outcomes. The AI picks one arbitrarily. Neither engineer knows which rule is being applied.
Rule bloat. Nobody removes old rules. A file written for a React 17 project still has React 17 rules after a migration to React 19. The AI applies outdated patterns confidently.
Ownership gaps. When something goes wrong because the AI followed an instruction incorrectly, nobody knows whose instruction it was or whether it should be changed.
Tool mismatch. Instructions written for Claude Code don’t translate to Cursor or Codex CLI, but the team uses all three. The AGENTS.md works for one tool and confuses the others.
Standards don’t eliminate these problems, but they create the conditions to catch and fix them faster.
What Belongs in Team AGENTS.md vs Personal CLAUDE.md
Before choosing a template, get this split right. The division is not arbitrary.
Team AGENTS.md is committed to the repository and applies to everyone working on the project. It should contain only rules that are:
- True for all contributors regardless of personal preferences
- Enforceable and verifiable (code style rules that a linter can check, not “write clean code”)
- Stable enough to not change every week
- Relevant to the AI’s behavior when generating or editing code in this specific repo
Personal CLAUDE.md (at ~/.claude/CLAUDE.md or similar) is for individual preferences that have nothing to do with the project. Preferred programming font. Preferred explanation depth. Whether you want Claude to ask before making large changes. None of this belongs in the team file.
The line that causes the most confusion: personality and communication style. “Explain your reasoning before writing code” is a personal preference. “When writing database migrations, always add a down migration” is a project rule. Keep them separate.
| Belongs in Team AGENTS.md | Belongs in Personal File |
|---|---|
| Language version and runtime constraints | Preferred verbosity of explanations |
| Test framework and required test patterns | Whether to ask before large refactors |
| Migration and deployment safety rules | Code comment density preferences |
| Security and compliance requirements | Editor and tool preferences |
| Project-specific naming conventions | Personal workflow shortcuts |
| Code review and PR requirements | Preferred thinking style |
The Required / Recommended / Optional Tier System
Not all rules are equally important. A rule about secret scanning failing a CI build is not the same as a rule about preferred variable naming. Treating them identically leads to rule files where everything looks equally authoritative — so nothing actually is.
We found that teams with the most effective AGENTS.md files used an explicit tier system, either labeled directly in the file or enforced through structure.
Required — Non-negotiable. Breaking these rules has real consequences: security vulnerabilities, broken deploys, compliance failures, data loss. The AI should treat these as hard constraints. Phrase them as prohibitions and requirements, not suggestions.
## REQUIRED — Never Deviate
- Never log `process.env` values or objects that may contain them
- Never commit secrets, tokens, or credentials to any file
- All database schema changes must include a rollback migration
- Never call `force: true` on any Kubernetes resource operationRecommended — Strong preferences based on team experience. Breaking these is not catastrophic, but it creates friction — extra review comments, tech debt, inconsistency with the rest of the codebase. The AI should follow these by default and ask before deviating.
## RECOMMENDED — Follow Unless There's a Reason
- Prefer named exports over default exports
- Write tests before implementation for business logic
- Use the project's shared error types in `src/errors/`
- Co-locate tests with the file they test (`foo.ts` → `foo.test.ts`)Optional / Informational — Context that helps the AI make better decisions, but where flexibility is fine. These are guides, not rules. The AI can deviate when it has a good reason.
## CONTEXT — Background and Conventions
- This project uses the repository pattern for data access
- The legacy `src/v1/` directory uses class-based components; new code uses functional
- Performance-sensitive paths are in `src/core/` and marked with `// @perf`Label these sections explicitly in your AGENTS.md. Engineers skimming the file need to immediately understand which rules they’re debating versus which ones are already settled.
Template 1: Startup Team (2–8 Engineers)
Small teams move fast and change direction often. The priority is keeping the AGENTS.md short enough to stay current. Every rule you add is a rule someone has to maintain.
# AGENTS.md
## Project
TypeScript monorepo. Node 22 (LTS). pnpm workspaces.
Apps in `apps/`, shared packages in `packages/`.
## REQUIRED
- Never log secrets or auth tokens (check `process.env` usage)
- Tests must pass before declaring a task complete (`pnpm test`)
- Database migrations must include a rollback in `down()`
## Stack Conventions
- Zod for all schema validation and parsing
- Drizzle ORM for database access — no raw SQL in application code
- Error handling: throw typed errors from `@repo/errors`, catch at route level
- File naming: kebab-case for files, PascalCase for exported components/classes
## Tests
- Testing Library + Vitest for React components
- Node's built-in test runner for utility functions and API handlers
- One describe block per file, test names describe behavior not implementation
## What to Ask Before Doing
- Adding a new package to the monorepo
- Changing the database schema
- Modifying shared types in `packages/types/`Keep it under 60 lines. If you feel the urge to add more, ask whether it’s actually a rule the AI needs or whether it’s documentation that belongs in a README.
Template 2: Growth-Stage Team (10–30 Engineers)
Mid-size teams have multiple squads, tech leads, and enough history that “we did it this way because…” actually matters. The AGENTS.md needs to encode more context while still staying maintainable.
Add a ## Squads and Ownership section if your monorepo has domain boundaries. The AI will write better code when it knows which team owns which directory.
# AGENTS.md
## Project
Next.js 15 application with App Router. TypeScript 5.4 strict mode.
Deployed on Railway. Postgres 16 (Supabase). Redis for sessions.
## REQUIRED — No Exceptions
- Never expose database column names in API responses (use DTOs)
- Auth checks must use the shared middleware in `src/middleware/auth.ts`
- Never use `any` type without a suppression comment explaining why
- All environment variables must be validated with `src/config/env.ts` at startup
- RLS policies must be present for any new Supabase table
- Never push directly to `main` — all changes via PR
## RECOMMENDED
- Use server components for data fetching, client components for interactivity
- Prefer `useFormState` / `useActionState` over client-side form state
- Shared business logic belongs in `src/domain/`, not in route handlers
- Write E2E tests (Playwright) for any user-facing flow that involves payment
- Use `src/lib/logger.ts` for structured logging — not `console.log`
## Code Organization
src/ app/ # Next.js App Router pages domain/ # Business logic (no framework dependencies) infrastructure/ # DB, cache, external APIs lib/ # Shared utilities middleware/ # Auth, rate limiting, logging
## Squads and Ownership
- `src/domain/billing/` and `src/app/billing/` — Billing squad
- `src/domain/content/` and `src/app/content/` — Content squad
- `src/infrastructure/` — Platform squad
Changes to another squad's directories should include a note explaining why.
## API Conventions
- REST endpoints follow `/{resource}/{id}/{sub-resource}` pattern
- POST creates, PUT replaces, PATCH updates specific fields
- Error responses always include `{ error: string, code: string }`
- Paginated responses include `{ data: T[], cursor: string | null }`
## Tests
- Vitest for unit tests
- Playwright for E2E tests in `tests/e2e/`
- Integration tests in `src/__tests__/integration/` use a test database
- `pnpm test` must pass; `pnpm test:e2e` runs in CI onlyTemplate 3: Enterprise Team (50+ Engineers)
Large teams need governance, not just conventions. The AGENTS.md at the root level should be mostly security and compliance rules. Per-directory AGENTS.md files (which Claude Code, Cursor, and most agents support) carry the team-specific context.
# AGENTS.md — Root Level
## Scope
This file applies to all contributors across all services.
Service-specific rules are in `services/{name}/AGENTS.md`.
## REQUIRED — Compliance and Security
These rules exist for regulatory and security reasons.
Do not deviate without approval from the Security team.
- Never store PII in logs — mask or omit before logging
- Never write cleartext passwords, tokens, or keys to disk
- All external API calls must use the approved SDK in `libs/api-clients/`
- Input validation is mandatory on all public-facing endpoints
- Database queries must use parameterized statements — no string interpolation
- File uploads must pass the virus scanner middleware before processing
- Audit logs must be written for all create/update/delete operations on user data
## REQUIRED — Engineering Standards
These rules apply to all services regardless of team ownership.
- All services must expose `/healthz` and `/readyz` endpoints
- Breaking changes to shared types require a migration plan in the PR description
- Feature flags are in `libs/flags/` — no hardcoded feature gates in application code
- Service-to-service communication goes through the service mesh (no direct DB access across services)
## Recommended Style
- TypeScript strict mode in all new services
- ESLint with `@company/eslint-config` — no per-project overrides without Platform approval
- Error tracking via the shared Sentry client in `libs/observability/`
## How to Update This File
Changes to this file require:
1. An ADR (Architecture Decision Record) in `docs/adr/`
2. Review from at least one member of the Platform team
3. A minimum 48-hour review window before merging
For service-specific rules, update `services/{your-service}/AGENTS.md` directly.Service-level AGENTS.md (e.g., services/payments/AGENTS.md):
# AGENTS.md — Payments Service
See root AGENTS.md for company-wide rules. This file adds payments-specific context.
## REQUIRED
- All Stripe webhook handlers must verify the signature before processing
- Payment amounts are always in the smallest currency unit (cents, not dollars)
- Never log card numbers, CVV, or full bank account numbers
- Idempotency keys must be passed for all Stripe charge operations
## Architecture
Saga pattern for multi-step payment flows. Each saga step is in `src/sagas/`.
Compensating transactions are in `src/sagas/compensations/`.
State machine: `pending → processing → completed | failed | refunded`
## Tests
All payment flows must have integration tests against Stripe test mode.
Test cards and webhook payloads are in `tests/fixtures/stripe/`.Version Control and Change Management for AGENTS.md
If AGENTS.md files aren’t under version control, they will drift. Treat them like you treat package.json or database schema files.
Every change gets a commit with a reason. The commit message should explain why the rule changed, not just what changed. “Add rule about Stripe idempotency keys” is insufficient. “Add idempotency key requirement after double-charge incident in staging” gives future maintainers context.
Use git blame actively. When reviewing an AI-generated PR and noticing unexpected behavior, git blame AGENTS.md and find who added the rule that’s causing it. That person has the context for whether the rule should be changed.
Tag your AGENTS.md changes alongside related code changes. If you update the testing framework from Jest to Vitest, update AGENTS.md in the same PR. Separating them creates a window where the AI gives inconsistent advice.
Quarterly reviews. Schedule a calendar event four times a year. The agenda: read every rule in AGENTS.md, verify it’s still accurate, and remove anything that no longer applies. This takes 30 minutes for a startup-size file, an hour for a growth-stage file. Skip it and the file becomes unreliable within six months.
A diff in AGENTS.md is a signal. When a PR modifies AGENTS.md, treat it like a schema migration — require it to go through the same review process as any other infrastructure change. Who approved this? What’s the backward compatibility story? What happens to AI behavior on existing branches while the change rolls out?
Rolling Out New Standards Without Breaking Existing Workflows
The hardest part of AGENTS.md adoption in teams that already have workflows is the transition. Engineers have learned to work around gaps in AI instructions. When you fix the instructions, you change the behavior they rely on.
Start with additive rules. Your first PR should add rules that don’t exist yet, not change rules that are already there. Purely additive changes are lower risk and easier to review.
Annotate new rules with a start date. Adding # Added 2026-07-14 after incident-0291 to a rule’s comment gives engineers context for why a rule appeared and when to expect the AI to start following it.
Pilot with one team before rolling to all. For multi-team repos, propose a change in one service’s AGENTS.md first. Get feedback from engineers using it for two weeks. Then propose the same change at the root level.
Test with your actual tools. Claude Code, Cursor, GitHub Copilot, and Codex CLI all read AGENTS.md but interpret it differently. Before finalizing a rule, test it with the tools your team actually uses. We found that specific, imperative instructions (“Always use @injectable() decorator for service classes”) work consistently across tools; vague instructions (“Follow dependency injection patterns”) produce inconsistent results.
Document the “why” for rules engineers will question. Engineers are good at spotting rules that feel arbitrary. Rules that don’t have a visible reason get ignored or quietly removed. For any rule that isn’t obviously correct, add a comment explaining the incident, constraint, or decision that created it.
Use feature flags for behavioral changes. If you’re changing how the AI handles a core pattern — say, switching from a class-based to a functional approach — you can’t update every piece of existing code simultaneously. Add a comment in AGENTS.md noting which parts of the codebase use the old pattern, so the AI knows to be consistent within a file rather than mixing old and new.
Frequently Asked Questions
Can we have separate AGENTS.md files per directory in a monorepo?
Yes, and for large monorepos you should. Claude Code reads the AGENTS.md in each directory when working in that directory. Cursor does the same with .mdc files. Most agents that support AGENTS.md respect this hierarchy. Put company-wide security rules at the root, service-specific rules in the service directory. See the enterprise template above for how to structure this. Our guide to AGENTS.md in monorepos covers this in detail.
How do we handle tool differences? Claude Code vs Cursor vs Codex CLI.
Write instructions in plain, direct English without relying on tool-specific behavior. “Never add console.log to production code” works the same way in any tool. Avoid instructions that reference specific slash commands or UI behavior, since those are tool-specific. If you need tool-specific configuration, use the tool’s native config file alongside AGENTS.md — Cursor’s .mdc files for Cursor-specific rules, settings.json hooks for Claude Code-specific automation.
Who owns AGENTS.md changes in a large team?
The platform or developer experience team typically owns the root-level file. Service teams own their own AGENTS.md. Changes to root-level required rules should require a formal review process (ADR + platform team sign-off). Changes to service-level files need only standard PR review within the service team.
What happens when engineers disagree with a rule?
Good. The disagreement should be in the PR comments, not in the AGENTS.md file. One rule wins; the other becomes a comment in the PR explaining why it lost. This is how architectural decisions should work. “Required” rules are not up for debate at the individual level — escalate to whoever owns the security or compliance requirement. “Recommended” rules are negotiable through the standard PR process.
How do we keep AGENTS.md from growing unbounded?
Two practices: scheduled quarterly reviews (as described above), and a “two-rule budget” for new rules. For every rule you want to add, identify one existing rule that can be removed or made obsolete by the new rule. This isn’t a hard cap, but it forces you to evaluate whether the file is already handling the scenario somewhere.
Secure your team’s development environment with 1Password CLI — manage secrets used in AGENTS.md workflows with op run, rotate credentials without touching code, and audit exactly which environment variables your AI tools access. See our guide on Claude Code secrets management for implementation patterns. Browse the full collection of AI instruction file templates and real-world examples at The Prompt Shelf /rules.