Introduction#

Over the past few months, the software engineering industry has seen an explosion of LLM-generated code, with both positive and negative outcomes. That mix is normal when a profession is first experimenting with a technology that feels almost alien.

Now we are slowly entering a phase where the initial butterflies of those light-speed prototypes are giving way to less flattering stories, coming from both small and big companies, which highlight the problem of multiplying the amount of code produced without preserving its quality.

But we are not going to stop here and throw the technology away, are we? Keep reading to see where I think the industry might be heading in the next stage of this amazing trip.

Code might not be the knowledge transfer layer anymore#

As I argued in my previous AI-related article, AI is fantastic when humans are not needed, and I think that statement is aging reasonably well. But for agents to get there, we need to provide them with the right context. When that context is missing and has to be pulled on the fly, grounded on wrong assumptions, the final quality suffers.

Code is the only thing agents have today to draw sound conclusions from. However, there are plenty of design choices, team processes, engineering standards, company directions and many other things that live outside our codebase and those infant markdown files we are rushing to stick next to our code in all sorts of shapes and forms. Those bits live in the minds of us: designers, engineers, product/engineering managers, directors, and everyone else.

Are the agents really that dumb? Or are we silently failing to provide what is otherwise available to any properly trained employee with at least 6 to 12 months of tenure? I think it’s mostly the latter.

So all we have to do is gather a bunch of markdown files with all that information and dump it somewhere as global context for both humans and agents, right? Well, it’s not that simple.

We, as an industry, have been lazy about creating a well-crafted and well-maintained source of internal documentation, because we figured out we could operate decently well without spending the resources required to do so. These wikis and internal docs repos exist everywhere, but I think they tend to be messy and rotten in almost all cases. We realized that code and the processes around code were what truly mattered, and we aimed our excellence at those. Humans could talk to each other to share the right context for development and compensate for poor internal documentation.

The problem we have now is that everything we tell each other is not being properly transferred to our new AI partners. Can you imagine hiring a software engineer and asking them to develop features by only looking at the codebase, without letting them join a single meeting, have any 1-on-1, or watch any company all-hands?

Excellence at the code level is still necessary, but we need to start extending that same seal of quality to the shared knowledge pool, if we want our new agents to be anywhere near as effective as we are at translating business needs into technology solutions, all while respecting team procedures and, most importantly, company direction and rules.

Our markdown sharing tooling isn’t nearly as advanced#

Markdown is, for now, the natural format for this shared layer. It’s plain text, so it diffs and reviews like code; it’s readable by a human without any special tooling; and it happens to be exactly the shape today’s agents consume and produce most fluently. It also lives comfortably inside the workflows we already use for code, which is half the battle. So, assuming markdown is our best bet for human-agent interactions, what do we have today? Tools like Obsidian and Logseq are cool, but it’s hard to find companies that have settled on one of them as a kind of collective mind, with content that is accurate, up to date, and well structured.

If it’s scoped to a single repository, it’s missing too much, even when that repository holds our entire codebase, because not everything is code. If a single person maintains it, or gatekeeps it, it does not scale. If we don’t regularly check that the structure makes sense and stays easy to navigate, we have a problem. If the content is stale, it might not be accurate. If we don’t have a background process reading shareable sources like Slack conversations and meeting transcripts, who is going to be responsible for adding new content on a regular basis? And if some of that content describes procedures, like runbooks or AI skills, who is evaluating them so they don’t rot?

That’s a long list of non-trivial problems we never felt the urge to fix. Ironically, we have solved most of them for code itself: we keep a list of code owners, we refactor our architecture when it stops scaling, we fix bugs when the application doesn’t behave as it should, we add features as the business requires, and we have tests that guard the whole thing against regressions.

What if now is the right time to solve these same problems one level up the abstraction ladder, in our long-mistreated internal documentation?

What could a solution look like?#

I don’t think we need to invent anything radically new. We can borrow the playbook we already trust for code and apply it one level up. Concretely:

Borrow the playbook we use for code#

  • Owners, not a gatekeeper. Every domain of knowledge has named owners, the same way code has code owners. Responsibility sits with the people closest to each topic, so it scales and survives any single person leaving.

  • Composable nodes, not one monolith. A single repository is too small a unit, because architecture decisions, product vision and team norms don’t live in any codebase, but one giant company-wide brain is too rigid to maintain. The sweet spot is a graph of context nodes: each team, department or layer of leadership owns a node focused on its own topics, and those nodes feed knowledge up and down to one another. It composes with the org chart instead of fighting it, and keeps ownership where the knowledge actually lives.

  • Continuous ingestion, not manual upkeep. A background process distills shareable sources like Slack threads and meeting transcripts into structured notes and routes them into the relevant node, so new knowledge flows in without anyone having to remember to write it down.

  • Structure that gets refactored. Just as we refactor an architecture once it stops scaling, the knowledge graph is reorganized periodically so it stays navigable instead of decaying into a swamp.

  • Freshness as a first-class signal. Content advertises how current it is, and stale entries get flagged and revised, the equivalent of fixing a bug when reality and the docs disagree.

  • Procedures that are tested. Runbooks and AI skills are exercised and evaluated regularly, the way tests guard code against regressions, so they don’t quietly rot into instructions that no longer work.

