Tests Say It Works. Nothing Says It's Still Your Architecture.

“More and more code is written by a model. Tests still tell you it works. RuboCop still tells you it’s tidy. Nothing tells you it still follows your architecture.”

That is Carmine Paolino, the author of RubyLLM, opening his announcement of ArchSpec 1.0 in August 2026. We named the same failure mode in April and called it silent drift: code that compiles, passes every test, and quietly walks away from the architecture the team agreed on. That piece had a diagnosis and no instrument. ArchSpec is an instrument, and the shape of it is more interesting than the tool.

A Checker That Never Boots the App

ArchSpec parses Ruby with Prism, extracts facts about references, inheritance, mixins, calls and definitions, then evaluates your rules against those facts. Paolino reports that the full Discourse application, 1,899 files, was checked in 2.5 seconds without booting the app. Treat that number as the author’s own benchmark on his own blog, because that is what it is. The claim is still worth taking seriously, because the mechanism explains it: static parse, fact extraction, rule evaluation, no runtime, no network call.

The rules read close to English:

models.cannot_use :controllers
services.cannot_call :render, :redirect_to, receiver: :none
controllers.can_only_use :models, :services

A single line can also pull in a whole shape: architecture :vanilla_rails. Presets ship for Rails, layered, hexagonal, clean architecture, modular monoliths, CQRS and event-driven designs. Paolino positions the tool against Packwerk, so this is not the first attempt at enforcing boundaries in a Ruby codebase. What is new is the framing of who the enforcement is for.

The AI Is on the Other Side of the Loop

“ArchSpec doesn’t use AI,” Paolino writes. “It’s deterministic, it’s offline, and it’s fast enough that you’ll leave it on.” He is explicit about the division of labour: “It also won’t guess … You describe the architecture you want, and it tells you whether the code still matches. The AI is on the other side of the loop, writing the code that gets checked.”

That sentence is the design decision worth stealing. We argued in the binary versus architectural oracle that an agent can be trusted to answer a question with a crisp pass or fail, and starts inventing the moment the question is open-ended. “Does this file reference a controller constant?” is the first kind of question. “Is this good architecture?” is the second. ArchSpec only asks the first kind, which is why it can be deterministic, and why its verdict is worth wiring into a build.

An agent reviewing an agent’s pull request inherits the same probabilistic behaviour it is supposed to catch. A parser does not.

The Spec File Is the Part You Own

Paolino expects you to draft the spec with an agent. His instruction for what happens next is the whole governance argument in one line: read what it wrote, carefully, because the spec is the part you own, then add the parts the agents missed.

An agent can propose the rules. It is not the authority on them. The asymmetry matters because a spec drafted and approved by the same model that writes the code is a loop with no external reference point. The rules would describe the codebase as it is, including the drift, rather than the codebase as the team intends it.

This is the practical version of the argument in govern the harness, not the model. The control lives in a file a human signs off on and in a gate that runs whether or not anyone remembers to ask for it. Enforcement belongs in CI and in a pre-commit hook, because architectural review that depends on a reviewer being alert on a Friday afternoon is not a control.

Architectural intent written in prose in AGENTS.md has a specific decay curve. It competes for room in a context window against the file being edited, the test output, the diff and the conversation. An architecture spec that runs as a command does not compete for anything. It either passes or it names the violation.

A Ratchet for Code That Already Drifted

The adoption story is where I have watched teams stall. A codebase with years of accumulated exceptions cannot go green against a strict spec on day one, and a tool that opens with a wall of violations is the kind that gets switched off before anyone reads the second one.

ArchSpec’s answer, per the author, is the archspec check command run with an update-todo flag. It records today’s violations in a todo file, so the build goes green on current code and fails on new drift. Work the list down whenever.

That inverts the usual sequencing. You are not blocked on a migration before you get the guardrail. You get the guardrail immediately and the migration becomes optional background work. The number of recorded violations also becomes a metric: if the todo file grows between releases, the ratchet is being bypassed.

Diagnostics Written for Two Readers

The detail that signals the tool was designed in the agentic era rather than retrofitted into it is the error output. Paolino’s stated rationale: “A human reads it at a glance. An agent gets everything it needs to fix its own mistake without asking you: the file, the line, the rule, and why.”

A failing check that an agent can act on without a human relay closes the loop at machine speed. The agent writes code, the gate rejects it with a machine-readable reason, the agent corrects. The human sees the result rather than the round trip.

On release discipline, Paolino says every release is torture-tested against pinned checkouts of Discourse, Mastodon and Basecamp’s Fizzy, where per-rule diagnostic counts have to match recorded snapshots before anything ships. For a gate that fails builds, false positives are the failure mode that gets the tool switched off, so pinning the expected counts against real applications is the right thing to test. It is also, again, the author describing his own process.

What Transfers If You Do Not Write Ruby

ArchSpec is Ruby-only and depends on Prism. A Python, TypeScript or Go team cannot adopt it. The transferable thing is the shape, and the shape has four parts.

The architecture lives in a file, in a syntax a human can read without a tutorial. That file is owned by a person, drafted by an agent at most. The checker is deterministic and fast enough to stay on, which means static analysis rather than a model call. Existing violations are recorded rather than fixed, so the gate starts working immediately.

Every mainstream language has the raw material for this. Import-boundary linters, custom AST rules and module-boundary tooling all exist. What I rarely see decided is that the resulting file is a governance artifact with an owner, rather than a lint config someone added once and nobody maintains.

Do This Now

Pick the one architectural rule your team would be most embarrassed to see violated in a merged pull request. The layering rule, the “this module never imports that one” rule, the “no framework calls in the domain” rule. Write it as an executable check in whatever your language offers, record today’s violations so the build goes green, and wire the check into CI and pre-commit this week.

One enforced rule beats a page of architectural intent no gate ever reads. Then add the second rule. The file becomes the architecture, and the architecture becomes something agents cannot quietly renegotiate.

Paolino ends his post with the line that makes the whole argument: “Agents can write the code. The architecture is still yours to keep.”

This analysis synthesizes ArchSpec 1.0: Executable Architecture Specification for Ruby’s Agentic Coding Era (Carmine Paolino, August 2026), read as a first-party account by the tool’s own author.

Victorino Group helps engineering teams turn architectural intent into enforced gates before agent-written code erodes it. Let us talk.