AGENTS.md

AGENTS.md is an open format: put a Markdown file in the repository root that tells an agent what it needs to know to work on the project. README is for humans; AGENTS.md is for agents. It emerged from tools including OpenAI Codex, Cursor, Google Jules, Amp, and Factory, is now stewarded by the Agentic AI Foundation under the Linux Foundation, and is used by more than 60,000 open-source projects.

Why it is our top pick

• Works across tools. Cursor, Codex, Pi, and others read it directly, so you do not rewrite it when you switch. Claude Code reads CLAUDE.md by default; make CLAUDE.md a one-line pointer to AGENTS.md, or symlink it, to keep a single source of truth.
• No format overhead. It is plain Markdown with no required fields; use whatever headings you like.
• It can be layered. In large repositories, subfolders can have their own AGENTS.md, and the one closest to the edited file takes precedence.

What to write

1. Commands. How to install, run, test, and check. Agents need this most and guess it wrong most often.
2. Conventions. Code style, what each folder is for, naming, commit message format.
3. Boundaries. What needs permission first (committing, deleting, changing public interfaces) and which files are off-limits.
4. Verification. Which checks must pass after a change.

What not to write

• Background stories and marketing copy meant for human readers.
• General knowledge the model already has ("write clean code").
• Long procedures needed for only a few tasks; turn those into Skills.

# AGENTS.md

## Overview
- <one-sentence project description>
- Stack: <e.g. Vite + React + TypeScript, pnpm>
- Folders:
  - `src/features/` modules split by business feature
  - `src/components/` UI components shared across features
  - `src/lib/` framework-agnostic utilities

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Unit tests: `pnpm test`
- All checks: `pnpm check`

## Conventions
- TypeScript strict mode, no `any`; validate external input at the boundary.
- Component files use PascalCase; other files use kebab-case.
- Commit messages follow Conventional Commits.

## Boundaries
- Ask before committing, pushing, deleting files, or changing public interfaces.
- Do not read or print secrets from `.env*`.
- Do not hand-edit generated code or lockfiles.

## Definition of done
- `pnpm check` passes; new behavior has tests; when fixing a bug, first add a test that reproduces it.