The change that looks like a cleanup
An engineer three weeks into a deployment finds two services that appear to do closely related work. One is small, barely maintained, and calls the other constantly. Merging them would remove a network hop, delete a deployment target, and simplify the integration they were sent there to build.
Every local signal says this is an improvement. The tests pass. The reviewer on the vendor side, who also does not know this system, approves it.
The separation existed because one of those services processes data that must remain inside a specific jurisdiction, and the boundary was the mechanism that guaranteed it. Nothing in either service says so. The decision was made in a compliance review two years earlier, recorded in a document nobody linked from the code, and enforced since then entirely by the fact that the people who knew about it reviewed the changes.
Those people were not on this review.
The change was not careless. It was correct against every piece of information available to the person making it. The information that would have made it obviously wrong was not in the system.
What a codebase cannot tell you
A repository is an excellent record of what and a poor record of why. It shows you the structure that exists. It does not distinguish between structure that is deliberate, structure that is vestigial, and structure that is actively being migrated away from.
To an engineer with years in the system these are easy to tell apart, because they remember the arguments. To a newcomer they are indistinguishable, and a forward-deployed engineer is a newcomer with a deadline and commit access.
This is worth stating carefully, because it is often diagnosed as a documentation problem and treated with a documentation remedy that does not work.
Why writing it down has never been enough
Organizations have been told to document their architecture for decades. Many have. The problem persists anyway, for four reasons that are structural rather than cultural.
1. Local optimization
Most architectural violations are not reckless. They are locally optimal changes made by someone who cannot see the constraint they are crossing. The merge above is the pattern: the improvement is real at the scale the engineer can see, and wrong at the scale they cannot. Documentation only helps here if the engineer knows there is something to look up, and the defining property of an invisible constraint is that you do not know to ask.
2. Superseded decisions that still read as current
A wiki page describing the messaging architecture is accurate as of 2023. The team moved off that approach in 2024 and documented the new one somewhere else. Both pages exist. Both are confident. Neither says which supersedes which, and the older one often ranks better in search because it has been linked to for longer. An engineer following the retrieved document faithfully implements a pattern the organization abandoned.
3. Context without applicability
A genuine, current, authoritative decision states that services must use a particular persistence technology. It was written about the transactional core. An engineer working on an analytics job reads it as universal, applies it where it does not belong, and produces something nobody asked for. Or, more commonly, notices it does not obviously apply, concludes the rules here are advisory, and stops consulting them. A constraint without a stated scope teaches people to discount constraints.
4. Architecture that was never externalized
The largest category. The constraint exists, everyone senior obeys it, and it has never been written anywhere because it was never contested in a forum that produced a document. It is enforced socially, through review by people who happen to know. Onboarding transmits it by correction rather than by reading.
An FDE meets all four, compressed into a few weeks, in a system where they have no social network to route around the gaps.
Why the social mechanism does not transfer
It is worth being precise about what was actually holding the line before, because the answer explains why forward-deployed work breaks it.
In a stable team, unwritten architecture is enforced by a review process that includes at least one person who was present when the decision was made, or who was corrected by someone who was. That person does not consult a document. They recognize the violation, because they have seen its consequences. The mechanism is pattern matching against experience, distributed across a handful of long-tenured engineers, and it works well enough that most organizations never notice they are relying on it.
It has three properties that make it fragile in ways nobody plans for. It is undocumented by construction, since the whole point is that it operates without documents. It is concentrated, usually in fewer people than anyone would guess, which is why architectural quality often degrades sharply after two or three specific departures. And it is invisible until it fails, because a mechanism that silently prevents bad changes produces no evidence of having worked.
A forward-deployed engineer is outside all of it. They are not in the informal review network, the people who hold the patterns are not reviewing their pull requests, and nobody has told them the mechanism exists because nobody thinks of it as a mechanism. From inside the customer organization it does not look like the FDE is missing anything. It looks like they are making strange decisions.
This is also why the usual remedy fails. Asking the customer to document their architecture asks the holders of the tacit knowledge to externalize something they have never had to articulate, on a deadline, for the benefit of a contractor. What comes back is typically a description of the current implementation, which is the one thing the FDE could already read.
Documentation and control answer different questions
The four failure modes share a root. Documentation is optimized to answer what should I know about this system. That is a retrieval question, and the whole apparatus around it, search, wikis, decision records, onboarding guides, is built to answer it well.
The question an FDE actually needs answered at the moment of change is different: what must remain true no matter what I am trying to accomplish right now. That is not a retrieval question. It is a control question, and no improvement in how findable a document is will answer it, because the failure happens after the document has been read.
This is the same separation that appears when an agent retrieves a constraint and then violates it. Forward-deployed work simply makes it concrete faster, because the person who would normally catch the violation in review has the same context deficit as the person who made it.
Not everything should become a rule
The instinct at this point is to convert the architecture into constraints wholesale. That instinct is wrong, and being precise about why matters more than the enthusiasm.
Some architectural commitments reduce cleanly to something a machine can check: a dependency direction that must not reverse, a persistence technology required in a specific domain, a boundary that must not be crossed. Others carry several independent significant terms at once, so turning them directly into a literal rule would either miss part of the decision or fire constantly on unrelated code. And some are genuinely matters for human judgement and design conversation, where a mechanical check would be actively harmful.
Mneme’s Architecture Protection Audit separates these into four states, and the distinctions are worth borrowing whether or not you use the tool:
| State | What it means |
|---|---|
| Protected | A typed deterministic rule exists on this decision. A contradicting change is stopped. |
| Mneme-ready | The decision reduces to one concrete supported guardrail that can be written without guessing. The rule can be emitted, but activation is a deliberate, separate act. |
| Requires modelling | The recorded intent carries several independent significant terms. A literal rule would miss part of it or fire on unrelated code. |
| Guidance | The decision belongs in review and design conversation rather than in a deterministic rule. This is not a judgement about importance. |
Two things about this are easy to get wrong. Guidance does not mean unimportant: a Guidance decision can be the most consequential commitment a team has made, and it is excluded from the protection denominator precisely so that reporting it as a gap does not imply it should have been a rule. And installing anything does not make a decision Protected. A repository can have the tooling in place and zero Protected decisions, because activation happens one decision at a time and on purpose.
The question worth asking on arrival
For a forward-deployed engineer, the useful reframing is that the first-tier decisions, the ones that reduce to a mechanical check, are exactly the ones whose value does not depend on you already knowing about them. That is the entire point. A constraint that fires when you cross it is the only kind that helps someone who did not know it existed.
Which suggests a different first question on arriving in a customer environment. Not “where is the architecture documentation,” which usually has an answer that turns out not to help. Instead:
Of the architectural decisions this system depends on, how many would actually stop a change that contradicted them, and how many rely on somebody happening to notice?
In most enterprise codebases the honest answer to the first half is close to none, and the second half is carried by a small number of long-tenured engineers who are not in the review queue for your work. That is not a failure of those engineers. It is an arrangement that worked while changes arrived at human speed and the reviewers had the context.
Both of those conditions are now changing, which is the subject of the next piece: what happens to this problem when the forward-deployed engineer is directing a coding agent that produces changes faster than anyone can review them, and has no access to the reasoning at all.