Instruction Files: Teaching the Agent Your Project

A README for the agent

Agents start each session knowing nothing about your project's conventions, so most tools read a project instruction file at the repository root (names vary by tool, for example AGENTS.md, CLAUDE.md or rules files). Put in it what a new teammate needs and cannot guess: how to build, test and lint (exact commands), project layout, coding conventions (naming, error handling, preferred libraries), things to avoid ("never edit generated files", "do not touch migrations"), and definition of done ("tests added, lint clean, changelog updated"). Keep it short, specific and current: long vague files dilute attention and rot. Prefer concrete commands over adjectives, link to deeper docs instead of pasting them, and review changes to this file like code, since it steers every future change. Never put secrets in it.

A good instruction file (illustrative)

Short, concrete and testable. Adapt names and commands to your project; not run here.

# AGENTS.md

## Commands
- Install: `pip install -e .[dev]`
- Test all: `python -m unittest discover -s tests -t .`   (must pass before you finish)
- Lint: `ruff check .`

## Layout
- `shop/` application code, `tests/` unit tests mirror the package layout

## Conventions
- Money values are integers in paise; never use floats for money.
- Raise `ValueError` with a clear message for invalid input; no bare `except`.

## Do not
- Edit files under `shop/generated/` or `migrations/`.
- Add new dependencies without asking.

## Done means
- A test covers the change; all tests and lint pass; the diff is small and explained.

Correct it when the agent errs

If the agent keeps making the same mistake, add a one-line rule to the file. Over time it becomes the project's accumulated lessons.

Quick check: What belongs in an agent instruction file?

• Exact build/test commands, conventions, things to avoid and what "done" means
• The production database password
• The whole source code
• A long list of vague adjectives