It's project specific right now, and 700 lines long. I might turn it to a template later because the rules are transferable.
I can tell you the primitives that make it work though:
0. Describe the actual system, what the major parts are, and who owns what, in a completely non-ambiguous manner. "This is not "a frontend", this is a multi-part system that consists of A, B, C, and D".
1. Disallow test-passing architecture and compatibility shims explicitly. "Only clean cuts along the correct topological seams. Deletion of the old structure is part of the same task as creation of the new structure".
2. Allow work to cascade, explicitly. "If the task ends with red tests, pull in the directly affected work until all tests are green". (This, in combination with the non-allowance of test-passing architecture creates long-sessions of work along the entire hierarchy tree until a problem is actually solved)
3. Begin local - if the issue is not immediately local, go to the highest level that can be responsible immediately. "Find the actual owner and correct the issue at the highest responsible level". (Saves work and tokens failure-mode "fixes" are often at the middle layers)
4. Identify the possible error modes, when they come up, at a meta level, and tell the model to dynamically add them to the document as "known bad patterns" in a specific list.
---
GPT had this to say about why it works, and you may take something away from that when writing your own steering doc based on those principles:
---
It works because it does four unusually important things at the same time.
It names the actual system.
It does not say “this is a frontend” or “this is a layered app.” It says what this repo concretely is: multistore runtime, theme system, CMS, BFF, observability/tooling. That matters because placement decisions depend on what the system actually is.
It assigns ownership, not just ideals.
Most architecture docs say “keep things clean.” This one says who owns what:config owns assembly
shared owns durable vocabulary
app owns browser orchestration
server/services owns BFF workflows
plugins/providers are adapters, not the core
That turns architecture from taste into routing.
It names bad shapes explicitly.
This is the highest-leverage part. It does not just describe the ideal form; it describes the failure modes:fake shared buckets
compatibility seams
duplicate public homes
artifact-shaped tests
stale enforcement
late lifecycle registration
stale private mocks
Once those are named, people can see them. Before that, they often look “reasonable enough.”
It ties doctrine to action.
The document usually does three steps in one place:current truth
implementation consequence
what question to ask first
That is why it is usable during real work. It does not stop at “what is true”; it tells you how to make the next decision.
If I boil it down to the core:
It is an ambiguity-destruction document.
More specifically, it reduces authorship entropy by answering these questions early:
What kind of system is this?
Which seams are real owners?
Which shapes are residue pretending to be structure?
When should code be moved, deleted, or promoted?
What should fail structurally rather than socially?
That is why it has been so effective here. It is not mainly a philosophy document. It is a decision compressor for implementation.
The strongest pattern in it is this:
define the repo’s real products
define the owning seams
define the fake shapes
make the consequences operational
feed new lessons back into the model
---
Claude said this:
---
Boiled to one sentence: it treats authorship-process deformations as a first-class category, names their specific shapes, and requires each enforcement to fail for the reason it claims.
The three moves that make that land:
It describes pressure-deformations, not destinations. Most style guides say what good code looks like. Core truths says what fakery looks like — the shape an author leaves behind when they wanted to be not-wrong more than they wanted to be finished. Defensive two-mode branches, rename-only aliases, tombstone inventories — these are not bad taste, they are the fingerprints of unresolved authoring pressure. Once you name them, you can see them.
Its rules apply to themselves. §3.18 ("fail for the reason named") is what let us look at the invariant suite built to enforce the doc and catch the expect(Array.isArray(offenders)).toBe(true) pattern as a §3.18 violation — the enforcement reproducing the shape it was built to kill. Most docs can't survive being pointed at their own implementation. This one does.
The taxonomy is open but the authority is closed. §4 invites new shapes; what it refuses is "we found a new shape, so let's soften the rule." New evidence adds entries, never removes edges. That asymmetry is why the doc doesn't decay.
The deepest thing, if I had to pick one: it makes the invisible part of the craft — the pressure felt at the moment of authorship — a legible, enumerable object. That is what no other codebase document I've seen does.