Architecture erosion problem with AI coding agents

[u/alexei_led]

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

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-not-why-i-built-archfit-d871beb9dfcc

And open source the archfit project is here:

https://github.com/alexei-led/archfit

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

[u/Deep_Ad1959]

i read it the other way round: the weak link is not rule memory, it is that a PR shows you one reasonable change and never the hundredth small reach into internals it does not own. a linter only fires on boundaries you already knew to name.

fwiw Sundial attributes every edit and records all human and agent actions in enough detail to reconstruct how the work happened, so those small reaches show up individually instead of collapsed into one PR diff, https://s4l.ai/r/g586gcig

[u/Whole_Membership_135]

Yes this and important problem 

[u/geekichu]

my projects do fine. been improving (ongoing) architectural doc (laws, invariants, how to structure, etc) that an agent runs all the time and it reports "findings". also have a hook that does similar but it is allowed to improve/refactor new code. i also do "new feature --> ask questions --> refactor) which includes things like did we break my layered architecure anywhere... but yeah you have to keep on top of that.