AI Zero-Knowledge Iteration: Constrain First, Automate Second

AI can produce working code remarkably quickly. That is not the difficult part.

The difficult part is producing the tenth feature without discovering that the first nine quietly created nine different architectures.

This is the failure mode behind much of today’s agentic development. One agent introduces a useful convention. The next invents another. A third adds an abstraction to reconcile both. Every change works locally, but the system becomes harder to explain, test, and extend globally. Code generation scales output; without constraints, it also scales inconsistency.

At Loomaic, we have been developing a different operating model: AI Zero-Knowledge Iteration. This is our name for a repository-grounded workflow; it is unrelated to cryptographic zero-knowledge. We first build a strongly constrained framework that contains the system’s architectural judgment. We then ask agents to implement routine product work inside that framework. Changes that expand or modify the framework receive human architectural review.

After the framework stabilizes, our target is simple:

• At least 90% of routine change requests should fit existing, pre-approved extension paths.
• The 10% or less that alter shared invariants should enter human architectural review.

The exact ratio is not a quota, an SLA, or a safety claim. It is a diagnostic target. Ordinary product, code, and security review can still apply to either class. If routine work repeatedly requires substrate changes, either the product is still in architectural discovery or the framework is not doing enough.

Broad research goes in. A predictable path for each common change class comes out. On smaller screens, swipe diagrams horizontally.

What “zero-knowledge” means here

“Zero-knowledge” does not mean context-free development. The agent receives the repository, the task, the declared toolchain, and the verification environment.

It means a capable agent can start with those artifacts, discover where a routine change belongs, produce a conforming implementation, verify it, and recognize when human review is required—without relying on private chat history or unwritten institutional knowledge.

The agent does not work without context. The important context has been compressed into durable artifacts:

• module boundaries and typed contracts;
• reference implementations and scaffolds;
• executable architecture checks;
• tests and acceptance criteria;
• versioned development guidelines;
• explicit escalation rules.

This gives us a practical test:

If a fresh agent needs an experienced engineer to explain the repository orally before it can make a routine change, too much architecture still lives in people’s heads.

The objective is not to make AI choose the architecture repeatedly. Humans define the decision space. Agents operate inside it.

The central idea: reduce degrees of freedom

Most attempts to improve agent reliability add more instructions to the prompt. That can help, but it has a ceiling. A long prompt still asks the model to reinterpret the architecture on every task.

We prefer to change the environment in which the agent operates.

We call that environment the constraint envelope: the set of legal shapes a change may take without additional architectural approval. It describes:

• where a feature may live;
• which dependencies it may use;
• which direction dependencies may flow;
• how state and data are owned;
• how authorization and validation are performed;
• how failures are represented and observed;
• which tests and contracts must pass;
• which surfaces are forbidden;
• when the agent must stop and escalate.

A strong envelope does more than describe the correct path. It makes that path the easiest one to take.

Directory conventions help, but generators are stronger. Written dependency rules help, but import checks are stronger. A sentence about authorization helps, but a shared policy boundary with contract tests is stronger. The closer a rule is to executable feedback, the less room remains for accidental interpretation.

A rule without a reliable verification path is guidance, not an enforceable constraint.

Phase 1: distill the ecosystem before designing the framework

The first step is not code generation. It is ecosystem distillation.

Before defining our own architecture, we study several relevant open-source systems. We do not look only at their current code or polished documentation. The highest-value material often lives in:

• long-running issue threads;
• migration guides and breaking changes;
• reverted or deprecated designs;
• repeated contributor mistakes;
• security advisories;
• operational incidents;
• maintainer discussions about rejected alternatives.

A mature issue tracker contains years of compressed architectural tuition. It shows which apparently elegant choices became expensive under real use, which extension points survived, and which abstractions forced painful migrations.

The output of this phase is not a copied architecture. It is a small ledger of invariants:

Invariant	Failure it prevents	Enforcement	Reconsider when
Domain modules cannot import adapters directly	Business logic becomes coupled to vendors	Import rule and CI check	A new integration model is approved
Authorization happens at the application boundary	Internal calls bypass access control	Shared policy wrapper and contract tests	The trust model changes
Schema changes require reversible migrations	Deployments cannot roll back safely	Migration test and deployment gate	Storage strategy changes

Every borrowed pattern needs a local reason. Popularity is not evidence that a pattern fits our trust model, scale, team, or product. Record sources, then verify and comply with applicable license terms whenever code, tests, documentation, or other protected material is reused. Study architectural ideas, but do not confuse inspiration with permission to copy an implementation.

This phase lets us pay for other teams’ lessons with attention rather than incidents.

Phase 2: front-load decisions with a large blast radius

Not every decision deserves equal attention at the beginning.

We front-load decisions that are expensive to reverse or capable of affecting the whole system:

• trust, authentication, and authorization boundaries;
• tenant and ownership models;
• domain and module boundaries;
• dependency direction;
• state and concurrency models;
• data ownership and migration semantics;
• public and external contracts;
• failure behavior and observability;
• deployment topology and rollback mechanics.

