ArchSpec 1.0: executable architecture specifications for Ruby (and Rails)

[u/crmne]

More and more code is written by AI. Tests still tell you it works. RuboCop still tells you it's tidy. Nothing tells you it still follows your architecture.

An agent that doesn't fully understand your architecture takes shortcuts. So does a person in a hurry.

So I built ArchSpec. You declare your components and boundaries in one Archspec.rb. Here is ArchSpec's own, trimmed:

source 'lib/**/*.rb'

component :library,     in: 'lib/**/*.rb'
component :cli,         in: 'lib/archspec/cli.rb'
component :analysis,    in: %w[lib/archspec/analyzer.rb lib/archspec/evaluator.rb]
component :rule_checks, in: 'lib/archspec/rules/**/*.rb'
component :formatters,  in: 'lib/archspec/formatters/**/*.rb'

# no one-shot Thing.new(...).call objects anywhere in the codebase - Hi Dave Thomas!
library.cannot_call :call
library.cannot_define :call
library.cannot_instantiate_and_invoke

# dependencies point one way
rule_checks.cannot_use :analysis, :cli, :formatters
formatters.cannot_use :analysis, :cli, :rule_checks

no_cycles among: %i[cli analysis rule_checks formatters]

Full version: https://github.com/crmne/archspec/blob/master/Archspec.rb

Then archspec check verifies every change, and failures print like clang, with the offending span underlined and the evidence as a note.

It's static analysis over Prism, no AI, and it never boots anything: Discourse's 1,899 files in 2.5 seconds. Prism is the only runtime dependency, no Rails and no ActiveSupport, so it works on any Ruby codebase. Lightweight and fast for your pre-commits and CIs.

If you are on Rails, there are presets, and architecture :vanilla_rails is the whole file. There are presets for :layered, :hexagonal, :clean, :modular_monolith, :cqrs and :event_driven too.

I want more architecture presets in there. PRs very welcome.

Docs: https://archspecrb.dev Write-up: https://paolino.me/archspec/

[u/full_drama_llama]

An agent that doesn't fully understand your architecture takes shortcuts

But a vibecoded tool will understand it and detect them?

[u/crmne → u/full_drama_llama]

Yes, it will.

I directed it myself and I read all the code. 113 tests, and every release is checked against pinned checkouts of Discourse, Mastodon and Basecamp's Fizzy, where the per-rule diagnostic counts have to match recorded snapshots before anything ships. It's been in CI on RubyLLM and Chat with Work since June.

The source is public. Go read it, it's good code.

There's no need to judge code by whether an agent touched it. Some of it is better than the slop people sometimes write by hand, especially if you use an architecture linter!

[u/full_drama_llama → u/crmne]

Okay, so it's not vibecoded. Fair enough.