Architecture rules

Workspace → Architecture Rules.

Madebook learns the technical patterns already used in your codebase and turns them into rules every agent must follow. If an agent tries to introduce a conflicting approach, Madebook flags it before the change moves forward.

The page explains why it exists, and the sentence is worth quoting:

The fastest way an AI-assisted codebase rots is a second way of doing something: one agent uses React Query, the next reaches for Redux, and six months later both are load-bearing.

Rules are derived, never written

There is no "new rule" button. The only way a rule comes into existence is Derive from the repository, which runs a deterministic analyser over the indexed code — no model involved.

It matches dependency names against known signatures, then falls back to directory and file patterns for categories no manifest answers.

There are 14 categories: Frontend state, Authentication, Data access, Validation, Logging, HTTP client, Testing, End-to-end testing, Styling, Secrets, Background jobs, API style, Dependency injection, Migrations.

Confidence

Source	Confidence
A human edited the ruling	100
A manifest, with two or more pieces of evidence	95
A manifest, with one	85
A file pattern	40 + 6 per hit, capped at 85
Fallback	50

A file pattern needs at least two pieces of evidence to produce a rule at all.

Two answers means no rule

This is the most important behaviour on the page. When more than one candidate matches a category, the deriver emits no rule and a note instead:

Frontend state: Redux and React Query are both present. No rule derived — the codebase has not settled this, and inventing a winner would make one half of the existing code a deviation.

Draft, approved, superseded

A derived constitution is a draft. A draft is advisory: nothing is enforced, no deviation is raised, and every agent brief labels the rules "draft — not yet approved."

Approving it is the human step. It stamps who approved it and when, marks every previous version superseded, and from that moment the rules are enforced. Approval needs constitution.amend — owner or organization admin.

A constitution with no rules cannot be approved:

There is nothing to approve — this constitution has no rules.

Re-deriving over an approved constitution

The new draft lands beside the approved one, not over it. The approved version stays in force until a lead approves the draft, which then supersedes it. There is at most one pending draft per workspace, and the setup checklist says so: "A newer draft (v{n}) awaits review."

A draft is also derived automatically after every analysis of a commit nobody has looked at.

Editing a rule

Two things a lead can change, both requiring constitution.amend:

• Edit the ruling or the rationale. Editing a ruling forces the rule's source to human and its confidence to 100 — you said so, and that is the strongest evidence there is.
• Make it advisory. A shield icon toggles enforcement. Tooltips: "Enforced — click to make advisory" and "Advisory — click to enforce." This is the opt-out for a category where the code genuinely has two answers.

A rule can also be removed with the trash icon, tooltipped "The deriver got this wrong." The interface offers this only while the constitution is a draft.

Deviations

A deviation is raised when a session reports a change that departs from an enforced rule of an approved constitution. A draft raises nothing at all.

Two deterministic detectors:

1. A dependency was added that matches a rule's conflict list. Matching is exact first, then bidirectional substring — so @reduxjs/toolkit matches a redux conflict.
2. A path names a conflicting technology. A conservative regex over the file path only: redux, mobx, recoil, zustand, jotai, graphql, apollo, axios, dapper, nhibernate, serilog, nlog, winston, pino. It fires only on unambiguous naming.

At most one deviation per rule per change set, and none at all when an open one already exists for the same pair.

Each deviation carries the agent's own rationale, verbatim, so you can see what it thought it was doing.

The 70% line

The rule's confidence decides how hard the deviation lands.

Condition	What the agent is told	What lands in the queue
Confidence 70 or above and enforced	REMEDIATE — "{observed} departs from this workspace's approach. Use {ruling} — {rationale}." and the evidence path is added to its blocked scope	decide, urgency 78
Below 70, or advisory	CONTINUE_WITH_WARNING — "{observed} may depart from this workspace's approach ({ruling}, inferred with {n}% confidence — advisory)."	inform, urgency 40

A rule Madebook inferred with low confidence is not something to hold an agent to as if it were law.

A deviation also adds a risk factor — 15 points each, capped at 30 — and shows up in the review capsule as a new_pattern inspection at high severity:

Introduces {observed}, which departs from what this codebase already does. Worth a decision rather than an accident.

Resolving one

The dialog is headed Architecture deviation with the fact stated plainly: "{observed} departs from {ruling}." Three outcomes.

Button	What it records	Who can
Use the existing pattern	The deviation is closed as use_existing.	Anyone who can read the constitution
Dismiss	Closed as dismissed.	Anyone who can read the constitution
Approve the exception	See below.	constitution.amend — owner or admin

Approving an exception amends the constitution in place. The rule's ruling becomes "{previous} and {observed}", the rationale gains a line recording your note, the rule becomes human-sourced at 100% confidence, and the constitution's version is incremented in place.

Resolved from the Architecture Rules page, it also writes a decision into the ledger — titled "{observed} is permitted alongside {previous}" — so every future session is told about it before it asks.

Note. Approving the same exception from the attention queue marks the deviation but does not write that follow-on decision. If the exception is one future agents should know about, resolve it from the Architecture Rules page.

The Why field is required by the dialog before you can approve, with a hint that says why:

an approved exception becomes a decision every future session is told about

Its placeholder is a good model for the kind of answer that helps:

Redux is allowed for the multi-step form only; everything else stays on React Query.

Where the rules show up

• In every brief, as a section that is never truncated by the context budget. Every rule with its ruling, rationale, confidence, whether it is enforced, and its do-not-use list.
• In context health. A session briefed on an older constitution version loses 35 points per version of drift. A session that was never briefed on one scores zero on that dimension, with the reason "The session was never told what this codebase has already decided."
• In the mission contract generator, which turns every enforced rule with a conflict list into a forbidden clause.

Related

• Decisions
• The brief
• The execution protocol