A guide to writing an effective AGENTS.md — think of it as a briefing for a new AI teammate.
An AGENTS.md file works like an onboarding document for AI coding agents. The goal is to give the agent the same context you’d give a new teammate on their first day: what the project does, how to set it up, how to run tests, and what standards to follow.There are no required fields — it’s plain Markdown. The more specific and accurate you are, the better the agent performs.
Describe what the project does in a few sentences. Mention the tech stack and any non-obvious architectural decisions. This helps the agent understand what it’s working with before touching any code.
## Project overviewThis is a monorepo containing the web app, API, and shared packages for Acme.The frontend is React + Vite (TypeScript). The API is a Node.js Express server.Packages live under `packages/` and apps under `apps/`.
Be explicit. Agents will attempt to execute test commands they find in AGENTS.md automatically — make sure the commands are accurate.
Agents auto-execute testing commands found in AGENTS.md. Use real commands from your project, not placeholders.
## Testing instructions- Run all tests: `pnpm test`- Run tests for one package: `pnpm turbo run test --filter <project_name>`- Run a single test by name: `pnpm vitest run -t "<test name>"`- After moving files or changing imports, run `pnpm lint --filter <project_name>` to confirm ESLint and TypeScript rules still pass.- Add or update tests for any code you change, even if nobody asked.
If your project has title formats, branch naming conventions, or required checks, put them here.
## PR instructions- Title format: [<project_name>] <Title>- Always run `pnpm lint` and `pnpm test` before committing.- Commits should pass all tests before merging.
Mention anything that could cause harm if done incorrectly: secrets handling, production data, rate-limited APIs, destructive migrations.
## Security- Never commit `.env` files or API keys.- Do not run migrations against production without a manual review step.- The `STRIPE_SECRET_KEY` variable must never appear in client-side bundles.
These aren’t always necessary, but they pay off in complex projects.Architecture notes — explain folder structure, module boundaries, or why things are organized the way they are.Deployment steps — document the deploy process if it’s non-obvious or involves manual steps.Known gotchas — things that have tripped up developers before: flaky tests, environment-specific behavior, tools that need special flags.Large datasets — if the project involves large files or datasets, tell the agent what to avoid downloading or modifying.
# AGENTS.md## Project overviewMonorepo for the Acme platform. Frontend is React + Vite (TypeScript).API is Node.js + Express. Packages live under `packages/`, apps under `apps/`.## Dev environment tips- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.- Run `pnpm install --filter <project_name>` to add a package to your workspace so Vite, ESLint, and TypeScript can see it.- Check the `name` field inside each package's `package.json` to confirm the right name — skip the top-level one.## Setup commands- Install deps: `pnpm install`- Start dev server: `pnpm dev`## Testing instructions- Find the CI plan in the `.github/workflows` folder.- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.- From the package root you can just call `pnpm test`.- To focus on one step: `pnpm vitest run -t "<test name>"`.- Fix any test or type errors until the whole suite is green.- After moving files or changing imports, run `pnpm lint --filter <project_name>` to confirm ESLint and TypeScript rules still pass.- Add or update tests for the code you change, even if nobody asked.## Code style- TypeScript strict mode- Single quotes, no semicolons- Use functional patterns where possible## PR instructions- Title format: [<project_name>] <Title>- Always run `pnpm lint` and `pnpm test` before committing.## Security- Never commit `.env` files.- Do not touch production data without a manual review.
# AGENTS.md## Project overviewREST API built with FastAPI. Uses PostgreSQL via SQLAlchemy.Background tasks run through Celery + Redis.## Setup commands- Create virtualenv: `python -m venv .venv && source .venv/bin/activate`- Install deps: `pip install -e ".[dev]"`- Copy env file: `cp .env.example .env`- Start dev server: `uvicorn app.main:app --reload`## Testing instructions- Run all tests: `pytest`- Run a single test file: `pytest tests/test_users.py`- Run a single test by name: `pytest -k "test_create_user"`- Check coverage: `pytest --cov=app`- Fix all failures before committing.## Code style- Ruff for linting: `ruff check .`- Black for formatting: `black .`- Type hints required on all public functions.## PR instructions- Branch naming: `feat/<ticket>-short-description`- Run `ruff check .` and `pytest` before opening a PR.## Security- Never log request bodies — they may contain PII.- Database migrations must be reviewed before running against production.
