Complete reference for the AGENTS.md file format, including structure, recommended sections, precedence rules, and examples.
AGENTS.md is plain Markdown. There is no schema, no required fields, and no special syntax. Any valid Markdown file named AGENTS.md is a valid AGENTS.md file.
AGENTS.md uses standard Markdown headings to separate topic areas. Conventionally, ## sections are used for each topic. There are no required sections — include only what’s useful for your project.
How to run tests, what CI checks exist, and what must pass before a change is complete. Agents will attempt to run commands listed here automatically.
## Testing instructions- Run `pnpm turbo run test --filter <project_name>` to run every check for that package.- From the package root, call `pnpm test`.- To focus on one test: `pnpm vitest run -t "<test name>"`.- Fix all test and type errors before finishing.- Add or update tests for any code you change.
Agents automatically execute testing and lint commands found in AGENTS.md and will attempt to fix failures before finishing a task.
Things the agent should be careful about — secrets, sensitive data, production systems, or destructive operations.
## Security considerations- Never commit `.env` files or secrets to the repository.- Do not modify database migration files that have already been applied.
A high-level overview of how the project is structured, useful for large or complex codebases.
## Architecture notes- This is a monorepo managed with pnpm workspaces and Turborepo.- Each package under `packages/` is independently deployable.- Shared utilities live in `packages/utils`.
In a monorepo, multiple AGENTS.md files can coexist at different directory levels.
A root AGENTS.md applies to the whole repository
A subdirectory AGENTS.md takes precedence over the root for files in that directory
The closest AGENTS.md to the file being edited wins
Explicit instructions given directly in chat always override AGENTS.md
The OpenAI main repository uses 88 AGENTS.md files — one at the root and one per package. This lets each package define its own build and test commands while sharing repo-wide conventions at the root.
# AGENTS.md## 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 the package to your workspace so Vite, ESLint, and TypeScript can see it.- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.- Check the `name` field inside each package's `package.json` to confirm the right name — skip the top-level one.## 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`. The commit should pass all tests before you merge.- To focus on one step, add the Vitest pattern: `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 be sure ESLint and TypeScript rules still pass.- Add or update tests for the code you change, even if nobody asked.## PR instructions- Title format: [<project_name>] <Title>- Always run `pnpm lint` and `pnpm test` before committing.
# AGENTS.md## Setup commands- Install deps: `pnpm install`- Start dev server: `pnpm dev`- Run tests: `pnpm test`## Code style- TypeScript strict mode- Single quotes, no semicolons- Use functional patterns where possible
# AGENTS.md — packages/api## Testing instructions- Run `pnpm test` from this directory to test only the API package.- Integration tests require a running database: `docker compose up -d db` first.- All endpoints must have corresponding tests in `src/__tests__/`.## Code style- Follow the root AGENTS.md conventions.- Use `zod` for all input validation — never `any`.
