agent-instructions

# Agent Instructions ## Purpose Write the project instruction file an agent reads before touching the codebase. Its job is to convey what the agent cannot infer and would get wrong — not to restate what it can read from the code. ## When to Use - Setting up a repository for agent-assisted development. - An agent that repeatedly makes the same wrong assumption about your project. - Refreshing an instruction file that has drifted from reality. ## Capabilities - Structuring project instructions for an agent audience. - Identifying what an agent cannot infer. - Encoding conventions, commands, and constraints. - Keeping instructions accurate as the project evolves. ## Inputs - The codebase, its conventions, and its build and test commands. - The mistakes agents actually make in this repository. - The things a new team member always has to be told. ## Outputs - An instruction file that is short, specific, and correct. - Commands that work, verified. - Constraints that prevent the failures you have observed. ## Workflow 1. **Write down what an agent gets wrong** — Start from observed failures, not from a template. If the agent keeps running the wrong test command, that is the first line. 2. **State the commands exactly** — Build, test, lint, run. With the flags. An agent that guesses `npm test` when the project uses `pnpm test:unit` wastes a turn and may run the wrong thing. 3. **Encode the conventions that are not visible** — "We use `Result` types, not exceptions, in t...