Ratchet Development is a governed approach to AI-assisted software development in which verified failures can become durable controls that future work inherits.
It becomes overengineering when the control grows larger than the lesson, or when it increases future context more than it reduces future risk. The answer is proportionality: prove the incident, diagnose the cause, place the smallest useful control at the owning layer, and stop when the work is complete.
I have overengineered Ratchet Development.
I tried to automate too much. The result was more complexity and less clarity.
Ratchet Governed Agentic Development asks how meaningful failures can become regression tests, contracts, permission boundaries, constraints, provenance requirements, or approval gates. That instinct has made my work more reliable, but it can become its own failure mode.
Not every mistake deserves a global rule. If every defect creates another gate and every uncertain edge becomes infrastructure, the system stops learning proportionately. It begins collecting ceremony.
A useful ratchet should reduce what work has to remember, explain, and reinterpret. When a control increases future context more than it reduces future risk, it has started working against the method it was supposed to strengthen.
A ratchet can encode the wrong lesson
A permanent control is only useful when the diagnosis behind it is correct.
The Client Operating Manifest in Marketing OS had a required Service Scope section. That section could contain truthful narrative boundaries about what a client was receiving, even when a separate database record containing machine-readable service roles did not yet exist.
My review prompt collapsed those two things. It told Claude that when the machine-readable scope_reference was absent, the entire Service Scope section should be treated as missing.
Claude implemented that premise. The tests implemented it too. A valid manifest containing real narrative scope but no separate scope row returned blocked_missing_context.
The premise was wrong.
The narrative scope belonged to the manifest. The service-role row was separate machine-owned authority. The correction was to ask two different questions: Does the manifest contain meaningful scope? And does this consumer require the canonical service record or roles?
The system had become stricter, but not more truthful.
A similar failure appeared in my first materiality rule for evidence-bound claims. The early heuristic treated nearly any number as a factual figure requiring an evidence receipt. A label such as “Q3” could be handled like a percentage, revenue figure, or measured result, even though it identifies a period rather than asserting a metric.
The control followed its instruction. The rule was too broad.
These failures changed how I think about the Ratchet Loop. Diagnose has to come before Encode because a bad ratchet does not merely waste time. It can make the system confidently wrong.
Calibration has a lower bound
The danger of overengineering does not mean fewer controls are always better.
Early in the Marketing OS rebuild, the foundation had 35 passing tests. I then ran an adversarial review using 98 agents and roughly 4.4 million subagent tokens.
It found two serious fail-open paths.
A deactivated user could still waive a failed gate and release an artifact. The system validated active actors in several privileged services, but it had missed two of the most consequential ones.
Denial records could also disappear. A request would refuse an action, but the surrounding transaction rolled back the event and audit rows along with the denied mutation. The system claimed refusals always left evidence while the actual HTTP path could erase it.
Those were consequential failures the environment could neither prevent nor reliably expose. Active-actor validation was hardened, refusal records were made durable, and negative tests made the original behavior permanently unacceptable.
That review earned its cost.
The lower bound is a verified consequential failure the environment cannot reliably detect, contain, or prevent. Choosing not to encode that lesson would be under-ratcheting.
Rigor also has an upper bound
The 98-agent review did not prove that every future change required 98 agents.
By the next major review, the fleet had been reduced to 20 agents and roughly 912,000 tokens. Later work used smaller targeted reviews, deliberate self-review passes, and test sets chosen according to the surface and risk being changed.
I stopped treating review size as a ritual.
A documentation correction may need a parser check and a close read. A route may need focused tests and a browser pass. A permission, migration, generation, or release change deserves wider proof because its failure can travel farther.
The distinction is consequence, reversibility, and how much of the system could inherit the mistake.
Independent critique still matters, which is why I separate production implementation from review. Maximum review is not proportionate review.
The upper bound is reached when the cost, reach, or complexity of the control exceeds the failure it is supposed to contain.
Governance should reduce future context requirements
Overengineering does not only happen in code.
My documentation system became its own warning. Decisions, running notes, memory, current-state summaries, trackers, and roadmaps all served legitimate purposes. Over time, the same facts began appearing in several layers. Running notes exceeded 51,000 words. Memory reached roughly 24,500. A correction in one place could leave a stale version somewhere else.
The system designed to preserve context was making future sessions carry more of it. The correction was not to delete history, but to establish one fact, one owner.
Decisions own architectural law. Running notes own a reconstructable evidence record, not a transcript of every command. Memory owns only what a fresh session would otherwise get materially wrong. Current State owns concise current truth. Trackers and roadmaps remain projections rather than authorities.
The governing principle became:
Documentation must reduce future context requirements.
That principle applies beyond documentation. A regression test should mean the architect no longer has to remember an old failure manually. A database constraint should mean each caller does not reinterpret the same invariant. A canonical source should eliminate reconciliation among several copies of one fact.
A useful control reduces future memory, explanation, vigilance, or interpretation. A control that adds more context than it removes risk is no longer strengthening the environment.
Build the doorframe, not the framework
One of the clearest instructions I gave during the build was:
Keep this small, the minimum doorframe.
The system needed a shared seam so future pipelines could use the same clients, permissions, evidence, audit, approvals, artifacts, and events without creating their own miniature operating systems.
That seam was necessary. A plugin framework was not.
The result was limited to an in-process registry, a common start guard, and client-scoped enablement. AI can make more architecture sound reasonable almost indefinitely, but the question is whether the next real workflow needs it.
Many future pipelines were defined while only a few were startable. The seam was not a mistake. It was a reminder that architectural breadth is not operational adoption.
I now try to build the smallest seam the next real use case requires, then let observed behavior earn the next layer.
My test before adding another control
I use five tests.
1. Evidence
Did the failure occur, or is the control responding only to a possibility? Severe theoretical risks can matter, but possibility alone does not justify a global mechanism.
2. Diagnosis
Do valid, invalid, and adjacent-valid cases support the explanation? The control should address the failure without rejecting a truthful neighboring case.
3. Ownership
Does the control live at the layer that owns the problem? Database state may need a constraint, authorization belongs in permissions, and a narrow defect may need one regression test.
4. Proportion
Is this the smallest control that reliably contains or surfaces the failure? The goal is enough enforcement for its consequence and reach.
5. Inheritance
Will the control reduce what future work has to remember, explain, reinterpret, or monitor manually?
This is the final test because Ratchet Development is about the environment future work inherits.
The task still needs explicit scope and a stop condition. A correction should not quietly authorize the next feature or broader architecture. Once the failure is addressed and the acceptance criteria are met, the next idea belongs in a later decision.
A stronger environment, not a heavier one
Ratchet Development is not maximum governance.
Some failures earn a shared guard, a database constraint, or a broad adversarial review. Others earn one narrow test. Some do not earn a durable control at all.
The difference is what happened, what allowed it to survive, where the problem belongs, and what future work should no longer have to carry.
A useful ratchet should make the next task easier to reason about. It should reduce what the architect remembers, what the agent reinterprets, and how much context must be reconstructed.
The goal is not to leave every future task surrounded by more process.
It is to leave it with less uncertainty.
The next task should inherit a stronger environment, not a heavier one.
Continue Reading: The Architect’s Trance