We treat these decisions as testable hypotheses, not permanent truths. Small technical spikes expose weak assumptions; short architecture records state the evidence, enforcement, and trigger for reconsideration. We deliberately defer low-cost product decisions. The principle is:

Decide irreversible things early; preserve optionality everywhere else.

Each high-impact decision becomes a short architecture record linked to a concrete enforcement mechanism. A decision that exists only in a document will eventually drift. A decision represented by a public interface, package boundary, scaffold, test, or CI rule can remain visible during every iteration.

The result is an architecture contract. It does not predict every future feature. It establishes the invariants that future features must preserve until evidence warrants a deliberate change.

Phase 3: build an obvious path for each common change

Once the architecture contract is clear, we build one supported implementation path for each recurring class of work. A UI feature, a background workflow, and an external adapter may need different paths; the point is that each class has a clear default.

A useful golden path usually includes:

• a canonical feature or module scaffold;
• typed input and output contracts;
• standard adapters for external systems;
• shared authorization and validation;
• stable fixtures and test harnesses;
• consistent telemetry and error handling;
• feature flags and rollback mechanisms;
• at least one complete reference feature.

This is the point at which architecture becomes leverage. Instead of asking an agent to invent a module shape, error policy, integration boundary, and testing strategy for each feature, we ask it to fill well-designed extension points.

The aim is not “the agent may write anything as long as the tests pass.” It is:

The agent selects from a small number of supported implementation shapes, while known invalid shapes are blocked or surfaced early.

Good constraints remove accidental creativity while preserving product creativity. The agent can still solve the customer problem in many ways; it should not invent a new deployment model to do so.

The 90/10 split is a routing target, not a code quota.

Phase 4: iterate with the minimum-chaos principle

After the framework exists, we implement through minimum-chaos iterations:

Each iteration introduces the smallest reversible change that creates an observable product or risk-reduction outcome while preserving existing contracts.

An iteration has one narrow acceptance target and one primary boundary. It should be easy to explain, verify, bisect, and revert. We avoid opportunistic refactors and speculative abstractions, especially when they are bundled with product work.

The most important rule is that we avoid changing all three of these in one undifferentiated step:

1. the feature’s intended behavior;
2. the framework rules governing the feature;
3. the infrastructure primitives beneath it.

Mixing all three obscures the causal link between intent, implementation, and outcome. When coordinated change is unavoidable—for example, during a migration—we sequence it explicitly, add observability and rollback points, and route it through human review.

Our loop is intentionally small:

1. State one observable outcome.
2. Classify the work as feature-layer or substrate-layer.
3. Locate the sanctioned extension point.
4. Implement the smallest conforming delta.
5. Verify product behavior and system invariants.
6. Keep the change, revert it, or propose a focused framework improvement.
7. Repeat.

The task package supports this loop with one product goal, observable acceptance criteria, allowed extension points, forbidden surfaces, relevant guideline links, required verification commands, and a clear escalation condition. After implementation, the agent inspects its own diff for boundary expansion before submitting or escalating.

Small diffs preserve the causal link between intent, implementation, and outcome.

This process may appear slower than asking an agent for a large rewrite. Its design goal is to reduce repair loops, review ambiguity, and architectural cleanup. The relevant productivity metric is not lines of generated code. It is validated product changes per minute of human attention.

Phase 5: keep the repository guideline fresh

The repository’s development guideline describes the framework from the perspective of the next contributor—human or AI.

For agentic development, freshness is not editorial polish. A stale guideline creates two architectures:

• the architecture the code actually implements;
• the architecture the agent believes it should implement.

When a human approves a substrate change, the same change set should update:

1. the implementation;
2. the scaffold or reference example;
3. the automated enforcement;
4. the guideline;
5. the architecture record, when the decision changed.

The guideline should live close to the code, remain concise enough to retrieve reliably, and link to canonical examples. Every important rule should contain four elements:

• Rule: what must be true;
• Rationale: which failure it prevents;
• Example: the preferred implementation shape;
• Check: how a contributor knows it still holds.

If the guideline lags behind the architecture, autonomous iteration pauses.

We also periodically run a freshness test: give a capable agent a representative task from a clean checkout. If it chooses the wrong boundary or needs oral clarification, we improve the repository before increasing autonomy.

The 90/10 operating boundary

The framework creates two change zones. Here, substrate means the shared architecture, runtime, data semantics, security boundaries, and build, deployment, and observability systems. Infrastructure is one subset of the substrate.

Feature zone: autonomous by default

A feature-zone change:

• uses established module shapes and contracts;
• stays within approved dependencies;
• uses existing state, data, and authorization patterns;
• does not alter shared runtime behavior;
• passes product, contract, architecture, and security checks.

Typical examples include UI, workflows, domain features, adapters that implement an existing interface, tests, and integrations through approved extension points.

Substrate zone: human architectural review

A substrate-zone change:

• changes a shared interface or dependency direction;
• introduces infrastructure or runtime dependencies;
• changes schemas or migration semantics;
• touches trust boundaries, secrets, billing, or tenancy;
• changes build, deployment, observability, or rollback behavior;
• creates an architectural exception or weakens a constraint.

