You ask AI to update an API endpoint. It updates the controller cleanly. What it does not update: the frontend service call that hits that endpoint, the middleware that validates the request shape, and the TypeScript interface that both sides depend on. The endpoint works in isolation. The system breaks. You spend forty minutes figuring out why.
This is not an edge case. It is the default behaviour of AI coding assistants when working on anything with more than one moving component — frontend and backend, service and middleware, schema and model. The AI sees what you show it. It does not see what connects to what. And it almost never asks.
AI coding tools solve the problem directly in front of them. You paste a function, describe a change, and the model produces a fix for that function. This is genuinely useful — the fix is usually correct, often better than what you would have written, and fast. The failure mode is not that the fix is wrong. It is that the fix is incomplete, and the model does not know it.
The model has no internal representation of your system. It cannot see that the function you changed is the source of truth for four downstream consumers. It cannot see that the data contract it just modified is assumed in six other files. It can only reason about what is in its context window — and most of the time, the dependent files are not there.
The result is what engineers call a cascading miss: one correct change, several silent breakages, no error until runtime.
Three patterns come up repeatedly:
Contract drift. You change the shape of an API response — add a field, rename a key, restructure a nested object. The backend is updated. The frontend still expects the old shape. Everything compiles. Nothing works at runtime.
Validation gaps. You add a new required field to a form or request body. The backend validates it correctly. The middleware that sits between frontend and backend does not know about the new field and strips it before it arrives. The validation always fails, and the reason is three layers away from where you are looking.
Model-schema divergence. You update a database schema — add a column, change a type, rename a table. The migration runs. The ORM model that maps objects to that table still has the old definition. Queries that should work now throw exceptions at the model layer.
In each case, the individual change is correct. The systemic picture is broken. And because AI produced the change confidently, there is no obvious moment where something felt wrong.
The solution is a single document — call it ARCHITECTURE.md or CURRENT_STATE.md — that describes your system in enough detail that any component change can be cross-referenced against every other component it touches.
The document contains three things:
The document is not written once and forgotten. It has two rules that make it work:
Start with the version of this document that takes twenty minutes to write, not the comprehensive one that takes two days and never gets finished.
The manual approval step is the one most people skip because it feels like extra friction. It is the most important part. AI's confidence is not the same as correctness at the system level. Making the change list explicit — and reviewing it before execution — is what catches the missed files before they become broken deployments.
The shift is from AI as a fast executor to AI as a system-aware collaborator. Without the architecture doc, you are handing a capable engineer a single file and asking them to make a change without telling them what the file connects to. With it, you are handing them the same file plus a map of the whole building.
The speed advantage of AI does not disappear — it gets more reliable. You stop losing the time saved on the change to the time spent debugging the breakage. The work that felt fast stops being expensive.
The pattern that causes most AI-assisted development failures is not bad code. It is correct code, written in isolation, that breaks a system it was never shown.