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 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.