AGENTS.md Template for Teams

A useful AGENTS.md template covers repository context, coding conventions, testing expectations, workflow rules, and escalation paths. Each section should be written in direct, actionable language so AI coding agents and humans can interpret it the same way.

Templates should be stable and rarely rewritten from scratch. When major changes are necessary, treat them like any other configuration migration: design the new shape, plan the rollout, and communicate the impact to affected teams.

The example below shows a full AGENTS.md template that many teams can adapt. It is intentionally generic and should be customized to match your stack, risk tolerance, and workflows.

# AGENTS.md

## Repository context
- This is a TypeScript monorepo using Next.js on the web and Node.js for backend services.
- We use PostgreSQL via Prisma as the primary database.
- Treat this file as production configuration, not casual documentation.

## Goals
- Help engineers write maintainable, well-tested code that matches our standards.
- Surface trade-offs when proposing significant architectural changes.
- Avoid introducing security, privacy, or reliability regressions.

## Coding conventions
- Prefer explicit types on public interfaces and exported functions.
- Keep business logic out of React components; favor hooks and services.
- Use async/await, not raw Promise chains.
- Name things clearly and consistently; avoid single-letter identifiers in production code.

## Testing expectations
- Add or update tests for non-trivial behavior changes.
- Keep unit tests fast, deterministic, and focused on behavior.
- Use integration tests around critical workflows and data boundaries.
- When suggesting large refactors, outline a test strategy before applying changes.

## Security and data handling
- Do not log secrets, access tokens, or full customer payloads.
- Prefer parameterized queries and ORM helpers over raw SQL.
- Call out security-sensitive changes explicitly in comments and pull request descriptions.

## Workflow and collaboration
- Explain non-obvious trade-offs when generating or refactoring code.
- Suggest incremental changes that can land in small, reviewable pull requests.
- When instructions in this file conflict with inline comments, prefer this file and call out the conflict.

## Documentation
- Link new features or patterns to existing documentation where possible.
- When creating new abstractions, suggest a short doc or README section summarizing intent.

## Tool-specific notes
- Assume multiple AI coding tools may read this file; keep instructions tool-agnostic.
- If you need to reference a specific tool behavior, do so in a neutral, descriptive way.

Deployment works best as a staged rollout. Start by applying the template to a small set of representative repositories, gather feedback from maintainers, and refine the language where it causes confusion or friction.

Once the template is stable, use tooling to generate pull requests that introduce or update AGENTS.md in additional repositories. Track acceptance and exceptions so you can see which projects remain on older versions and why.

For more on the operational side of this rollout, see How to Manage AGENTS.md Across Repositories.