House Rules Explained

What this is

Claude Code is a program with an AI assistant that reads and edits the files in your project, and it will build almost anything you describe. Two things it will not do on its own: ask for the safeguards you did not know to ask for, and check that the instructions you gave it last month still hold. house-rules does both.

The first problem shows up on day one if you are not an engineer. You do not yet know what to ask for. Claude Code knows how to change stored data safely, or to try a change on a separate copy of the project first, but it does not decide on its own which of those your project needs. If you never think to ask for a backup, you will not have one on the day you needed it.

The second shows up a few weeks in. Whatever you write down for Claude Code is advice. A session is one working conversation with Claude Code. Nothing checks on its own that a session followed what you wrote, that what you wrote is still true after you rename a file, or that the copy in your next project still says the same thing. So what you wrote goes stale, grows too long to be followed, and drifts, and nothing tells you. A project, here, is the folder of files you are building something in.

house-rules is a set of plain-English working rules for a project built with Claude Code: how changes are made, how stored data is protected, how documents stay true, how what a session learns is kept, and more. The rules do the asking on your behalf, and each gives its reason in the same breath, so you learn the discipline as you go and can argue with any of them. They are copied into your project as ordinary files, and one command, a short instruction typed into a terminal (the text window where you type commands), reads those files and your project's documents back and reports where they and the project have stopped matching.

You do not need to be a programmer, only a project you care about, a terminal, and the few free tools set up under Getting started. Every technical word is explained where it first appears, with a glossary at the end. Aaron Altamura, who wrote these rules, explains further down why he needed them.

What goes quietly wrong

Two things go quietly wrong, and neither announces itself.

The first is what you never asked for. A change to stored data goes through without a backup. A fix lands straight on the shared copy of the project, with no separate copy to try it on first. A safeguard gets added and nobody proves it can catch anything. Each could have been prevented by one written rule, and you did not know to write it.

The second is what you did write down. The first week goes well. You put how you like things done in a file at the top of your project, and the sessions that follow mostly do it your way. Then the file grows, the project changes underneath it, and the two stop matching. A session that quietly skipped a rule looks exactly like one that followed it, and a rule that has become false looks exactly like one that is still true. One project is enough for a rule and its project to stop matching, and a second project multiplies the chances. The failures themselves are ordinary:

• The instruction file grew. Every fix added a paragraph, and now only some of it gets followed.
• A rule you wrote once now lives in three projects, because you copied it. Each copy has drifted, and none knows about the others.
• A rule tells the assistant to run a small program you renamed last month, and nothing told you. On its own, nothing compares a rule against the project it describes. The words stay exactly where you left them while the rule stops being true.
• You are asked why a rule exists, cannot remember, and the rule gets worked around instead of revised.
• What a session worked out on Tuesday is gone on Thursday, or lives only in notes on one machine nobody else sees.

Nothing broke. That is what makes both halves hard to notice: nothing broke, and nothing accumulated either. What you never asked for never happened, what you wrote down drifted, and nothing told you.

Your house: what Claude Code sets up, and what you post yourself

Every project you work in is a house you own. Claude Code is what the builder installed before you moved in, the same in every one of them. The assistant, from here on, means one working session of Claude Code: a guest, new each time. What the builder installed gives you:

• A noticeboard by the door. Claude Code reads the instruction file at the top of your project every session, plus rule files that name the file patterns they cover, which go up only when a matching file is opened, while a rule file that names none goes up every session. The board holds advice, and a guest may do otherwise.
• Doors and locks. Some commands you can simply forbid in Claude Code's settings file, and Claude Code refuses those itself. That is real enforcement rather than a request.
• A fuse box. A hook, a small program Claude Code runs just before an action, can cut the power to that action.
• A notepad on the fridge. The assistant keeps notes between sessions, on that machine only.
• The appliances you install. A plugin is an add-on that gives Claude Code extra skills and hooks. A skill is a set of instructions you trigger by typing its name after a slash. What a plugin cannot do is post anything on the noticeboard.

All of that is Claude Code's own work, and it gives you good places to put rules. What it does not do on its own is decide what those rules should say, or read the board back later to check it is still true, and one house is enough for both to bite.

house-rules is the posting itself, written for you by someone who knew what to ask for, in the same words in every house you own, plus four things the builder does not supply: a sealed copy of each posting, and every copy carries a fingerprint, a short code that changes if even one character of the file changes, so a scribble on the board shows up; an inspector who reads the house's documents; a ledger, a written record, of what this house does differently and why; and a handoff, so what the guest knew leaves the fridge.

The analogy has a limit worth naming. A real fuse box cannot be switched off by the appliance. This one can: a setting turns hooks off, and a session started bare, in safe mode, or in restricted mode loads no project hooks at all. So a rule that must hold gets a lock on the door beside it too, one of those forbidden-command settings, rather than relying on the fuse box alone.

How it works, in six moves

The whole method is six moves. The first three decide what a rule says and where it sits. The last three are how you find out when a rule has stopped being true.

