--- title: "Rules Files and a Prompt Library: Make the Repo Remember" author: "Harry" published: 2026-10-31T04:47:29.213Z updated: 2026-10-31T05:07:11.493Z category: "Building with AI" tags: ["prompts-guide"] canonical: "https://fxblog.dev/posts/rules-files-stop-repeating-yourself" --- # Rules Files and a Prompt Library: Make the Repo Remember ## Key takeaways - If you type the same thing in two different chats, move it up to the rules layer. - A rules file is read on every request, so a line earns its place only when the model cannot learn it from the code. - Most healthy rules files are 30 to 100 lines; at 500 lines it is a wiki pretending to be a rules file. - Asking an AI reviewer for only important issues makes it drop real bugs; review in two passes, find then refute. - Keep shared prompts in the repo, reviewed like code, and prune them after model upgrades. > **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](01-how-llms-work.md) 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. > **Tip** > > The guide's golden rule: if you type the same thing in two different chats, move it up a layer. | Tool | Project rules file | | -------------- | --------------------------------------------------- | | Claude Code | `CLAUDE.md` | | Cursor | `.cursor/rules/*.mdc`, plus `AGENTS.md` | | GitHub Copilot | `.github/copilot-instructions.md`, plus `AGENTS.md` | | Codex | `AGENTS.md` | | Gemini CLI | `GEMINI.md` | 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. ![What goes in a rules file: stack, working commands, hard boundaries and hidden structure; what stays out: generic advice, things the code shows, task detail and stale facts](https://fxblog.dev/media/01a19048-71fc-7290-bde2-49289a87da6b/1600) _A wrong rule is worse than no rule._ Here is the guide's `AGENTS.md` template, trimmed and filled in for the auth service that will get the login rate limit: ```markdown ## 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. > **Warning** > > Most healthy project rules files are 30 to 100 lines. If yours is 500, it's a wiki pretending to be a rules file: move the reference material out and link to it. ## 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: ![Two-pass code review: pass one lists every possible issue, pass two in a fresh session tries to refute each one, and only confirmed findings remain](https://fxblog.dev/media/01a19048-7964-707e-a9d3-bd97ad46e250/1600) _Separate sessions cut false positives sharply._ ```text Review the diff between 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. {{git diff}} ``` ```text 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 ```text 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 ```text Read the post at . Then review my current rules file: . Sort every line into keep / move to the prompt / delete, with a reason, and point out any two lines that contradict each other. ``` > **Success** > > Your tools now start every session with your conventions, and your best prompts live beside the code. Next: **Run Coding Agents Without Babysitting, and Reset Them When They Loop**. ## FAQ ### I use several AI tools. Do I need a file for each? Put shared conventions in AGENTS.md and keep only tool-specific extras in each tool's own file. Claude Code can point at AGENTS.md with one line in CLAUDE.md. ### Why two review passes instead of one? The session that produced a finding is a poor judge of it. A fresh session told to refute each finding cuts false positives sharply, while the first pass still lists every candidate.