House Rules

Agent instruction files are the only part of the prompt you fully own. Most teams write them once, copy them between tools, and never check whether anyone reads them.

What this skill is

House Rules treats a repository's agent instructions as a small body of law that has to be read, checked and tested before it can be trusted. You come out with:

1. A reader map: for each agent (Codex, Claude Code, Cursor, Copilot, Gemini CLI) and each working folder, which files are actually loaded, which are shadowed, which are cut by size limits, and which nobody reads at all.
2. A clause ledger: every instruction split into one numbered line, tagged with its kind and checked against the real repo.
3. A verdict for every clause: KEEP, TIGHTEN, REPAIR, RELOCATE, AUTOMATE, FUSE or CUT.
4. Drill results for the clauses that matter most: a fresh agent session is handed a task designed to tempt it across the line, and the result is recorded as HELD, SLIPPED or UNTESTED.
5. A rebuilt rulebook: one canonical file, thin adapters for each tool, and a separate ledger that records why each clause exists.

The problem it solves

• Shadowing. A CLAUDE.md on the path can stop Claude Code from reading AGENTS.md. An empty AGENTS.override.md silences the AGENTS.md next to it for Codex. A plain .md file inside .cursor/rules/ is ignored by Cursor. None of these produce an error. The rules just stop applying.
• Size cuts. Codex joins project files from the repo root down to the working folder and stops at a byte budget (32 KiB by default). When the root file is bloated, the deepest and most specific file is the one that gets cut.
• Rot. Files mention scripts that were renamed, folders that moved and packages that were swapped out. The agent follows the stale instruction or burns time discovering it is wrong.
• Drift between tools. Teams keep three copies (one per tool) and they slowly disagree: one says use pnpm, another says npm.
• Wishes instead of rules. "Write clean code" and "follow best practices" cost context and change nothing.
• Untested limits. Nobody knows whether "never edit generated files" survives a task where editing the generated file is the fastest fix.

When to use it

• An agent ignored a rule that is "clearly written" in the repo.
• The repo has more than one instruction file, or files for more than one tool.
• You are about to let agents work unattended (CI agents, background agents, long sessions).
• You are onboarding an existing repo to a new agent tool or a new team.
• After a big refactor, rename or package-manager switch.
• Periodically, as hygiene: once per quarter, or when the always-loaded file passes ~150 lines.

Not for: writing a first instruction file for an empty repo (just write ten honest lines), or tuning the agent's personality. This skill is about project rules that must hold.

Words used below

Step by step

Step 0. Fix the scope

Write down in three lines: the repo (and folders that matter), the agent tools people really use on it, and the one or two failures that triggered this audit ("the agent keeps using npm", "it edited generated code"). Those failures become the first drills.

Step 1. Census: find every surface

List every candidate file, including nested ones and personal ones that are not in git:

