| name | agents-md |
| description | Create and maintain AGENTS.md files that provide AI coding agents with project context, commands, code style, and boundaries. Use when updating an existing AGENTS.md, creating a new AGENTS.md for a repository, or improving agent instructions for a codebase. |
Agents Md
AGENTS.md is a README for AI agents: a dedicated place to provide context and instructions to help AI coding agents work effectively on a project.
Important: Keep It Minimal
Key principle: Include only what agents cannot infer from the codebase itself. Redundant documentation is harmful—agents already read files, search code, and understand common patterns.
When to Create/Update
- Create: When the project has non-obvious tooling, specific commands, or critical boundaries agents must know
- Update: When commands change, new critical constraints are added, or tooling requirements evolve
- Omit: If your repository has standard structure and common tooling (React, Python, etc.) that agents already understand
What to Include
Focus only on information agents cannot discover themselves:
1. Essential Commands (Required)
Specific commands with full flags. Include only if non-standard or critical.
## Commands
- Install: `pnpm install`
- Dev: `pnpm dev --port 3000`
- Test: `pnpm test --coverage`
- Build: `pnpm build`
Skip this section if using standard commands (e.g., npm install, npm test).
2. Tooling Requirements (If Non-Standard)
Specify tools agents should use. Research shows agents DO follow specific tool instructions (e.g., uv usage increases 1.6x when mentioned).
## Tooling
- Use `uv` for Python dependency management
- Use `ruff` for linting (not flake8)
- Use `just` for task running (not Make)
Only include if different from defaults agents would assume.
3. Boundaries (Critical)
What agents must NEVER do. This is the highest-value content.
## Boundaries
- Never commit secrets, API keys, or `.env` files
- Never modify `vendor/`, `node_modules/`, or lock files
- Never remove failing tests—fix or ask first
- Ask before changing database schemas
Always include this section. It prevents costly mistakes.
4. Project-Specific Patterns (If Unusual)
Only document patterns that differ from standard conventions in your stack.
## Patterns
- Use functional React components, not classes
- Place tests in `__tests__/` folders (not `.test.ts` files)
- Import order: React, third-party, `@/`, relative
Skip if following standard conventions for your framework/language.
What to Avoid
Based on research findings, do NOT include:
❌ Codebase Overviews
Research shows "context files do not provide effective overviews"—agents don't discover files faster with overviews present. They already search and explore code effectively.
Don't write:
## Overview
This is a React application with a component-based architecture...
❌ Comprehensive Structure Documentation
Listing every directory is redundant. Agents can explore the filesystem.
Don't write:
## Structure
- `src/components/` - React components
- `src/hooks/` - Custom hooks
- `src/utils/` - Utility functions
❌ Obvious Style Guidelines
Agents already know common patterns (camelCase, functional components, etc.).
Don't write:
## Code Style
- Use camelCase for functions
- Use PascalCase for components
- Prefer const over let
❌ Verbose Explanations
Code examples are clearer than paragraphs. One snippet beats three paragraphs.
Prefer:
## Commands
- Test: `pytest -xvs tests/`
Over:
## Testing
To run tests, use the pytest command. This will discover all tests in the tests directory and execute them with verbose output and fail-fast behavior...
Workflow
- Check if needed: Does the repo have non-obvious tooling or critical constraints?
- If yes, create minimal file: Include only Commands (if non-standard), Tooling (if non-standard), Boundaries (always), and Patterns (if unusual)
- If updating existing: Remove redundant sections, keep only high-value content
- Validate: Ensure every line provides information agents cannot infer
Examples
Good: Minimal and Specific
# AGENTS.md
## Commands
- Install: `uv pip install -e ".[dev]"`
- Dev: `uvicorn app.main:app --reload --port 8000`
- Test: `pytest -xvs`
- Lint: `ruff check --fix .`
## Tooling
- Use `uv` for dependencies (not pip)
- Use `ruff` for linting and formatting
## Boundaries
- Never commit `.env` files
- Never modify `alembic/versions/` after merge
- Ask before schema changes
Bad: Redundant and Verbose
# AGENTS.md
## Overview
This is a FastAPI backend application with SQLAlchemy ORM.
## Tech Stack
- Python 3.12
- FastAPI 0.109
- SQLAlchemy 2.0
- PostgreSQL
## Structure
- `app/` - Application code
- `api/` - Route handlers
- `models/` - SQLAlchemy models
- `tests/` - Test files
## Code Style
- Use type hints on all functions
- Write docstrings for public functions
- Use async where possible
## Commands
- Install: `pip install -e ".[dev]"`
- Dev: `uvicorn app.main:app --reload`
- Test: `pytest`
Why it's bad: Stack and structure are discoverable from files. Style guidelines are standard Python practices. Overview is unnecessary.
Monorepos
For monorepos, place minimal AGENTS.md files at subproject roots:
repo/
├── AGENTS.md (root - only if repo-wide constraints exist)
├── packages/
│ ├── api/
│ │ └── AGENTS.md (API-specific tooling/boundaries)
│ └── web/
│ └── AGENTS.md (web-specific tooling/boundaries)
Keep each file focused on what differs from defaults.
References
