Untitled topic

I’ve been thinking about a problem that seems to be getting worse and more visible as we use coding agents more seriously.

An agents can write good quality code today and can make a perfectly reasonable local changes and write tons of new tests. So that everything compiles, the all tests are green, and even the PR looks reasonable and well-written.

But the change may still bypass a module’s contract, reach into another module’s internals, introduce a wrong dependency and break your architecture intention and design. And do this by hundreds of small changes, creating an architecture erosion and converting your code to big ball of mud.

Of course, this isn’t unique to LLM models. People have been doing the same thing for years, especially under delivery pressure. The big difference is speed and about of new code and tests models generate relentlessly. People cannot scale - not in speed and not in code review.

You can try to use well-written prompts, ADR documents, `AGENTS.md`, and code review, and you should, but I’m not sure helpful is this. All these "rules" depend on agent remembering the right thing and following the rule at the right time.

I was looking for a more deterministic approach to keep architecture intent and prevent architecture/design erosion. Unfortunately I did not find the right tool (but I would a lot of helper tools) and I used AI to create meta linter for architecture [archfit](https://github.com/alexei-led/archfit)

The basic idea is to describe the intended module boundaries, compare them with the dependencies that actually exist in the code, and report findings and violations as part of CI or other automation trigger. The checks must be deterministic and not random LLM-based.

I don’t think this as a replacement for a thoughtful architecture review. It’s more like a structural linter that catches some kinds of erosion early.

I’m still trying to figure out where the useful boundaries are:

- Which architecture rules should block CI, and which should only be warnings? - How much configuration is reasonable before the tool becomes a burden? And who is responsible to write this configuration and maintain it over time (imho, this is human role, but ...) - If coupling scores are useful, or not that much? - Can structured reply actually help agents to follow the architecture guidance and respect it?

I wrote a blog with more detailed explanation on Medium:

[https://itnext.io/the-tests-are-green-the-architecture-is-no...](https://itnext.io/the-tests-are-green-the-architecture-is-no...)

And open source the `archfit` project is here:

[https://github.com/alexei-led/archfit](https://github.com/alexei-led/archfit)

I would appreciate any feedback on this approach, any ideas and contribution too.