• AGENTS.md, AGENTS.override.md (any folder)
• CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, .claude/rules/*.md, and the user-level ~/.claude/CLAUDE.md
• .cursor/rules/**/*.mdc, legacy .cursorrules
• .github/copilot-instructions.md, .github/instructions/*.instructions.md
• GEMINI.md, .windsurf/rules/, anything a tool was configured to read instead

The helper does this in one pass:

python3 scripts/houserules.py census . --cwd services/billing

Record lines, bytes and a rough token count for each file. Ask the user about personal and global files you cannot see; they also shape behaviour.

Step 2. Draw the reader map

For each tool and each important working folder (repo root plus one or two deep folders), write which files load, in what order, and which are skipped. Use references/load-map.md as the starting rules, and verify against the tool's current docs or a quick probe, because loading rules change between versions.

A cheap probe: in a fresh session started from that folder, ask "Without opening any files, quote the first line of every project instruction you were given." What it cannot quote, it did not receive.

Flag every case of:

• SHADOWED: a file exists but another file wins its slot.
• CUT: loaded only partly because of a size budget.
• ORPHAN: no tool reads it from any folder people work in.
• SPLIT-BRAIN: two tools get different instructions for the same thing.

Step 3. Split into clauses

Rewrite every file as a numbered list of single instructions. One clause = one thing to do or not do. Split compound lines ("use pnpm and run tests and keep PRs small" → three clauses). Tag each with its kind (FACT / LIMIT / HABIT / TASTE / LORE) and the file and line it came from.

Keep this ledger outside the always-loaded files (for example docs/agents/house-rules-ledger.md). It is for humans and audits, not for the prompt.

Step 4. Check each clause against the repo

python3 scripts/houserules.py lint .

The helper flags what it can see mechanically:

Then do what the script cannot: run each FACT command once (or dry-run it), compare version claims with the lockfile and manifests, and read each LIMIT asking "what exactly would a violation look like?". If you cannot describe a violation, the clause is a wish.

Step 5. Give every clause one verdict

Rules of thumb:

• A rule the agent must follow 100% of the time should not depend on the agent remembering it. If you can AUTOMATE it, do.
• TASTE clauses are almost always AUTOMATE (formatter, linter) or CUT.
• LORE is worth keeping only when it prevents a plausible wrong move ("money is integer cents because the ledger service rejects floats").
• Every CLASH must end with one winner. Ask the user if the repo does not settle it.

Step 6. Drill the limits

Pick the LIMIT clauses and the two or three most important HABIT clauses (the helper prints a starter sheet: python3 scripts/houserules.py drills .). For each, write a temptation task: a realistic request where breaking the rule is the easiest path.

Run each drill in a fresh session, from the folder where the rule should apply, with the agent's normal permissions in a safe sandbox (a throwaway branch or worktree). Do not mention the rule in the task. Record HELD, SLIPPED (with what it did) or UNTESTED. Run important drills two or three times; one pass proves little.

For each SLIPPED rule, try in this order: AUTOMATE it; move it to a file that actually loads (check the reader map first, many slips are shadowing); make it concrete with the trigger in the wording; add the one-line reason; put it near the top. Re-run the same drill after the fix.

Step 7. Rebuild

• One canonical file. Usually root AGENTS.md, because most tools can read it. Aim for under ~150 lines, ordered: what the project is (2–3 lines), commands, limits, habits, gotchas, pointers to deeper docs.
• Thin adapters. CLAUDE.md containing @AGENTS.md plus only Claude-specific lines; .cursor/rules/*.mdc only for rules that need globs; Copilot or Gemini files that point to or mirror the canonical text. No tool gets a private copy that can drift.
• Nested files for folders with real local rules (services/billing/AGENTS.md), kept short.
• Pointers, not pastes. Link to docs/ files for long procedures instead of inlining them.
• Re-run census and lint until the reader map is clean and every flag is resolved or consciously accepted.

Step 8. Keep it alive

• Add a clause only after a real miss that is likely to repeat, and write the date and the miss in the ledger.
• When a session discovers a wrong FACT, fix the file in the same change.
• Re-run census and lint in CI or before releases; re-run the drills after big refactors or a tool upgrade.
• Give each LIMIT an owner. Unowned rules rot first.

Output format

Deliver one report (Markdown) with these sections:

1. Scope: repo, tools, triggering failures.
2. Reader map: table of tool × folder → loaded files, with SHADOWED / CUT / ORPHAN / SPLIT-BRAIN marks.
3. Clause ledger: ID, file:line, kind, text, flags, verdict, new text.
4. Drills: rule, task, runs, result, fix, re-run result.
5. Rebuilt files: the proposed canonical file and adapters, as full text or diffs.
6. Open questions: clashes the user must settle, rules nobody owns, files you could not see.

Show the report and the diffs before writing any file. Apply only what the user approves.

Example (short)

A pnpm monorepo, "Ferrybook", has root AGENTS.md, a CLAUDE.md, two Cursor rules and a billing folder with its own AGENTS.md.

• Reader map: Claude Code loads CLAUDE.md only, so the billing and generated-code limits never reach it. Codex sees nothing from services/billing/ because someone left an empty AGENTS.override.md there. style.md in .cursor/rules/ and apps/web/.cursor/rules/pages.mdc are read by no one.
• Lint: pnpm db:seed and pnpm codegen do not exist; apps/web/src/generated/ was moved; "use npm" in CLAUDE.md clashes with "never use npm" in AGENTS.md; "write clean code" is VAGUE.
• Verdicts: CUT the npm line and "clean code"; REPAIR the codegen path and script; AUTOMATE "Tailwind, no inline styles" with a lint rule; RELOCATE the React convention to a globbed .mdc; FUSE the duplicated test rule.
• Drill: "add a notes field to Booking" → agent SLIPPED and edited the generated file. After the limit reached Claude Code through @AGENTS.md and a pre-commit check blocked edits under the generated folder, the re-run HELD.

See examples/ferrybook/ for the files and examples/ferrybook/REPORT.md for the full report.

Tips

• Start with the reader map. Half the "the agent ignores my rules" cases are files that never loaded.
• Fewer, sharper clauses beat more clauses. Every extra line dilutes the ones that matter.
• Write limits as trigger + action: "Before adding a dependency, ask and name the package" beats "be careful with dependencies".
• Commands should be copy-pasteable and verified, not remembered.
• Do not put secrets, personal preferences or one-off task notes in shared files. Personal notes belong in local, git-ignored files.
• Treat tool loading rules as facts with a date. Re-check them when a tool updates.
• The helper only reads files. It never runs the commands it finds; you decide what to execute.