None of these bullets is exotic on its own. The hard, interesting part is making them work together as a single living system, for both humans and agents. And even if we never squeeze the full leverage out of it for AI agents, a living knowledge layer like this is something plenty of humans would appreciate too.

The nodes need a shared shape#

Owners and ingestion keep the layer alive, but they say nothing about what a node is actually made of. And a node stuffed with shapeless prose rots just as fast as any wiki page we have ever abandoned. We also need to agree on the shape of the things we keep inside it.

The good news is that we don’t have to invent that shape. Most of what we reason about at work is already a recognizable kind of thing, with a name the whole industry already shares: people, teams, processes, features, components, architecture decisions, post-incident reviews, runbooks and AI skills, strategy, engineering principles, engineering guidelines. We just never bothered to treat them as first-class, typed entities, the way we treat a class or an interface in code.

Naming them explicitly pays off on both sides of the partnership. A human and an agent both know that an architecture decision record or a post-incident review has a predictable structure, so they can produce one, find one, and trust what’s inside it, instead of parsing yet another free-form document that may or may not contain what they’re after.

But the real leverage isn’t in the boxes, it’s in the edges between them. Once a post-incident review links to the components it touched, you can ask for every incident a given component has ever caused and get a straight answer. You can walk the other way too: this feature is owned by that team, governed by these engineering principles, and it produced this runbook. The knowledge stops being a pile of pages and becomes a graph you can actually traverse, which is exactly the kind of context an agent needs and rarely gets.

A knowledge graph of typed entities connected by labeled relationships: a team owns a feature, the feature is built from components and governed by engineering principles, a component is the subject of a post-incident review, and that review produced a runbook, illustrating how knowledge becomes a traversable graph rather than a pile of disconnected pages

What this is not#

It helps to be just as clear about what does not belong in this brain, because the temptation to turn it into a dumping ground for everything will be strong.

It is not the codebase. This might sound surprising given where we started, but code stops being the knowledge layer and becomes an artifact produced one level down, something the brain reasons about and points to, rather than a part of the brain itself.

It is not application data. Live information about our customers and our business already has a well-designed home in our databases and the products themselves.

And it is not observability data. The live state of our systems already has an excellent home in our observability stack.

What’s left is the durable layer of why and how we work, the part that today only lives in people’s heads and the occasional meeting nobody recorded. That, and not the fast-moving runtime data we already have tooling for, is what we keep losing.

The full picture#

Step back and the layers fall into place. Your application holds its own data. Your observability stack tells you everything you need to know as an external viewer of your running systems. Your codebase defines the business logic and, through infrastructure as code, the configuration of those systems. Everything else, all the why and how that never fit cleanly into any of those, is what goes into the collective team brain.

Four complementary layers of a software organization: application data lives in the product and its databases, observability data lives in the monitoring stack as an external view of the running systems, the codebase holds business logic and infrastructure as code, and the collective team brain holds everything else, the durable why and how of working, feeding complete context to AI agents

Get those four layers right and something quietly powerful follows: every task in the software development lifecycle you hand to an agent arrives with everything it needs to succeed. No missing context pulled on the fly, no decisions grounded on wrong assumptions, just a complete brief for the work in front of it.

Conclusion#

Think of it as the next layer of a knowledge network we have been building for decades. The internet gave us the global layer: raw, undigested content from everywhere, and it’s exactly what today’s frontier models were trained on. That’s why they are so capable on general questions and so shaky the moment we drop them into our own company. The global layer is built; the local one is not, and that gap is the bottleneck.

That local layer is also a harder problem, because it moves faster. Global knowledge changes slowly; the information we handle at work changes every day. Building a structured, living home for that fast-moving context is, in my opinion, the next thing the industry has to figure out, and it’s how we stop “hiring” generic AI developers and start onboarding ones that know how we work, what we build, and why.

I think there is room for the industry to build something that serves this purpose. Projects like Ars Contexta are already exploring the space, and I intend to do so as well. Stay tuned!

Thanks for reading!