Rules Files and a Prompt Library: Make the Repo Remember

TL;DR Retyping your stack and your review prompt into every chat costs minutes each session, and conventions still break in the next one. Whatever you type twice belongs in the repo: a short rules file for the facts the model can't guess, and a shared prompt library for the prompts you reuse, both reviewed like code.

Do this: Open your rules file (or create AGENTS.md), cut every line the model could learn from the code, and add the commands it keeps getting wrong.

Part 1 ended with a prompt that works and a cost that stays: in every new chat you type "TypeScript, page objects in tests/pages/LoginPage.ts, pnpm not npm" again, plus the same review prompt. Those lines belong in the repo, where the model reads them on every request.

The model isn't forgetting "pnpm, not npm". Nothing persists between calls, so it never had anywhere to keep it.

AI Practices for Engineers, in 6 parts:

1. How LLMs Work, and How to Ask So They Stop Guessing
2. Rules Files and a Prompt Library: Make the Repo Remember (you are here)
3. Run Coding Agents Without Babysitting, and Reset Them When They Loop
4. AI-Generated Code: Checks That Can Fail, and the Calls That Stay Yours
5. Prompt Injection and the AI Bill: Give the Agent Less to See
6. Turn Repeated Fixes into Skills, Then into a Team Practice

Three layers, and one rule for moving between them

Every AI coding tool builds what the model sees from the same three layers: rules loaded every session, context attached per task, and the prompt you type now.

If your team uses more than one tool, put the shared conventions in AGENTS.md, the open cross-tool format. CLAUDE.md can point at it with one line: See @AGENTS.md. These tools change weekly; when this table and your tool disagree, trust your tool's docs.

What earns a line in a rules file

A rules file is read on every request, so every line taxes every task. A line earns its place when the model can't learn it from the code.

Here is the guide's AGENTS.md template, trimmed and filled in for the auth service that will get the login rate limit:

## Project
Auth service: login, sessions, tokens. Current focus: rate limiting
on POST /api/login.

## Setup & checks
install: pnpm install   test: pnpm test   lint: pnpm lint
Always run lint + tests before declaring a task done.

## Code style
Match the structure of src/auth/session.ts for new handlers.
Error messages are shown to users: no stack traces.

## Testing instructions
Unit tests in tests/auth/. UI tests use Playwright page objects
in tests/pages/ (LoginPage.ts). Never mock Redis in integration tests.

## Boundaries
- No new dependencies without an explicit ask
- Ask before: migrations, CI config

Every line is something the model would otherwise get wrong.

The review prompt that hides real bugs

Prompts you reuse belong in the repo too, because a bad one costs more than a retyped line. "Only report important issues" sounds sensible in a review prompt. Current models follow it literally: they judge each finding against your bar and silently drop the real bug they rated minor. You never see what was filtered.

The guide's fix is two passes, in two sessions:

Review the diff between <diff> tags. Report EVERY issue you find,
including uncertain or low-severity ones; a separate pass will
filter. For each: file:line, what is wrong, a concrete failure
scenario, confidence, severity, and a short fix.
<diff>{{git diff}}</diff>

Below are candidate findings and the diff. Try to REFUTE each one
by reading the code. Verdict per finding: CONFIRMED (the exact
failure path), REFUTED (why it can't happen), or NEEDS-INFO.
Add no new findings.

The session that produced a finding is a poor judge of it. Run this on the rate-limit diff and the first pass lists every candidate; the second keeps only what survives.

Keep the library alive

A test-case prompt from the same library asks the model to mark guesses as [ASSUMPTION: ...] instead of inventing them. On the rate limit, a case that depends on "per IP only, or per account too?" comes back marked. A guess you can see is a question you can answer.

1. Keep the prompts in the repo, reviewed like code, so everyone gets each fix.
2. Fill every {{PLACEHOLDER}}; an empty one gives generic output.
3. Keep the instructions frozen, which also helps prompt caching.
4. Prune after model upgrades: old workarounds become dead weight.

Try it

Read this repo's README, package files and a few source files.
Draft an AGENTS.md under 60 lines: project, setup and checks,
code style that differs from defaults, testing, boundaries.
Leave out anything you could infer from the code. Mark any line
you are guessing with (?) so I can confirm it.

The conventions load in every session, and the review prompts sit one file away. You're ready to hand over the change itself: rate limiting on POST /api/login. An agent will read the rules, edit files and run commands for an hour. How do you let it work without watching every step, and what do you do when it goes in circles? Part 3, Run Coding Agents Without Babysitting, writes the brief.

Read this with your AI

Read the post at <this post's URL or .md link>.
Then review my current rules file: <paste>.
Sort every line into keep / move to the prompt / delete, with a reason,
and point out any two lines that contradict each other.