These changes are not wrong. They simply expand the system’s decision space, so a human must evaluate their assumptions, blast radius, migration path, and rollback mechanics.

The review trigger is therefore not diff size. A two-line authorization bypass can carry more architectural risk than a thousand-line feature implemented inside a safe module.

Our stop rule is explicit:

When an agent cannot complete a task without weakening a constraint, it must stop and propose a framework change instead of silently creating an exception.

Normal organizational review policies may still apply to feature work. The 90/10 model concentrates mandatory architectural review at the substrate boundary; it does not make all other code risk-free.

Failure modes to watch

Constraint theater

The architecture is described in Markdown, but nothing detects violations. Convert repeated review comments into types, scaffolds, tests, or CI checks.

Prompt accretion

Every agent failure adds another paragraph to a global prompt. Fix the extension point or enforcement mechanism when the failure is architectural.

The golden cage

The framework is so rigid that legitimate product work constantly needs exceptions. Constraints should protect invariants, not freeze product evolution.

Infrastructure smuggling

A local-looking feature quietly adds a dependency, changes a schema, bypasses authorization, or alters deployment behavior. Classification and diff inspection must look for boundary changes, not only filenames.

A stale guideline

The framework evolved, but its examples and instructions did not. Treat guideline updates as part of the substrate change’s definition of done.

Cargo-cult distillation

The team copies a pattern from a respected project without preserving its assumptions or trade-offs. Record the local reason for every adopted invariant.

Large-batch autonomy

The agent receives a broad outcome and returns a multi-system rewrite. Divide work until each change has one observable target and a reversible path.

Human rubber-stamping

The review gate exists, but reviewers approve substrate changes without examining invariants, migration, failure behavior, or rollback. Human review must protect the architecture, not merely acknowledge the diff.

Measure the framework, not the agent’s confidence

Over a rolling window of merged change requests, we monitor signals that reveal whether the environment is producing bounded autonomy:

• Framework conformance ratio: changes using sanctioned extension points;
• Substrate change rate: changes requiring architectural review;
• Escape-hatch rate: exceptions, suppressions, or rule bypasses;
• First-pass verification rate: changes passing all checks without repair;
• Guideline update lag: time between a framework change and its instruction/check updates;
• Rollback time: time required to reverse a change safely;
• Human attention per accepted change: the scarce resource we actually want to reduce;
• Architectural drift findings: violations discovered after merge.

These are signals for investigation, not targets to optimize mechanically. A temporary rise in substrate changes may reflect legitimate product discovery rather than failure. A suspiciously perfect conformance rate may hide misclassification. The point is to expose framework quality, not game the ratio.

An adoption playbook

You do not need to redesign an entire codebase before trying this workflow.

Start with one common vertical slice:

1. Choose a recurring feature type with clear customer value.
2. Mine comparable systems for recurring failures and migrations.
3. Record the small set of invariants that matter locally.
4. Create one reference implementation.
5. Extract its scaffold, contracts, fixtures, and checks.
6. Define the feature/substrate review boundary.
7. Give a fresh agent a similar task from a clean checkout.
8. Turn every unnecessary question or invalid attempt into a framework improvement.
9. Repeat until routine work consistently stays inside the envelope.

Only then expand the model to another feature class. The framework should grow from observed needs, not from an attempt to predict the entire future.

Best-practice checklist

Before implementation:

• Study multiple relevant open-source systems.
• Mine issues, migrations, and reversals—not only happy-path code.
• Record invariants and the failures they prevent.
• Decide high-blast-radius trust, data, state, module, API, observability, and deployment boundaries.
• Define feature-zone and substrate-zone criteria.

When building the framework:

• Provide a canonical scaffold and at least one reference feature.
• Encode dependency rules and public contracts.
• Standardize authorization, validation, failures, telemetry, and tests.
• Make invalid shapes fail locally and in CI.
• Provide a deliberate, visible, human-approved, and time-bounded escape hatch.
• Require migration and rollback semantics for substrate changes.

For each agent iteration:

• State one narrow acceptance target.
• Classify the change before editing.
• Use an existing extension point.
• Make one reversible change.
• Avoid opportunistic refactors.
• Run product, contract, architecture, and security checks.
• Inspect for hidden substrate changes.
• Escalate instead of bypassing a constraint.

After a human-approved framework change:

• Update code, scaffolding, checks, guidelines, and decision records together.
• Add a regression case for the condition that forced the change.
• Verify that the next agent can use the new path without oral context.
• Remove obsolete rules and temporary exceptions.

The outcome: controlled autonomy

The goal is not unrestricted agent autonomy. It is a system in which routine changes follow well-lit paths, known boundary violations become harder to introduce and easier to detect, and architectural expansion remains a deliberate human decision.

AI Zero-Knowledge Iteration is our current operating model for moving toward that goal. Agents provide throughput. The framework preserves coherence. Humans remain responsible for expanding the system’s decision space.