How to Read the House Rules

Who this is for — anyone about to write or review Go, Zig, Bash, or Make in these repositories, human or agent.

Read this if — you want to know why the subset is drawn where it is.
Skip this if — you just need the rules; go straight to Go, Zig, Bash, or Make.

Takeaways

1. These four pages are reference material, not narrative. They are meant to be grepped, not read.
2. The subset is chosen for one property: whether a reviewer — or a check — can tell right from wrong quickly.
3. A rule that no command can enforce is a preference. It is allowed here, but it is labelled as such by living in prose rather than in make preflight.

Why a Subset At All

“The Good Parts” is Crockford’s phrase, and borrowing it sets an expectation: that somebody argued for a subset, rather than merely listing a house style. So here is the argument, in one paragraph, before the lists start.

Every language feature has a cost that is invisible when you write it and obvious when someone else reads it. In a fleet maintained by one person and a rotating cast of models with no memory, reading is the dominant cost. A package-level mutable variable in Go costs nothing to type and costs a future session an hour of tracing hidden coupling. A [[ ]] test in Bash works perfectly until the script runs under sh on a machine you did not configure. A clever @compileError-driven abstraction in Zig is a delight to write and an obstacle to every subsequent change.

So the subset is drawn by one criterion, and it is not elegance:

Keep the constructs whose correctness a cold reader — or a check — can establish locally. Drop the constructs that require holding the rest of the program in your head.

That criterion explains every rule in the four pages that follow. Explicit allocators in Zig, explicit dependencies in Go, test instead of [[ ]] in Bash, self-documenting targets in Make — each one trades a little writing convenience for a large amount of reading certainty. It is the same trade the rest of this book makes everywhere else: pay up front, in the harness, so that nobody has to remember anything later.

What These Pages Are Not

They are not tutorials, and they are not comprehensive. They are the accumulated residue of real bugs in emojig, cati, and this repository — the rules that were paid for. Where a rule is pinned to a specific toolchain version, it says so at the top of the page; see Zig — House Rules, which is the most perishable of the four.

Enforcement

The second row is the honest one: those rules are enforced by attention, not by a command. That is exactly why they are written down in one place a cold session can read in thirty seconds.