architectural-invariants

Architectural invariants — the design pattern of enforcing strict boundaries and predictable structure mechanically, via linters and structural tests, rather than through review or convention. Per 2026-04-27-harness-engineering-codex-agent-first: agents thrive on predictable structure, so the architectural rigor that’s typically deferred until hundreds of engineers becomes an early prerequisite for agentic codebases. By enforcing invariants — not micromanaging implementation — the agent can move fast without eroding the foundation.

The wiki’s earlier reference to this idea is 2026-04-27-agent-principles-architecture-engineering (Tw93’s “Agent” essay), which cites Andrew Ng’s parse-don’t-validate and the logic.inc AI is forcing us to write good code post; this page is anchored on those plus the OpenAI codex team’s specific implementation.

The shape — domain-bounded layering

From 2026-04-27-harness-engineering-codex-agent-first, each business domain inside the codebase obeys a fixed dependency layering:

Types → Config → Repo → Service → Runtime → UI

Code may only depend “forward” through that sequence. Cross-cutting concerns — auth, connectors, telemetry, feature flags — enter through a single explicit interface called Providers. Anything else is disallowed and enforced automatically.

The author’s framing of the implication:

这种架构通常要等到你拥有数百名工程师时才会推迟。对于编码智能体来说，这是一个早期的先决条件：有了约束，速度才不会下降，架构才不会漂移。

(This kind of architecture is normally deferred until you have hundreds of engineers. For coding agents, it’s an early prerequisite: with constraints in place, speed doesn’t drop and the architecture doesn’t drift.)

Two layers of enforcement

That last detail is the operational kicker: lint error messages are written for the agent, not for a human reviewer. When the next Codex run hits the violation, the error tells it what to do. This collapses the loop “rule violated → human review → human writes fix” into “rule violated → agent reads fix instruction → agent applies it” — same mechanism as verifier-loop but with the verifier producing actionable feedback rather than just pass/fail.

What gets specified, what doesn’t

The post commits to a useful split: enforce the unchanging shape, leave the implementation free. Cited example:

• Specified. “Parse data shapes at boundaries” (citing Alexis King’s parse don’t validate).
• Not specified. Which library to use for the parsing. The model gravitates to Zod, but no specific library is mandated.

The general rule the post extracts:

你非常重视界限、正确性和可重复性。在这些边界内，你允许团队或智能体在解决方案的表达方式上拥有很大的自由。

(Care intensely about boundaries, correctness, and reproducibility. Within those boundaries, allow the team or agent significant freedom in how the solution is expressed.)

This is the same instinct large engineering platform organizations apply to humans: enforce edges centrally, allow autonomy locally. It scales unchanged to agents.

Why “premature” architecture isn’t premature

Conventional engineering wisdom — don’t over-architect; constraints emerge from running code — assumes the cost of imposing structure upfront is borne by humans, who slow down. With agents, the cost calculus inverts:

• For humans, rules feel pedantic. Each new constraint is friction at the keyboard.
• For agents, rules are multipliers. Once encoded, they apply everywhere instantly. “With agents, [these rules] become multipliers: once encoded, they apply everywhere instantly.”

So the right amount of architectural rigor for an agent-driven codebase is higher, not lower, than for an equivalent human team — and it should arrive earlier in the codebase’s life. 2026-04-27-harness-engineering-codex-agent-first reports this as a learned lesson: early progress was slower than expected, not because codex couldn’t do the work, but because the environment was under-specified.

Relation to other concepts

• verifier-loop is the more general framing — invariants are one kind of acceptance criterion. This page focuses specifically on architectural invariants enforced by custom lints, with the distinguishing detail that error messages double as fix instructions.
• claude-hooks is the claude-code mechanism that plays the same role at session-time (deterministic enforcement before / after specific events). The OpenAI team’s “custom lints + structural tests” are CI-time; Hooks are turn-time. Different placement, same instinct.
• harness is the umbrella; invariants are the acceptance baseline + execution boundary parts.
• agent-legibility: invariants make the codebase legible because the agent can rely on the structure being what the structure claims. Invariants without legibility are bureaucracy; legibility without invariants is documentation that drifts.
• entropy-and-garbage-collection: invariants alone don’t catch drift inside what they don’t constrain. The cleanup loop covers the gap; invariants cover the foundations.

Open questions

• The exhaustive list of “taste invariants” the OpenAI team enforces isn’t fully enumerated in the source — only structured logging, naming conventions, file size limits, and platform reliability requirements are named. A more complete inventory from a future OpenAI publication would be useful for adapting the pattern.
• The cost / payoff curve of building Codex-written linters isn’t reported. The post implies it pays back, but doesn’t quantify against the cost of writing the linter rules.
• Whether the Types→Config→Repo→Service→Runtime→UI layering is a generic recommendation or a property of this specific application is unclear. Probably the latter; the underlying principle (fixed forward-only layering with a single cross-cutting interface) generalizes.