Why Missing Infrastructure Documentation Breaks AI Agents

Your new hire spends their first two weeks reading runbooks, asking in Slack why that one subnet is tainted, and shadowing the on-call engineer before they touch production. Your AI agent gets none of that. It gets a repo, a prompt, and maybe twenty minutes before someone expects a pull request.

That gap is why infrastructure documentation ai agents rely on has suddenly become a production issue instead of a nice-to-have. For years, thin docs were survivable because a human filled in the blanks: they remembered why the staging cluster has a weird node pool, or they just asked the person who set it up. Agents can't do either. They read what's in the repo and nothing else, and when the repo is quiet about the parts that matter, they guess.

The undocumented Terraform module is a trap, not a shortcut

Every infra team has at least one Terraform module that works because everyone already knows not to touch it wrong. No comment explains why count is hardcoded to 3, no README mentions that the module manages a resource shared with another team's stack, no tag says this environment is exempt from the naming convention because a legacy integration depends on the old name.

A human engineer picks up on these signals from tribal memory, or they pause and ask. An AI agent asked to "add a new environment following the existing pattern" will copy the pattern literally, including the parts that were never meant to be copied. It doesn't know the count is hardcoded because of a quota ceiling, so it raises it. It doesn't know the resource is shared, so it duplicates it. The output looks plausible, runs terraform plan clean, and then breaks something two teams over.

# modules/eks-cluster/main.tf
resource "aws_eks_node_group" "workers" {
  # Capped at 3: shared quota with the ml-training account, see INFRA-4021
  scaling_config {
    desired_size = 3
    max_size     = 3
    min_size     = 1
  }
}

That one-line comment is the difference between an agent that respects the constraint and one that "fixes" it. Without it, the constraint exists only in someone's head, or in a ticket the agent never sees unless you point it there.

Kubernetes runbooks written for humans skip the parts agents need

Most Kubernetes runbooks are written by people who already understand the cluster, for people who already understand the cluster. They say "restart the pod and check the logs" without saying which pod, which namespace, or what a bad log line actually looks like. A human on-call engineer fills in those gaps from memory of the last three incidents. An agent has no last three incidents. It has the text on the page.

When a runbook says "if the ingress controller is unhealthy, roll it," a human knows this means checking kubectl get pods -n ingress-nginx, confirming which deployment owns the controller, and watching for the specific CrashLoopBackOff pattern that means a bad config versus the one that means a resource limit. An agent given only that sentence either does nothing useful or takes the most literal, most destructive interpretation available: a full rollout restart, at 2am, without checking whether the actual cause was something a restart won't fix.

# runbooks/ingress-unhealthy.yaml
trigger: "IngressControllerErrorRateHigh"
check:
  - kubectl get pods -n ingress-nginx -l app.kubernetes.io/component=controller
  - kubectl logs -n ingress-nginx <pod-name> --tail=100 | grep -i "upstream timed out"
known_causes:
  - pattern: "upstream timed out"
    likely_cause: "backend service overloaded, not the controller"
    action: "scale the backend deployment, do not restart ingress-nginx"
  - pattern: "OOMKilled"
    likely_cause: "controller memory limit too low after traffic growth"
    action: "raise memory limit in values.yaml, then restart"
restart_only_if: "no known pattern matches and error rate is climbing"

A runbook structured like this gives an agent an actual decision tree instead of a vibe. It also happens to make the runbook better for the next human on call, which is the honest objection to all of this: didn't we already write these docs for people?

The objection: "we already have docs, humans manage fine"

Most infra teams will say they have documentation, and they're not wrong. The problem is that human-oriented docs assume a reader who can tolerate ambiguity, ask a follow-up question in Slack, and pattern-match from experience the doc never states outright. An agent can't ask a follow-up unless you've built that loop, and it has no experience beyond its context window. The docs aren't missing, they're missing the specific layer that made them work for humans: the unstated context.

You don't need to rewrite everything. You need to surface the assumptions that were always implicit and were never a problem until something without institutional memory started reading the file.

Start with what the agent will touch first

Don't try to document the entire infrastructure estate before your first agent-assisted change. Start narrow:

• Add a comment to every Terraform resource with a magic number, hardcoded value, or exemption from your standard pattern, explaining why.
• Turn your top three runbooks (the ones paged most often) into explicit if-this-then-that trees instead of prose.
• Note ownership and blast radius on shared resources: what else breaks if this changes.

Then watch what the agent gets wrong on its first few tasks. Those mistakes are a direct map of your documentation gaps, more accurate than any audit you'd do by hand.

This matters because the agents aren't going away, and the infrastructure they're being pointed at was never written down for an audience with zero tolerance for ambiguity. The teams that fix this now ship agent-assisted infra changes safely. The teams that don't will keep discovering their undocumented assumptions the expensive way, in production.