Unwritten Rules: How AI Can Help Enterprises Capture Engineering Knowledge That Documentation Misses
As an engineering leader, you might be familiar with the following scenario: someone who’s just joined your team opens a pull request. The code looks clean, follows the style guide, and passes all the tests. However, a senior engineer sends it back anyway because dates must be stored in UTC, after a time-zone bug double-billed customers, and only the billing service writes to the orders table. None of these rules is written down anywhere.
Now, picture the same scenario, but replace the new engineer with an AI coding tool. It will make the same mistake, for every engineer, on every request. And because AI code output is higher than ever, the mistake might not be caught in review.
This gap was one of the themes engineering leaders kept returning to at our SF Tech Week roundtable, and it raises the question this article sets out to answer: what organizational knowledge must AI be able to access?
Our view is that AI needs not just your business rules, but also the reasoning behind them. Some of it is already in your documentation. The rest has to be captured where the work happens, then validated by the people who own it.
Key Takeaways
- Every large codebase runs on rules nobody wrote down: approved libraries, service limits, and edge cases that break production.
- Docs say what to do, but often miss why, when a rule does not fit, or how the team really works.
- AI coding tools only see the context they get, so hidden rules stay hidden.
- A context layer can mix docs, repo patterns, and design choices, and can spot repeated practices across a team.
- Cognitive debt grows when teams accept code they cannot explain. Working inside known patterns slows it, but does not replace human understanding.
The Rules Nobody Wrote
Every engineering org runs on some layer of consensus that never made it into a document. Senior engineers know about it, but new hires learn it slowly, usually only after a pull request comes back.
This is not new. In 1985, computer scientist Peter Naur argued that a program is more than source code: it’s a theory held by the team that built it. As Margaret-Anne Storey points out, that theory explains what the software does, how its parts fit together, and how it can change safely. The code is only the visible part.
The invisible part has a cost. In the 2024 Stack Overflow Developer Survey, 61% of developers said they spend more than 30 minutes a day searching for answers to work problems. Much of that time goes into finding knowledge that exists but is not searchable.
What Lives Only in People's Heads
Unwritten engineering knowledge often falls into four groups:
- Approved and avoided libraries. The team uses one charting library, not the three most popular ones. After a licensing review, someone dropped another library, and nobody updated the wiki.
- Why does a service take its specific shape? An odd boundary between two services often reflects a past scale limit, a compliance rule, or a team split. Engineers who don't know the reason behind it may treat that boundary as a mistake and remove it.
- Lessons from past incidents. The edge case that broke production two years ago is now handled by a check that seems useless. Remove it, and the incident can come back.
- Exceptions to written rules. Someone documented the rule, but not the exception.
Why It Leaves When People Do
This knowledge lives in the heads of people who were there when the decision was made. These people become the ones everyone goes to with questions. Stack Overflow's analysis of the same survey found that three in four developers keep answering questions they have already answered before.
This pattern is fragile. When those engineers move teams or leave the company, their knowledge leaves with them. What stays behind is code that works, and nobody who knows exactly why. That is one of the quieter sources of engineering drift: teams rebuild what they can no longer explain, each in a slightly different way.
Why Docs Capture Instructions but Not Reasoning
The normal response to lost knowledge is to write more docs. They are the first place a new engineer looks, and the first place an AI tool should look too. But they have a limit: they record what to do far better than why to do it.
They also age. A Fraunhofer survey of developers found that architecture docs are often seen as outdated and inconsistent, and that one-size-fits-all docs often don’t always help with the task at hand.
The software industry has known about this gap for years. In 2011, Michael Nygard proposed architecture decision records (ADRs): short records of a decision, its context, and its outcome. His point was simple: the reason behind a decision is one of the hardest things to track over a project's life. Without it, the next team has two choices: follow the decision blindly, or reverse it blindly, neither of which is safe.
The Three Things Docs Miss
Even good docs tend to leave out three things:
- Reasoning: why the rule exists and what problem it prevents;
- Exceptions: where the rule doesn’t apply, and who approved that;
- Informal conventions: how the team really builds things, which is often more specific than the style guide.
Storey calls the loss of this rationale intent debt: the erosion of the shared reasoning that both developers and AI agents need to change a system safely.
Why AI Makes the Gap Visible
A new engineer who misses an unwritten rule usually gets corrected in review. An AI coding tool misses it every time, for every engineer, at the speed of generation.
That is because AI works only from the context it gets. Ask a generic model for a charting component, and it will reach for the most common public library, not the one your team approved. Ask it to connect to a service, and it may call that service directly, unaware that your architecture routes everything through a gateway for a reason nobody wrote down.
The output often looks right. If the reviewer doesn’t know the missing rule either, it gets approved. Better models won't fix this: a smarter model with the wrong context still produces the wrong code. A larger context window will not fix it either, because context engineering is about giving the model the right rules, not more text.
How a Context Layer Captures What Docs Miss
The goal is simple to say: code that already fits how your company builds software, so review starts from the right place. To get there, AI needs the knowledge your senior engineers carry before it writes a line.
That is the job of an engineering context layer. When someone makes a request, the layer finds the rules, patterns, and decisions that matter, assembles them, and passes that context to the model before code generation.
What makes the layer useful for unwritten knowledge is where its context comes from.
Start With What You Already Have
The first input is the material your organization already owns: code repos, docs in tools like Confluence, Jira, and Notion, design systems, unit tests, QA, definition-of-done criteria, and any architecture decision records you keep.
The repos matter more than they might seem. Docs describe how the team is supposed to work. Code shows how it actually works: which libraries are imported, how services are called, and which patterns repeat across modules. Many informal conventions are written nowhere except in the code itself.
Add Approved Examples and Decisions
The second input comes from people. Some knowledge is too new or changes too fast to wait for the next round of docs: a newly adopted library, an internal API someone just shipped, or a clear way the team wants a tool used.
Engineers can capture this directly as reusable instructions, along with approved examples and the architectural decisions behind them. This is where reasoning gets recorded on purpose, by the people who own it, in a form the AI can use.
Learn From How Teams Actually Work
The third input is the one docs can never provide: patterns that emerge from how people actually prompt.
Take a simple example. One developer asks the AI for a singleton to connect to MariaDB. Another asks for one that connects to MongoDB. A third needs a Postgres connection and does not remember the word singleton, only that they want a single instance.
Three requests, three database engines, one shared intent. A context layer can spot that repetition across the team and propose the pattern as a standard. After that, a request to connect to a database can produce the singleton without anyone having to spell it out.
Nobody would have written that convention down. Nobody has time to document how they use a singleton. But the team had already agreed on it in practice, and now that agreement can be captured.
From Pattern to Standard: Why People Still Decide
A pattern that repeats is not always a good one. Teams repeat mistakes too. So the rule has to be clear: the system proposes, and people decide.
AI is good at noticing what a team does often across many requests. But it’s not responsible for deciding whether that practice should become the rule. That judgment belongs to the engineers who own the architecture, just as ownership of AI-generated code stays with a named human.
Who Should Own the Context
A context layer works best with one or two designated owners, usually architects from the platform engineering or architecture team. Open contribution degrades the layer quickly: conflicting guidance piles up and outdated rules linger. Owners should be able to add, edit, and remove sources with a full change history, and review proposed standards on a regular cadence.
Handling Conflicts
When new guidance contradicts an existing rule, the conflict should be flagged, not resolved in isolation. Engineers know the logic from a git merge: you can auto-resolve, but someone should look first. The flag goes to the document's owner and, since owners move on, to the last person who updated it.
The Other Gap: Cognitive Debt
Unwritten rules are knowledge that was never recorded. AI adds a second gap: knowledge that never forms. Margaret-Anne Storey calls this cognitive debt, the loss of a team's shared understanding of what a system does and why. It grows when teams accept code they can't explain.
A context layer doesn't make anyone understand code, but it reduces how much there is to decode. Code built on the team's own patterns looks like the rest of the codebase, and saving every prompt as an attributable version keeps the intent behind each change on record. Teams still need habits on top, such as explain-back reviews and named approvers for high-risk changes.
How to Start Capturing Your Unwritten Rules
You don't need a large program, or a new platform, to start. Most of the early work is making existing knowledge visible and giving it an owner, and those steps pay off whether or not AI is involved.
- Collect the most repeated questions. Ask senior engineers which questions they answer most often. Each one points to a rule that lives in someone's head, and together they show where your documentation is lacking.
- Inventory your sources. List the repositories, documentation spaces, ADRs, postmortems, and test definitions that already hold part of the answer. You’ll likely find more captured knowledge than expected.
- Name one or two owners. Make curating engineering context part of someone's role, not a side task. Without an owner, rules drift as quickly as the code.
- Record decisions with their reasons. For every significant architectural choice, write down the context and the trade-offs, not just the outcome.
- Review proposed standards on a cadence. As patterns emerge from how teams work, owners accept, adjust, or reject them.
One signal tells you whether it's working: fewer pull requests come back for breaking rules nobody wrote down, and the questions senior engineers field start to change.
Conclusion
Unwritten rules won't be fixed by writing more documents. Instead, you should capture them where work happens: in the code, in the decisions, and in how teams actually prompt. Then let the people accountable for the architecture decide what becomes a standard. Done well, this also slows cognitive debt, because code that’s built on familiar patterns is easier to understand than code that isn’t.
DesignVerse builds the context layer that allows engineering teams to generate code within your existing architecture and standards, from the repositories, documentation, and design systems you already have, plus the patterns your teams repeat.
Next in the series, we apply the title question of this article to legacy systems. In the meantime, find out how much engineering drift is costing you, and then request a demo to talk to our team.
FAQs
What is organizational context for AI?
It is the set of standards, decisions, patterns, and business rules that describe how a specific company builds software. Giving it to AI helps the output fit that company instead of generic public defaults.
Why is documentation not enough for AI coding tools?
Docs record instructions but rarely the reasoning, exceptions, and informal conventions behind them, and they go out of date. AI follows what it can see, so those gaps show up in its output.
What is tribal knowledge in software engineering?
People hold knowledge in their heads rather than in any system: they understand why a decision was made, what to avoid, and what broke last time. People lose it when they leave or change teams.
What is cognitive debt in software development?
Cognitive debt is the gap between the code a team has and the code it understands. It grows when teams accept code they cannot explain, and it shows up when something breaks and nobody can say why.
Can AI decide what becomes an engineering standard?
It should not. AI can find repeated patterns and suggest them. However, designated people should check what becomes a standard. They should also resolve conflicts with existing rules.