1. Write a rule so it can be argued with. An instruction you could follow, one clause saying why, a line naming what enforces it, a pointer to the evidence that earned it. A rule with no why gets worked around.
2. Post only what is relevant. Rule files have a ceiling, a maximum length set in your project's own settings file; this package sets 200 lines, and each names the kinds of file it covers, so a session picks up only the rules that matter.
3. Copy the rules in rather than link to them. They are written word for word into your own copy of the project, your checkout, where Claude Code reads them like any other file.
4. Record a fingerprint of each copy. The fingerprints live in a lock file, a record of how each file looked when it arrived.
5. Have something read the project back to you. A checker rereads the project's documents whenever you ask and reports what no longer holds.
6. Change it at the source. A rule you disagree with is fixed in the package rather than your copy, and the next version reaches you as a plan you approve.

What is in the package

Nine modules, 112 rules in all. A module is a themed set of rules. Five of the nine are on unless you switch them off.

• claude-code protects the assistant's setup: what it reads each session, how long that is, where a new fact belongs.
• docs protects the written record, the README and changelog and rule files, so no document points at something that no longer exists.
• engineering protects how code gets written and changed day to day.
• github protects how a change travels on GitHub, the website where a project and its history are kept and shared: a branch and a pull request each time. A branch is a separate copy of your work, made so you can change things away from the main line, which is the version of the project everyone builds on. A pull request proposes folding your branch back into that main line, with somewhere to review it first.
• testing protects the word done: what gets tested, and what a passing test may claim.

Four more turn on only if your project looks like it needs them. database protects stored data when its shape changes. deployment protects releases, so putting something live is deliberate. data-pipelines protects scheduled jobs that move data in bulk. llm-output protects text a model produced, before anyone reads it as fact.

Here is the first half of the problem answered: things you would not have known to ask for. One example from each module, in plain words. Each is something the assistant now does, or refuses to do, without you thinking to ask.

• claude-code: When more than one Claude Code session might be working in the same project, the assistant saves your changes and asks you before switching tasks, so a second session cannot quietly strand the first one's work.
• docs: The assistant never writes a command or setting into your project's instructions unless it already exists, so you never follow a step that is not real.
• engineering: The assistant keeps passwords and secret access codes out of your project's code, storing them somewhere separate, so publishing or sharing the project cannot leak them.
• github: On GitHub, typing "fixes" or "closes" next to a task's number closes that task automatically, even by accident. The assistant avoids those words unless it means them, so open tasks do not quietly disappear.
• testing: When the assistant adds a check meant to block a bad change, it also writes a test proving the check can catch one, so a silently broken safeguard cannot wave bad changes through.
• database: Before any change to stored data that could delete or overwrite it, the assistant takes a backup, proves the backup restores, and compares record counts afterward, so a mistake cannot silently destroy data for good.
• deployment: The assistant restores your backup for real from time to time, rather than only confirming a file exists, so you learn whether it works before an emergency instead of during one.
• data-pipelines: The assistant refuses to delete more than a small share of any stored data set unless you confirm it, because a run that empties everything looks like routine cleanup until it is too late.
• llm-output: Text a model produced goes into a separate holding area, not straight into your files, so nothing becomes final until a person has checked and moved it, apart from cases you approved in advance.

Five skills you run. A skill is a set of instructions you trigger by typing its name after a slash, inside Claude Code.

• /house-rules:bootstrap sets a project up the first time.
• /house-rules:sync brings a later version in.
• /house-rules:conventions answers "what is the house rule for this" from a short index, a table of contents of the rules, without reading every rule.
• /house-rules:revise-docs files something you just learned where it belongs.
• /house-rules:handoff closes a session by writing down what the next person needs.

house-rules includes a hook called the branch guard, and it is the fuse box in action. Because it is a hook, it runs on its own: when your project's settings say changes go through pull requests, it refuses to commit or push a change straight onto the main line. A commit is one saved snapshot of a change, and a push sends your saved changes up to GitHub.

The checker is the inspector: one command, node .house/check.mjs, running ten kinds of check. Among the things it looks for: a copy edited by hand, a document naming a file that is gone, and a file past its line ceiling.

Beside them sits house.json, the settings file for all of this, written into your project when you set it up. It records which modules are on, keeps a dated ledger of anything you declined, and holds the per-file line ceilings, which tighten as files shrink. Twelve evals hold a session to these rules. An eval is a real task plus a check of whether the rules held. They come in pairs: one case where a rule should hold, and one where it should stay quiet because it does not apply.

Why I built this

I'm Aaron Altamura. By day I build AI and data systems for go-to-market teams at software companies, which is to say I'm not a software engineer by trade. I build the tools I need with Claude Code, and I wrote this guide, co-written with Claude Code, in the plain language I wished I had at the start.

Over about five months I built five working projects that way, roughly 1,312 commits between them (a commit is one saved change). These rules aren't a theory. They're what I wrote down after the same things went wrong on me more than once.

One instruction file grew to 1,512 lines when its own rule said 200, and nothing objected on its own, so it ended up skipped more than followed. A rule kept pointing at a program I had renamed, because nothing checks a rule against the project it describes. Rules I couldn't justify got argued with and worked around, fairly, since I'd written the instruction and not the reason. And what one session learned stayed in notes on my machine, where no one else could see them.

