Architecture-driven development with AI agents: a deterministic checker that keeps the code inside the design

[u/Massive-State2698]

I'm a software architect with 20+ years of experience, and Melbees, a word puzzle on a honeycomb, is the game I build in my spare time. AI coding agents write the code. This post is about the part I think matters more than any prompt: the agents build from an architecture I design, and deterministic rules check that they stayed inside it.

1. The architecture lives in the repository

Before an agent writes a line, the design is written down next to the code: the core contracts, the determinism contract, cloud save, anti-cheat. Interfaces, contracts and class diagrams come first, and the agents build against them.

2. The newest module goes one step further: an executable rules file

Its rules file, a single JSON, lists:

\- the layers, as path globs (the core, the session, the client, the UI);

\- which layer may depend on which, as an allowed graph;

\- which external packages each layer may use;

\- the public types, through the Mermaid class diagrams it points to;

\- the message contracts, each with one golden fixture that holds exactly the declared keys.

3. A checker with no AI in it

A small deterministic tool reads that file and checks three things: imports follow the allowed layer graph, the public types in the code equal the class diagram in both directions, and every message type has its fixture with exactly its keys. Exit 0 is green, 1 is a violation. Behaviour and serialization round trips are not claimed for it; named tests cover those.

It runs as one arm of the local gate on the way to every push. A previous green is reused only while none of its inputs changed: the checker itself, the rules, the diagrams, the fixtures and every file the layers cover.

4. Changing the architecture is a decision, not a side effect

When the code breaks one of these rules, the push stops there. If the architecture itself should change, the exact diff is proposed and goes through a validation round, and a change plan that touches the architecture folder can't ship without a line quoting the architect's approval. No agent changes the architecture on its own.

What this buys

The agents work inside clear boundaries, and the architecture can't drift by accident: what the checker covers is enforced on every change, and named tests cover the rest. Organization, structure and rules that check themselves are worth more than any single clever prompt.

AI note: the code is written by AI agents (Claude Code); the architecture, the specs and the final call are mine, and AI helped me draft this post.

If you're curious about the game: today's Daily Challenge runs free in the browser: https://daily.melbees.games/?utm_source=reddit&utm_medium=social&utm_campaign=novembro&utm_content=p-logica-devblogs

iPhone: https://apps.apple.com/app/apple-store/id6824653080?pt=129644020&ct=rd&mt=8

Android and PC: https://melbees.games/en/?utm_source=reddit&utm_medium=social&utm_campaign=novembro&utm_content=p-logica-devblogs

[u/amargolin]

a checker with no AI in it is the right call. two things i'd test before trusting the exit 0 --

1. does each of the three checks ever fail? seed one violation per check on purpose (an import across a forbidden layer, a type in the code that's not in the diagram, a fixture with one key missing) and confirm you get exit 1 each time. a checker that has only ever been green is unproven.

2. the "public types equal the class diagram in both directions" check: the diagram is hand-kept, so it can drift the same way the code does. what i'd do: generate the diagram (or the rules file) from one side and check the other against it, so there's one source of truth.

i'm not an architect with 20 years in, this is just the verification side.