Web Application Project Rules

When to use this

Drop this at the root of a frontend project. AGENTS.md is read by most agent harnesses at the start of a session, so it is where you put the things you would otherwise repeat every time.

Keep it short. A file nobody maintains is worse than a short one that is accurate.

The template

# AGENTS.md

## Project

[One or two sentences: what this app is and who uses it.]

Stack: React 19, TypeScript, Vite, Tailwind CSS.

## Commands

- `npm run dev` starts the dev server on port 3000
- `npm run build` production build
- `npm test` runs the test suite
- `npm run typecheck` must pass before any commit
- `npm run lint` autofixes what it can

Run typecheck and tests before saying a change is done.

## Structure

- `src/components/` shared components
- `src/routes/` one directory per route
- `src/lib/` utilities and API clients
- `src/styles/` global CSS and Tailwind config

## Conventions

- TypeScript strict mode. Do not use `any`; use `unknown` and narrow.
- Function components with hooks. No class components.
- Styling is Tailwind utility classes. Do not add CSS modules or styled-components.
- Data fetching goes through the existing client in `src/lib/api.ts`.
- Tests live beside the file they test, as `Component.test.tsx`.
- Imports use the `@/` alias for anything under `src/`.

## Do not

- Do not modify anything in `src/generated/`, it is regenerated from the API schema
- Do not add a dependency without asking
- Do not change the Tailwind theme or the design tokens
- Do not commit directly to `main`
- Do not disable a lint rule to make an error go away, fix the cause

## Needs approval before proceeding

- Adding or upgrading a dependency
- Any change to the build config or CI
- Any change to authentication or permissions
- Database or API schema changes
- Deleting a file

## Writing

Plain, direct prose in user facing copy and comments. No filler.

What to change

Replace the project sentence, the stack line, and every command with your real ones. A wrong command is worse than no command, because the agent will run it.

Adjust the structure section to your real directories. Delete rows that do not exist.

The "do not" section is the highest value part. Fill it with the things you have already had to correct an agent about.