Documentation as Infrastructure

“Documentation is no longer a record of what was built; it is the infrastructure through which we build.” — Matt Gierhart

For me, this shift became real when I connected Claude Code to my Obsidian vault. Before that, working with AI meant isolated chat sessions: you typed, you got answers, you copied them somewhere, you started over next time. The AI had no memory. No context. Every conversation began from zero.

When Anthropic released the Model Context Protocol in late 2024, I could suddenly point Claude at my notes, my project files, my research. But the bigger deal was that Claude could write into it: session protocols, research summaries, project updates. And when a conversation ran out of space, we could start a new one, load the last protocol, and pick up exactly where we left off. Everything was there.

That was when documentation stopped being something I did after the work. It became the thing that made the work possible.

With Claude Code, this went further. Claude Code does not just access files through a connector. It lives inside the filesystem. It reads, writes, moves, searches across the entire vault. And because it does, the structure of my vault (the folder hierarchy, the naming conventions, the protocols, the overview files I keep for each project) became the operating system for my collaboration with AI.

Today, this is what it looks like: I juggle many projects at once. A new email comes in about a client project. I tell Claude Code to check the project folder, read the last protocol, and catch up. Within seconds, it knows the context: what we discussed, what was decided, what is still open. Then it reads the email and suggests a response, or asks me what I want to do. Context switching that used to cost me twenty minutes of mental ramp-up now happens in seconds. The AI is not doing anything clever here. The documentation is doing the work.

My own documentation habits changed because of this. I take far more notes now than I used to: what I just finished, what I am working on next, what I am thinking about a project. Because I know that the more context I provide, the better Claude Code can help me. Writing things down is no longer record-keeping. It is investment in future capability.

I dictate much more than I type now. Recording thoughts as voice and transcribing them means I produce more content with less friction. Spoken language is messier than written text, but it carries more of what I actually think. The transcripts become raw material that Claude Code can work with.

Every talk I give gets recorded, transcribed, and stored in the vault. When a new speaking request comes in, I can say: look through my past talks and find content that connects to this brief. Claude Code searches, compares, and drafts a proposal grounded in work I actually did, not generic AI output. Every project adds to the archive. Every archive makes the next project faster. What is the principle behind this?

The Concept

Documentation as Infrastructure is the idea that documentation has shifted from being a record of what happened to being the substrate through which work gets done. This is literal. In AI-assisted workflows, the quality of your documentation directly determines the quality of AI output. Vague docs produce hallucinating agents. Structured, specific docs produce agents that know what they are doing.

Matt calls this context density: the measure of relevant, structured information available per task. Too sparse, and the AI hallucinates. Too dense, and it drowns. The job of documentation becomes optimizing this density: making knowledge findable, structured, and just detailed enough.

A new class of files has emerged that embodies this shift. CLAUDE.md, .cursorrules, .github/copilot-instructions.md, llms.txt: these are documents that humans write and AI agents execute. They are simultaneously readable instructions and machine configuration. The documentation is the system.

Igor puts it sharply: “You cannot delegate what you cannot articulate.” When you try to hand work to an AI agent, every gap in your documentation becomes immediately visible. AI is, in this sense, a forcing function for organizational clarity. What used to be “tribal knowledge” (the stuff that lived in people’s heads and was “good enough” because humans could fill in the gaps) becomes a failure mode when you delegate to machines.

The Organizational Dimension

Igor’s Strategy as Protocol series takes this further. His argument: traditional strategy operates as invisible logic. Organizations say one thing and do another. The gap between stated values and actual behavior stays hidden because no one is forced to make it explicit.

AI changes this. When you try to encode strategy into protocols that an AI agent can follow, you are forced to articulate what was previously implicit. This transparency is the actual transformation, not a side effect. Igor describes an AI-Trust-Strategy Loop: articulation forces transparency, transparency enables challenge, challenge produces better strategy, better strategy earns trust, trust enables more delegation.

In his essay The Custodian Shift, Igor explores what happens to human roles when AI handles execution. The answer: humans shift from protagonists to custodians. The custodian does not deliver outcomes. The custodian tends conditions: Are the protocols still valid? Is there drift between what we documented and what is actually happening? When should the system stop?

This is the most important function in an AI-enabled organization. And it is the least prestigious. Career structures and organizational narratives reward the hero who delivers, not the custodian who maintains. Igor sees this as one of the central tensions of AI adoption.

He invokes Ursula K. Le Guin’s carrier bag theory of fiction: before the spear came the bag. Before the tool that forces energy outward, we made the tool that brings energy home. The container precedes the weapon. Documentation precedes execution.

Why It Matters

• Strategy-as-Protocol — Igor Schwarzmann on why strategy must be explicit, human-readable, and machine-executable. The forcing function of AI delegation.
• The Custodian Shift — Igor on what happens when the most important role carries the least prestige.
• PRD-Driven Context Engineering — Matt Gierhart’s methodology template for treating documentation as shared memory infrastructure between humans and AI.
• Context Engineering — Philipp Schmid’s definition of the discipline: designing dynamic systems that provide the right information, in the right format, at the right time.
• Effective Context Engineering for AI Agents — Anthropic’s engineering perspective on building context for agents.

The New Documentation Layer

• CLAUDE.md — Anthropic’s convention for project-level AI agent configuration. Loaded automatically by Claude Code at every session start.
• llms.txt — Jeremy Howard’s proposed standard (2024) for LLM-optimized website documentation. Like robots.txt, but for AI agents.
• The GTM Guide to AI Context Engineering — Maja Voje on using CLAUDE.md as a strategic onboarding file that pulls live business context.

Intellectual Lineage

Several threads converged to get us here:

• Docs-as-Code (mid-2010s): Anne Gentle pioneered treating documentation like code: version-controlled, reviewed, published through CI/CD. The core insight: docs that live alongside code stay alive. Docs in a wiki decay.
• Infrastructure-as-Code (2010s): Terraform, Ansible, Pulumi. The idea that infrastructure should be defined as declarative documents, not configured by hand.
• Living Documentation (2011+): Gojko Adzic’s Specification by Example coined the term. Cyrille Martraire’s Living Documentation (2018) systematized it. Documentation that auto-updates from code, staying synchronized without manual effort.
• Context Engineering (2024+): The discipline of managing what AI knows, when, and in what format. Gartner formally defined it in July 2025, predicting it will replace prompt engineering as the core AI skill.

The direction of causality reversed somewhere along this timeline. Documentation used to describe what code does. Now documentation prescribes what agents do.

Open Questions

The Prestige Problem. Custodianship (tending documentation, maintaining protocols, detecting drift) is the most important function in AI-enabled organizations and the least rewarded. How do you build career incentives around maintenance?

The Articulation Gap. Not everything can be documented. Ikujiro Nonaka’s distinction between tacit and explicit knowledge exists for a reason: some knowing is embodied, relational, situational. What happens to the knowledge that resists documentation?

Documentation Debt. Organizations already struggle with technical debt. Documentation debt (outdated protocols, contradictory instructions, orphaned files) may be worse. And unlike code, nobody has built the tooling to detect it.