None of that was Claude Code failing me. It gave me the places to put rules, and hooks, small programs that run just before an action and can stop it. What it does not do on its own is take a view on what my rules should say, or read them back and tell me which ones had quietly stopped being true. So I wrote both. The five projects run on these rules now, and so does the package itself.

If any of this sounds like your last month, I'd like to hear about it. Find me on LinkedIn or GitHub.

Getting started

These steps are written for a Mac. On Linux they are the same, except that you install the tools with your system's own installer rather than with Homebrew, the Mac installer described just below. On Windows, the Claude Code quickstart linked below covers your version.

What you need first

1. A terminal. On a Mac, open the Terminal app.
2. Homebrew, the tool that installs other tools on a Mac, installed once from https://brew.sh.
3. Three tools, installed with brew install git gh node. Git tracks your project's history, gh is the GitHub command line tool, and Node runs the checker. Node must be 22 or newer, which node --version confirms.
4. A GitHub account, signed in once with gh auth login.
5. Claude Code itself, installed by following the official quickstart at https://code.claude.com/docs/en/quickstart, which gives a one-line install command for Mac and Linux and the Windows equivalents. Then run claude and follow the prompts to sign in.

Install house-rules, once per machine. The first command below points Claude Code at the marketplace that publishes house-rules. A marketplace is a published list of add-ons and where to get them. The second installs it for your user account, so it is there in every project.

claude plugin marketplace add dubbl-a/house-rules
claude plugin install house-rules@house-rules --scope user

Set up one project. The project folder has to be a repository first, a folder Git is tracking: setup reads your project\'s default branch, and the checker only looks at files Git tracks, so a plain folder gives it nothing to read. If yours is not a repository yet, ask Claude Code to make it one and give it a home on GitHub. Then open a terminal in the project folder, start Claude Code by typing claude, and run:

/house-rules:bootstrap

It looks over the project, proposes a file called house.json naming which modules fit, and on your approval writes the rule files, the checker, the lock file, and a short index of the rules into your own copy, plus a starter block for your instruction file that you merge in by hand.

Check any time. From the top folder of the project:

node .house/check.mjs

It prints any findings and warnings, then a one-line summary counting them, so a clean run ends at zero findings. It is also a good command to add to CI, the service that runs a project's checks on every proposed change.

What to expect afterward

Updates arrive as a plan you approve. When the package changes, or when you change house.json, run /house-rules:sync inside the project. It prints what it would do and waits. Read it as you would any proposed update: take what you want, decline what you do not. Say the package wrote a file and keeps it in step, and you edited that file by hand. The update is never written over your edit. It is refused instead, and you are shown the difference.

When the checker reports something, there are three honest ways to settle it.

1. Fix the thing it found. A renamed script, a document pointing at a file that moved, a file grown too long: change it so the finding goes away. This covers most findings.
2. Write down that you are doing it differently. Record a deviation in house.json, a dated note of what you declined and why, which the checker reads back on every run. An exception with a reason attached is a decision; an exception with no reason is drift.
3. Send the change to the package. If a rule file itself needed editing, that edit belongs in the package rather than your copy: propose it there, then run /house-rules:sync, which writes the package's new version once you approve the plan; until then your hand-edited file is refused rather than overwritten.

Where to ask. The project's home on GitHub is https://github.com/dubbl-a/house-rules. Its issues page has a form for something broken, one for a rule you want changed, and one for a question, and the question form points you to the Discussions tab. These rules keep changing, and disagreement is the point rather than a problem.

Glossary

• Repository (repo). Your project's folder of files, plus the record of every change to it.
• Checkout. Your own copy of a repository, the one on your machine.
• Commit. One saved snapshot of a change, with a message saying what it was for.
• Pull request. A proposal to fold a separate line of work into the main one, opened so it can be reviewed first.
• Module. A themed set of rules on one subject, such as docs or testing, turned on or off as a group in house.json.
• Plugin. An add-on giving Claude Code extra skills and hooks.
• Skill. A set of instructions Claude Code follows when you type its name after a slash, such as /house-rules:sync.
• Branch. A separate line of work in a repository, made so a change can be worked on and reviewed apart from the main line.
• Marketplace. A published list of plugins and where to get them.
• Hook. A small program Claude Code runs just before an action, able to stop that action. The branch guard is one.
• Lock file. A record of how each managed file looked when it arrived.
• Fingerprint (hash). A short code calculated from a file's contents, which changes if the file does.
• Checker. The command node .house/check.mjs, which rereads your project's documents and the files the package manages and reports where they and the project have stopped matching.
• CI. A service that runs a project's checks on every proposed change, so a break is caught without anyone remembering to look.
• Eval. A test of behavior rather than code: a real task, plus a check of whether the rules held. The cases come in pairs, one where the rule should hold and one where it should not fire.
• Deviation. A dated note that this project declines a default, and why.
• Ratchet. A line ceiling that tightens when a file gets shorter, so a trimmed file cannot grow back.
• Anchor. The line under a rule naming what enforces it, or saying that nothing does.