Most engineering documentation is procedural. Step one, step two, step three. How to deploy. How to roll back. How to scale a node pool. The steps are documented because they need to be reproducible, and reproducibility is the point.
AI tools are becoming good at runbooks. Given the right context — the system, the goal, the constraints — they can draft a procedure that covers the common cases. They can turn a description of a change into a step-by-step guide. They can even execute the steps.
What they can’t do is explain why.
The context that gets lost
Decisions have rationale. The architecture choice between option A and option B. The constraint that ruled out the simpler solution. The thing that was tried and didn’t work, and why. The tradeoff that was made deliberately rather than by default.
That context lives in the heads of the people who made the decisions. When they leave — or when the project moves past that phase — the context leaves too. What remains is the system as it is: the Terraform modules, the Kubernetes configs, the CI/CD pipelines. The documentation, if any, describes what each piece does. It doesn’t explain why it’s built that way.
Runbooks are the clearest example of this. A runbook tells you how to perform an operation. It doesn’t tell you what assumptions the operation makes, what would make the steps unsafe, or what the person who wrote it knew that you don’t. Follow a runbook in a system you don’t fully understand and you’re executing steps in a context you might not have.
What AI assistance reveals about documentation
Using AI tools heavily in platform engineering work — I use Claude Code and Cursor regularly in my work — sharpens something about documentation quality. When I ask an AI assistant to help with a system it hasn’t seen before, the quality of the output is directly proportional to the quality of the context I can give it.
Runbooks and configuration files are context. But what makes the output trustworthy is the rationale behind them. Why does the node pool have this configuration? What would break if this parameter changed? Is this a deliberate choice or a historical accident?
When I can give that context — because it’s written down, because I remember it, because it’s in a commit message or an architecture document — the AI assistance is genuinely useful. When I can’t — because the rationale was never captured — the AI generates something plausible that may or may not be appropriate for this specific system.
That’s the documentation gap AI assistance makes visible: not missing steps, but missing reasons.
What rationale documentation looks like
Rationale documentation is not long. It doesn’t need to be a formal architecture decision record for every configuration choice, though ADRs are useful for significant decisions. It’s the one sentence — in a comment, in a commit message, in a README section — that explains the why.
Not: “VPC peering is configured between these two projects.”
But: “VPC peering rather than Shared VPC here because the client’s security team required project-level IAM isolation and didn’t permit shared VPCs across their organisational boundary.”
The second version is ten words longer. It’s the difference between “this is what it is” and “this is why it’s this way.” Someone coming to the system later — human or AI — can reason about whether the constraint still applies, whether the decision was right, and whether changing it would be appropriate.
The decisions worth capturing
Not everything needs rationale documentation. The decision to use for_each over count in Terraform is a practice, not a decision with project-specific context. But some decisions do:
Architecture choices where the alternative was seriously considered. If you chose GKE over self-managed Kubernetes, and the reason matters — the client’s support requirements, the team’s operational capacity — write it down.
Security constraints that shaped the implementation. A network configuration that looks unusual probably looks that way because of a compliance requirement. If that requirement isn’t documented, someone will “clean it up” and create an incident.
Workarounds that are deliberate rather than accidental. A configuration that looks wrong but is correct given a specific behaviour of the platform. Without the rationale, it will be changed.
Tradeoffs made under time or cost pressure. Something that could have been better but wasn’t because the constraint was binding. If the constraint is lifted later, the improvement is possible — but only if the decision was logged as a tradeoff rather than treated as permanent.
The connection to AI-assisted operations
As AI tools become more present in DevOps workflows — generating changes, reviewing configurations, assisting with incident response — the quality of the rationale in the codebase determines the quality of the assistance.
An AI tool given a well-documented system, with rationale captured alongside the configuration, can reason about changes accurately. Given a system where the why is absent, it generates plausible steps against unknowable constraints.
The rationale isn’t for the AI. It’s for any future reader — human or AI — who needs to understand the system well enough to modify it safely. Writing it is the discipline that makes that possible.
Write the runbook, yes. But write the rationale too.