Marios PriftiCTO & CPTO Book intro call

No Documentation in the AI Era? Then Your AI Is Guessing

Why software documentation has become the context layer for AI agents, and how to build it as a knowledge system.

AI & engineering

Today I had a call with some very experienced technology leaders. When the conversation turned to documentation, I realised how many projects still come without it, even though everyone in the room agreed that this is bad practice.

None of that is new. What is new is the cost.

In the AI era, "we will document it later" means something different.

The old cost of missing documentation

When decisions live only in people's heads, the symptoms are familiar. Onboarding takes longer. The same questions come back every few weeks. Knowledge leaves with every departure, and the one person who understands the payment flow becomes a bottleneck for everyone else.

The numbers have been telling us this for years. In Stack Overflow's 2024 Developer Survey, 61% of developers said they spend more than 30 minutes a day searching for answers, and 30% said knowledge silos hit their productivity ten or more times a week.

That was the cost when only humans were reading the code.

The new cost: AI coding assistants that guess

Now there is another reader. AI coding assistants and AI agents write, review and change code every day, and 84% of developers use or plan to use them. But AI can only work with the context it is given. When the context is incomplete or missing, it does not stop and ask. It generates confident code anyway.

Developers feel this already. In the 2025 survey, 46% said they do not trust the accuracy of AI output, and the most common frustration, named by 66%, was solutions that are almost right, but not quite.

"Almost right" is exactly what you get when an AI understands the code but not the decisions behind it: why the retry logic works the way it does, which service owns the data, what was tried before and rejected.

So documentation is no longer only for the next developer who joins the team. It is also the context layer for AI.

Two documentation layers, one source of truth

I see documentation as two connected layers.

The human-facing layer explains the why. Architecture decisions and their trade-offs, often captured as architecture decision records. Onboarding guides. Runbooks for when things break. The reasoning behind the code, which the code itself can never show.

The machine-readable layer makes that knowledge structured, searchable and available to AI agents. Same knowledge, different shape.

The two are not separate projects. The second is built on the first. If the human layer is weak, the machine layer only spreads the gaps faster.

One source of truth feeds both developers and AI agents Source of truth in Git Human layer: the why Decisions and trade-offs Onboarding and runbooks Owner, status, review date Structured sources OpenAPI and JSON schemas Database schemas Infrastructure as code Knowledge system Chunk and embed Vector database with metadata Hybrid search semantic + keyword + metadata filters MCP server Approved docs, schemas and internal tools AI agent Searches and retrieves, then proposes a change grounded context New developer reads the why
Developers read the human layer directly; AI agents reach the same knowledge through retrieval and an MCP server.

From a folder of Markdown files to a knowledge base

For the AI-facing side, documentation cannot just be a folder full of Markdown files. It needs to become a knowledge system.

Keep the source of truth in Git. Documentation is versioned and updated together with the code, in the same pull request. If the code changes and the document does not, the review should catch it.

Give every document metadata. Service, domain, owner, status, last-reviewed date and related repository. Metadata is what lets you, and an AI agent, tell a current runbook from one that was abandoned two years ago.

Add structured sources around it. OpenAPI specifications, JSON schemas, database schemas, infrastructure-as-code and typed configuration. These are documentation too, and they have the advantage of being precise.

Then comes retrieval, the part that turns a knowledge base into something an AI can actually use.

Documents are split into chunks, turned into embeddings and stored with their metadata in a vector database. A hybrid search layer then combines semantic search with keyword search and metadata filters. This is the core of retrieval-augmented generation (RAG).

The hybrid part matters. Semantic search understands that "payment retries" and "failed charge handling" mean similar things. Keyword search finds the exact service name or error code. Metadata filters keep out documents from the wrong service or ones marked as outdated. Together, a question about payment retries surfaces the right service, the architecture decision, the runbook and the API contract.

An MCP server: a front door for AI agents

On top of that, an MCP server can expose the approved documentation, schemas and internal tools to AI assistants.

The Model Context Protocol has quickly become a widely adopted open standard for connecting AI applications to other systems. It is now run under the Linux Foundation, with Anthropic, OpenAI, Google, Microsoft and AWS behind it. That matters for a CTO: you are building on a standard, not locking yourself into one vendor's tool.

Through the MCP server, an agent can search the knowledge base, fetch a full document, inspect a schema or query an approved internal source, instead of relying on guesses. And because you decide what the server exposes, you also decide what the AI can and cannot see.

How it works in practice

The flow is simple:

  1. Someone asks a question, or asks an agent to make a change.
  2. The agent searches the knowledge base.
  3. It retrieves the most relevant chunks.
  4. If it needs more detail, it fetches the full source document or schema.
  5. It answers, or proposes the change, using that grounded context.

For example, instead of expecting an AI model to "remember" how a payment service works, the agent searches the documentation, retrieves the relevant architecture decision and API contract, and only then proposes a change. The same steps a good senior engineer would take, just faster.

Where to start

You do not need the whole system on day one. A practical order:

  1. Write down the decisions first. The five or ten architecture decisions that new people always ask about.
  2. Move documentation into the repository, and make updating it part of the definition of done.
  3. Add metadata and an owner to every document, with a review date.
  4. Collect the structured sources you already have: API specs, schemas, infrastructure code.
  5. Then add retrieval and an MCP server, starting with one team or one service.

Documentation is infrastructure

The goal is not to make AI replace documentation. It is to make documentation good enough that both a new developer and an AI agent can understand the system, without interrupting someone who has been there for years.

That changes how documentation should be funded and owned. Not as a nice-to-have that gets written when there is time, but as part of the platform the whole team, human and AI, depends on.

Documentation is no longer overhead. It is infrastructure.

More from the blog

Keep reading

Security

Cybersecurity Is Not an Unexpected Expense

Security gets funded in waves and dropped when the headlines move on. The supermarket fridge cyberattacks show what that costs.

Contact

Have a technology decision worth discussing?

Every engagement is scoped and priced to the case. A 15-minute intro call is the quickest way to find out what yours needs, and whether deeper work is worth it.

  • 15 minutes
  • By video
  • Confidential, NDA on request
  • Europe & US time zones