# AGENTS.md

Read by every agent on every surface — GitHub Copilot (IDE, CLI, cloud agent, code
review), and by Claude Code, Cursor and Gemini CLI too. One file, every vendor.

Keep it short. Everything here is loaded on every request, so a rule that is merely
nice-to-have dilutes the ones that matter. Path-specific rules belong in
`.github/instructions/*.instructions.md` with an `applyTo` glob instead.

Replace everything below with your own project's facts.

## Commands

Things an agent cannot guess and will otherwise invent:

```
<install>      e.g. pnpm install --frozen-lockfile
<build>        e.g. pnpm build
<test one>     e.g. pnpm test -- --run path/to/file.test.ts
<test all>     e.g. pnpm test
<lint>         e.g. pnpm lint --fix
<typecheck>    e.g. pnpm typecheck
```

Prefer running a single test file over the whole suite while iterating.

## Architecture boundaries

State the rules that a reasonable person would break by accident, and say *why* —
a rule with a reason survives a situation you did not anticipate.

- `<layer A>` must not import from `<layer B>`. (Reason: …)
- All network access goes through `<module>`. (Reason: retries and tracing live there.)
- `<generated dir>` is generated. Edit `<source>` and regenerate; never hand-edit.

## Conventions that differ from the default

Only list what departs from the language or framework norm — your linter already
enforces the rest, and repeating it wastes the budget.

- …

## Known traps

- …

## Where the real documentation lives

- `<path or URL>` — …