Spec Tests Cured Architectural Drift: An Agent Fixed 637 Font Sizes in One Pass

There is a well-known experiment: you ask ChatGPT to make an exact copy of an image without changing anything, then repeat the process 101 times. By the end, a photo of Dwayne Johnson has turned into a cartoonish mess. Each individual step is almost faithful, but the cumulative result is something entirely different.

The same thing happens to code maintained by an AI agent. The author of the analysis calls it architectural drift. The frontend provides the clearest example: the typeface is defined and consistent everywhere, but each page uses its own font sizes, and the website’s overall style falls apart. The underlying principle applies to every area of development: the source of truth begins to diverge.

The truth is in the spec, not the code

The author does not read the code at all; he reviews only the specs. The reasoning is simple: the spec is the blueprint and the code is the manufactured part. You compare the part with the blueprint, not with another part. Two sources of truth create chaos.

All documentation lives in the docs directory at the project root. As of November 5, 2026, it contained 7,478 .md files across 11 levels of nesting. In 95.3% of directories there were no more than 7 files, and in 97.4% no more than 9. This follows the “7 plus or minus 2” rule, making it easier for both humans and agents to understand where things are. Agents write and read the specs, while a human views them in a convenient format through the admin panel.

For example, all typography rules are stored in a single typography.md file. It defines 22 roles, each with a font family, desktop and mobile size, weight, and color. An article paragraph, for instance, is Charis 21/30, while the base style is Inter 14/21. The entire site uses two font families and only the weights 400 and 700. The key rule is that no state may exist outside the registry: a new combination requires a new row approved by a verdict.

Enforce reading and verify deterministically

Specs alone work probabilistically: the agent may follow them, or it may not. That is why the system has two layers of protection.

The first is the AGENTS.md file. It states that, before starting a task, the agent must read the documentation in the relevant directory. If a cloud-cost audit is needed, it goes to the cloud directory and reviews every provider. According to the author, the rules remain unbroken in 9 out of 10 cases.

The second layer is spec tests for the “tenth case.” A test reads the tables in typography.md, builds the set of permitted size pairs, and scans the entire frontend. Any pair outside the spec fails the build and reports the file name and line number.

What the test uncovered

Until November 6, the test used a denylist of nine obsolete pairs. While preparing the article, the author discovered that the code contained about 150 pairs outside the spec. In a single pass, the agent brought 637 usages into compliance, added 4 missing rows to the spec, and rewrote the test to use an allowlist. This is the main practical lesson: a denylist catches only what you already know about; an allowlist catches everything else.

If the docs and code still diverge, the escalation order helps: tests first, then self-healing in production—the author promises a separate article on that—and only then a human. The human’s job is not to catch the bug, but to understand why it slipped through and close that gap.

Limitations and conclusion

The approach requires discipline: thousands of documents must be kept consistent, and the author’s examples mostly concern typography, where verification is straightforward. Writing spec tests for business logic is harder. This is the experience of a single project, the figures are self-reported, and the poll beneath the article received one vote.

The practical takeaway for teams working with agents is to move rules into machine-readable specs, require agents through AGENTS.md to read them before each task, and turn the most common deviations into allowlist-based tests. The author published the framework itself—AGENTS.md, CLAUDE.md, and a code-free docs directory—on GitHub, so teams can start with a ready-made template.