The Wall Nobody Marked
A contractor is handed a perfect set of drawings for a house.
Every room is dimensioned. Every pipe is routed. The work is fast, clean and exactly to specification.
What the drawings do not say is which interior wall is load-bearing. Nobody marked it. The person who knew left two years ago, and the reason lived in their head, not on the page.
So when the contractor sees a wall that looks redundant, they remove it. Nothing about that decision was careless. It was a reasonable call, made with the information on the page.
The ceiling sags three weeks later.
AI coding agents are that contractor — working at a speed no human crew has ever matched.
The Argument Everyone Is Having
Spend a few minutes on Hacker News lately and you will find some version of this argument. One recent thread, titled "The problem is not AI code, but not knowing about system architecture or intent," collected 388 points and 240 comments within days of being posted.
The article behind it makes a simple claim. The real risk is not what the model writes. It is that teams stop understanding their own systems and forget why past decisions were made. Cheap generation, the author argues, only makes maintenance the final boss.
The comments will be familiar to anyone who has led an engineering organization. Some say coding has become cheap while software engineering has not. Others worry that engineers who stop reading code lose the knowledge to make good calls. One person described tracing a company strategy back through a chain of AI-generated tickets and memos — and finding no human who owned it. Others replied that unclear decision-making long predates AI.
That last reply is the most interesting one. It points at the real issue, which is not about AI at all. Coding agents are an unusually honest audit of how much of your system's purpose was ever written down. An agent has no hallway memory. It can only read what is there, and in most organizations that is the code, a few stale diagrams and a wiki nobody trusts.
The Wrong Diagnosis
When an agent-written change causes a problem, the usual conclusion is that the model got it wrong. It hallucinated an API. It ignored a convention. It "didn't understand the codebase." The proposed fixes are all about the agent: a longer context window, a better prompt, another fifty lines in the rules file.
Sometimes that is right. Often it is not.
Look at the failures that are hardest to explain afterwards and you find that the agent did exactly what the code in front of it suggested. It added a direct database call because three other services make one. It retried a payment request because retrying is a sensible default. It removed an apparently redundant check because nothing in the repository said the check existed to satisfy an auditor.
Each of those is correct given what the agent could see. What failed is that the information that would have changed the answer was never in the place the agent looks.
That is not a model problem. It is an intent problem wearing a model problem's clothes.
The cost lands in three places:
Plausible code, wrong decision. The change compiles, passes the tests and quietly violates a constraint nobody recorded. It survives review because the reviewer cannot see the constraint either.
Comprehension debt. Code is produced faster than anyone reads it. The system grows while the team's understanding of it shrinks.
Review as archaeology. Reviewers reverse-engineer the purpose of a change from its diff, instead of checking it against a stated purpose.
What Intent Actually Is
"Intent" gets used loosely, so here is the concrete version. In an architecture context, the intent behind a part of a system is four things — and almost none of it is code.
Purpose
What the component exists to do, for whom, and what outcome tells you it is working. Not a description of the implementation. A statement that would still be true if you rewrote it in another language.
Constraints
What must always be true, and why. The payment call must be idempotent because the provider charges twice otherwise. Patient data must not leave a region because of a contract. This service must not call that one directly because it was split out to protect a team boundary.
The "why" matters more than the rule. A rule without a reason gets "optimized" away.
Non-goals
What the component deliberately does not do, so nobody — human or agent — helpfully extends it. Non-goals are the cheapest form of intent to write and the most commonly missing.
Ownership
Who decides when this changes, and who has to be asked. An agent that can see the owner can route a question or a review. An agent that cannot will decide for itself.
Notice what is not on that list: a description of how the code works. Agents already read code well. What they cannot read is the reasoning behind it — which is exactly what disappears when the two people who knew it leave.
Where to Write It So It Gets Read
Intent that lives in a slide deck is intent no tool will ever read. The test for any intent artifact is simple: would a new engineer, or an agent working in the repository, find it while doing the work?
| Artifact | What it captures | Where it lives | Who reads it |
|---|---|---|---|
| Decision record | A significant choice, the options considered, the reason, the consequences | In the repository, next to the code it governs | Engineers, agents, reviewers |
| Constraint note | An invariant that must always hold, and why | At the top of the module, or in a short file in its folder | Anyone changing that code |
| Purpose and non-goals header | What a component is for, and explicitly not for | The component's own README | Anyone arriving at it |
| Ownership map | Who decides, who is consulted, who is told | A file the review tooling can read | Reviewers, agents routing a question |
| Check that encodes the rule | The constraint, made executable | The build pipeline | The pipeline — so nobody has to remember |
None of this is new. Decision records, ownership files and architecture checks have existed for years. What has changed is the audience: a reader now exists that follows instructions literally and never complains the documentation is out of date.
Start where protection is highest for the least writing. That is almost always the constraint note on the two or three modules where a wrong change is expensive.
Here is how those pieces work together when an agent proposes a change:
%% caption: How intent reaches an agent-proposed change before it merges
flowchart TD
A[Agent Proposes a Change] --> B[Reads Intent Notes\nPurpose, Constraints, Non-goals, Owner]
B --> C{Does the change touch\na stated constraint?}
C -- "No" --> D[Automated Checks Run in the Pipeline]
C -- "Yes" --> E[Change Cites the Note\nand Names the Owner]
E --> F{Owner Approves?}
F -- "No" --> G[Change Revised or Rejected]
F -- "Yes" --> H[Note Updated in the Same Pull Request]
H --> D
D --> I{Checks Pass?}
I -- "No" --> G
I -- "Yes" --> J[Reviewer Checks Change Against Stated Purpose]
J --> K[Merged\nIntent and Code Stay in Step]
If you already keep decision records, the step to agent-readable intent is small. I have written before about how decision records bridge strategy and implementation and about extending them to cover decisions delegated to agents. This post covers the other half: not recording what agents decided, but giving them what they need before they decide.
How to Keep Intent Alive
Intent that is wrong is worse than intent that is missing. An agent will follow it with total confidence. Four habits keep it honest.
Write it at the moment of the decision. The cheapest time to record why is while the argument is still in the room. A record written a year later is a reconstruction. Make it part of closing the decision, not a follow-up task.
Keep it short and attached to something. A constraint note that fits in five lines gets read. A document that needs a table of contents does not. Put it in the same pull request that introduces or changes the thing it describes — so reviewing the code and reviewing the intent are the same act.
Make the important rules executable. A constraint that only exists as prose depends on someone remembering to check it. If a rule is a true invariant — a dependency that must not exist, an API that must not change shape — encode it as an automated check. I made that case in replacing the architecture review with fitness functions. The point here is narrower: an executable constraint survives even when nobody has read the note.
Review intent when you review code. Add one question to the checklist: does this change alter a stated purpose, constraint or non-goal — and if so, was the note updated?
What the Technology Leader Changes
Everything above can be started by one engineer on a Friday afternoon. Whether it lasts is a leadership matter, because intent only stays current if someone makes it part of how decisions get made.
Decide what deserves a record
Not every choice needs one. A workable rule is to record anything that would be expensive to reverse, that crosses a team boundary, or that you would be annoyed to see an agent reverse on its own. Everything else can stay in the commit message.
Make the forum about intent, not slides
In my work with an 80-person SaaS company, decisions had been waiting weeks for a cross-team meeting, because nothing was written down and decisions kept being revisited. A decision rights matrix and a lightweight decision log moved decision time from two to four weeks down to two to five days. The log became the thing new hires read to understand why the system looked the way it did. The full story is in the case study.
The mechanism was not clever. It was deciding who decides, and writing the answer down. That same log is the raw material agents need — though I have not yet run that with a client, and I will not pretend otherwise.
Set the expectation that agents read before they write
For any system where it matters, the working agreement should be that an agent-proposed change comes with a statement of which intent notes it considered. A reviewer can reject it for ignoring one. That turns intent from optional documentation into part of what makes a change reviewable.
What the Market Is Showing
Two signals point the same way.
The conversation
The Hacker News thread reached 388 points and 240 comments. Its subject is not a particular model or product. It is the worry that teams are generating code faster than they understand it — and the answer from the article behind it is that humans must keep supplying intent, taste and design, because AI cannot direct itself. You can read the thread and the article behind it. It is a developer-leaning audience, so treat it as a strong practitioner signal, not a universal one.
The job market
In a scan of 42 postings for senior architecture, AI and engineering leadership roles in New Zealand, Australia and the UK and Europe earlier this month, 14 asked for architecture governance in some form — standards, guardrails, design authority, review forums or decision records. That is my own tagging of the postings, so treat it as the shape of demand rather than an exact statistic. I re-opened three:
- A principal adviser for data and AI architecture at Rio Tinto is expected to lead architecture governance including design reviews, maintain architecture decision records, manage exceptions and help set enterprise architecture standards.
- A VP Engineering brief from the recruiter La Fosse wants "AI-first engineering" across the development lifecycle, with golden paths, standards and reusable scaffolding as foundations — and asks for "just enough" governance rather than heavyweight design documentation.
- An ICT Enterprise Architect role at Meridian Energy is asked to lead architecture forums and to establish standards, governance and guardrails "to support consistent decision-making."
Employers are not asking for more documentation; the La Fosse brief pushes against it. They want someone who makes decisions consistent, visible and light enough that fast, increasingly AI-assisted teams can follow them. That is the practitioners' problem, seen from the hiring side.
Action Plan
This Week
Ask three questions about a system your team is already changing with AI assistance:
- If a new engineer, or an agent, wanted to know why this system is built the way it is, where would they look — and would they find an answer?
- Which two or three constraints would be expensive to break, and are they written anywhere other than someone's memory?
- Who decides when one of those constraints changes, and would a reviewer know their name?
If the answer to the first question is "ask one particular person," you have found your single point of failure. It is not a machine.
Next 30 Days
Pick the one system where a wrong change costs the most. Write a purpose-and-non-goals header, a constraint note for each invariant that matters, and an ownership entry. Encode the one or two constraints that can be checked automatically. Add the intent question to your pull request template.
3 to 6 Months
Extend the practice to the systems your architecture forum cares about most. Set the threshold for what earns a decision record, so the forum handles only what needs a room. Track how long it takes a new engineer to answer "why is it built this way?" without asking a person. Review the notes on the same rhythm as the rest of your architecture governance — not as a separate documentation project.
Final Thought
The contractor with perfect drawings and no mark on the load-bearing wall is not a bad contractor. The drawings were accurate. The wall came down because the reason it was there lived in the head of someone who was not on site that day.
AI coding agents are that contractor, at a speed no human crew has matched. They will follow the drawings flawlessly. What they cannot do is know what the drawings never said.
So the useful question is not whether your agents are good enough. It is whether the purpose, the constraints and the owners of your system are written somewhere a reader with no hallway memory can find them.
If they are, an agent is a very fast pair of hands. If they are not, it is a very fast way to discover how much of your architecture was only ever in people's heads.
Write Down What Your System Is For Before an Agent Changes It
If your teams are adopting AI coding tools and nobody can say where the reasons behind your architecture are recorded, that is not an AI tooling problem. It is an intent gap — and it is cheapest to close before the next large change ships.
or
AI can write the code. It cannot know what the code was for unless you wrote it down.
