For most of modern software history, documentation existed for one core reason: human written code was expensive to create and difficult to replace. Developers carried complex mental models in their heads. Code was the physical imprint of those models. Documentation was the act of extracting that fragile, human knowledge and making it reusable.
Documentation existed to protect human intellectual property.
That logic is breaking.
With systems like OpenAI Codex and other AI coding agents producing usable code in minutes, the implementation itself is no longer the scarce asset. Code can be regenerated, rewritten, or discarded with very little cost. What remains hard, slow, and deeply human is deciding why a system exists, what it must guarantee, and where its limits lie.
Documentation has to change accordingly.
Why traditional documentation no longer fits
Classic documentation focused on explaining how the code works internally. This made sense when:
- Only the original author fully understood the system.
- Design decisions were embedded directly in the code.
- Reuse depended on another human being able to mentally simulate the implementation.
In an AI assisted world, implementation details are the easiest thing to recover. Given a clear specification, they can be produced again and again. What cannot be reconstructed reliably is intent, context, and constraint.
You can regenerate code.
You cannot regenerate meaning.
What now deserves documentation
The focus of documentation shifts away from mechanics and toward judgement. What humans still produce, and therefore must document, includes:
- Purpose: Why this system or feature exists at all
- Constraints: What it must never do, even if a future implementation could
- Invariants: Conditions that must always remain true
- Trade offs: What was consciously not optimised and why
- Failure boundaries: How the system is allowed to fail and how it is not
- Ownership: Who is responsible for outcomes and behaviour
These are not implementation details. They are decisions about values, risk, and direction. AI can follow them, but it cannot originate or own them.
Upfront design quietly returns
As code generation accelerates, something unexpected happens. Design becomes the bottleneck again.
The modern development loop increasingly looks like this:
- Humans define intent, constraints, and acceptable behaviour.
- AI generates code rapidly.
- Humans review outcomes and refine intent.
Structurally, this resembles the old waterfall idea where design precedes implementation. The difference is scale and speed. The cycle is no longer months long. It can be hours, or even minutes.
Agile has not vanished. It has moved upward. Iteration now happens primarily at the level of intent and specification, not at the level of syntax.
This shift has been articulated clearly by people closest to the tools. Andrej Karpathy has described it as a phase change in software creation, where developers increasingly “program in English” while AI handles the mechanical translation into code. In this framing, code becomes fluid and disposable, while human direction provides stability and coherence.
https://karpathy.ai/
Intentional design or emergent design
This shift raises a natural question. If code is cheap and disposable, do we now need rigid upfront design, or is emergent design still acceptable?
The distinction turns out to be misleading.
The real divide is not between intentional and emergent design. It is between explicit and implicit intent.
Emergent design worked well in the past because the same humans stayed close to the system over time. Intent lived in people’s heads and slowly shaped the structure. That continuity is weaker when large parts of the system are generated by machines and rewritten frequently.
In this environment, design may still emerge, but intent must be explicit.
Intentional design today does not mean big upfront architecture or locked in decisions. It means writing down what you are trying to achieve before generating code, naming constraints early, and making value judgements visible rather than letting them accrete silently.
Emergent design without explicit intent becomes risky. AI accelerates feedback loops so quickly that systems can converge on something coherent but wrong. Without documented intent, behaviour drifts, priorities shift across iterations, and nobody can clearly explain why the system is the way it is.
A useful way to think about this is:
- Intent is deliberate and slow
- Implementation is fast and disposable
- Structure may emerge, but boundaries are fixed
You intentionally design the invariants. Everything else is allowed to evolve.
What humans now produce
Humans are not being removed from the process. Their output is changing.
They now produce:
- Clear problem statements
- Behavioural specifications
- Architectural intent
- Ethical and safety boundaries
- Coherence across many fast iterations
This aligns with Karpathy’s observation that the hardest part of modern software work is no longer writing loops or APIs, but knowing what to ask for and how to judge the result.
A closely aligned idea appears in Rich Sutton’s essay The Bitter Lesson, which shows that long term progress in computing comes from scalable methods rather than hand crafted detail. In that framing, human effort shifts away from micromanaging implementations and toward defining objectives and evaluation criteria.
http://www.incompleteideas.net/IncIdeas/BitterLesson.html
Documentation as the durable artifact
The implication is simple but uncomfortable. Documentation is no longer a secondary artifact attached to code. It becomes the primary store of understanding.
Code is transient.
Intent is durable.
If teams continue documenting implementation minutiae while allowing intent and constraints to remain implicit, they will accumulate large volumes of functional code with no shared understanding of what it is actually for. That is not technical debt. It is organisational amnesia.
When code is easy to replace, documentation becomes the thing worth preserving.
Written for KiwiGPT.co.nz — Generated, Published and Tinkered with AI by a Kiwi