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 the domain layer." An agent can read the code, but it cannot tell a convention from a coincidence.
4. State the hard constraints — Never edit generated files. Never commit to main. Never modify the migration history. These prevent real damage.
5. Keep it short — This file is loaded on every session. Every line costs context. Ruthlessly cut anything the agent could work out for itself.
6. Update it when it is wrong — An inaccurate instruction file is worse than none, because it is trusted.

Best Practices

• Do not restate what the code says. The agent can read package.json. It cannot know that the test script is broken and everyone uses test:ci.
• Commands must be verified. An instruction file listing a command that fails is a trap that costs a turn every session.
• Be specific about the boundaries: which directories are generated, which are vendored, which must never be edited by hand.
• Record the non-obvious architectural decision. "The legacy/ module is being strangled; do not add to it, extend orders/ instead" saves an agent from a well-intentioned wrong turn.
• A long instruction file is diluted. If it exceeds roughly 150 lines, most of it is not earning its place.
• Put project-specific conventions in the file and general engineering practice in skills. The instruction file is about this repository.

Examples

An instruction file that earns its tokens:

# Project instructions

## Commands
- Install:  `pnpm install --frozen-lockfile`
- Test:     `pnpm test:unit` (fast) / `pnpm test:integration` (needs Docker)
- Lint:     `pnpm lint --fix`
- Typecheck:`pnpm typecheck`
- Run:      `pnpm dev` (requires `.env.local`; copy from `.env.example`)

Do NOT run `pnpm test` — it is an alias for the full E2E suite and takes 25 minutes.

## Conventions
- Domain errors are returned as `Result<T, DomainError>`, never thrown.
  Exceptions are reserved for programmer error. See `src/shared/result.ts`.
- All money is `Money` (integer minor units). Never a float, never a number.
- Features may not import from other features. Shared code goes in `src/shared/`.
  This is enforced by ESLint; if you hit that rule, move the code rather than
  disabling the rule.

## Boundaries
- `src/generated/` is generated by `pnpm codegen`. Never edit by hand.
- `migrations/` is append-only. Never modify an existing migration, even to fix
  a typo — write a new one.
- `legacy/billing/` is being strangled. Do not add to it. New billing code goes
  in `src/features/billing/`.

## Gotchas
- The integration tests need Docker running. They will fail with a confusing
  connection error if it is not.
- `pnpm dev` binds to port 3000; if it is in use the error is silent and the
  server exits with code 0.

Every line here is something an agent would otherwise get wrong, and each one costs it a turn.

Notes

• The single most valuable content is the "do not run X" line. Agents will find the obvious command and use it; the trap is when the obvious command is the wrong one.
• Treat the instruction file as code: review changes to it, and fix it the moment it becomes inaccurate. A stale line will be followed confidently.
• If the same correction is given to an agent twice in a session, it belongs in the file.