/agent-instructions

name: agent-instructions
description: Use when writing project instructions for a coding agent (CLAUDE.md, AGENTS.md, or equivalent). Covers what belongs in them, what does not, structure, and keeping them accurate as the project changes.
metadata:
  category: agent-tooling
  version: 1.0.0
  tags: [claude-md, instructions, context, onboarding, agents]

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.