Teach the Repo

A situation you may recognize

Monday. You tell the AI: “Run payment package tests, not root smoke tests.” It does. You merge.

Wednesday. New chat. Same repo. The AI runs pnpm test at the root. Green. Wrong package. You type the same correction again.

Friday. A teammate hits the same issue. They ask you for the “magic prompt.”

A fresh session has no memory of Monday’s chat. It reads files, layout, and behavior rules: if those rules do not exist, you become the manual. README helps humans onboarding; it rarely stops an AI from running the wrong command.

That pattern is easy to miss because Monday felt successful. The failure shows up as repetition, not as a red error screen. Session 3 is about moving knowledge from your head and chat history into places the next session loads automatically, so Wednesday does not start from zero.

Two readers, two manuals

Most repositories were written for human readers first. That is not wrong; it is incomplete for agent-shaped workflows.

When you open a README, you expect narrative: what the project is, how to install, where to get help. When a fresh AI session opens your repo, it often behaves like a new contractor on day one: eager, literate, and missing every unwritten rule your team accumulated in Slack threads.

The table below is not about adding more documentation for its own sake. It is about matching audience to file:

README is the welcome desk. Agent rules are house rules on the wall: run these tests, do not touch those paths, stop if unsure.

When an AI runs git clean or skips tests, the failure is often not “a bad model.” Nobody wrote the rule where the tool looks. The discovery to make in this session: every time you type the same correction twice, ask where would a new session find this without me?

Tool equivalents

Pick one place your team reviews in pull requests.

Pick one place your team reviews in pull requests. Two competing rule files teach conflicting behavior.

What changes when you write the rules down

The vignette below is short on purpose. Read it as a before/after you may recognize, not as a product demo.

# Agent house rules

## Tests
- Run tests in the package you touched: `pnpm --filter <pkg> test`
- Do not rely on root `pnpm test` alone

## Git
- Never run `git clean`, `git reset --hard`, or force-push
- Never commit `.env` or credential files

## Scope
- Payment code lives under `packages/payments/` — stay there unless the ticket says otherwise

What you knew on Monday was correct. What was missing was location: the rule lived in your head and chat history, not where the next session loads instructions.

One small pull request, often a dozen lines, can replace weeks of repeated corrections. On a team, that file is shared infrastructure, not a private notebook. The first time you merge agent rules, watch standup the following week: the “magic prompt” requests often quiet down, not because people got smarter, but because the repo got clearer.

A starter template you can adapt

# Agent house rules

## Before saying the work is done
- Run tests in the package you touched: `pnpm --filter <pkg> test`
- Do not rely on root test scripts alone for package changes

## Git
- Never run `git clean`, `git reset --hard`, or force-push
- Never commit `.env`, credentials, or secrets

## Scope
- Payment code lives under `packages/payments/`, stay there unless the ticket says otherwise

## When stuck
- Ask instead of guessing file paths or API shapes
- Do not add new dependencies without explaining why

If a line feels vague, “write clean code”, remove it. If a line saves you from typing the same correction twice, keep it. The test for each line: would I approve this in a pull request if a teammate wrote it? Vague rules get ignored; specific rules get followed.

Layout teaches too

Agent rules tell the tool what it must do. Layout tells it what the codebase is: often without a paragraph of explanation.

AI tools also infer meaning from structure: folders, tests, names. When an AI gets lost, the fix is often clearer structure, not a longer README. You may discover this by accident: you add a rule saying “payment code lives here,” then realize the folder was already named well and the rule only made explicit what layout implied.

Three layers, from specific to general:

Skills        →  one job          (“review this pull request”)
Agent rules   →  whole repository  (“run tests; never commit secrets”)
Code layout   →  silent hints      (boundaries, types, test folders)

For the payment helper:

Skill       → review-changes on the diff
Agent rules → run `pnpm --filter payments test` before reporting done
Layout      → src/payments/helpers/ and tests/payments/ show the boundary

Examples on this site:

A gentle try-it (optional)

1. Install review-changes or one skill from /skills/.
2. Run it on a small local change.
3. Write one agent rule you wish every future session already knew, specific enough that a teammate would approve it in a pull request.

Before Session 4

Session 4 opens with a diff and a green CI check. You will decide ship or hold before the rest of the session explains why.

Next: Session 4: Verify Before Merge