🗺️ Onboarding to a Huge Terraform Codebase With AI

The worst day in any infrastructure job is day one on a codebase someone else built. You git clone, open the repo, and find 200 modules, four environments, a terragrunt.hcl you don’t understand, and a state file referencing resources nobody documented. The person who wrote it left in 2023. You need to make a change by Friday and you’re afraid to run terraform plan in case it does something.

This is where I lean on AI hardest — not to make changes, but to build a map. A model is a fast junior engineer who can read all 200 modules in the time it takes you to read one, and summarize how they fit together. The crucial discipline: its map is a hypothesis, and terraform plan is how you check it. You never let it touch state or run anything; you use it to get oriented faster.

Start with the shape, not the details

Before any single module, get the lay of the land:

find . -name '*.tf' | sed 's|/[^/]*$||' | sort -u
terraform state list | sed 's/\..*//' | sort | uniq -c | sort -rn

The first command lists every module directory; the second counts resource types in state. Paste both and ask:

Here’s the directory structure and a count of resource types in state. Give me a one-paragraph summary of what this infrastructure probably is, and identify the three or four most critical-looking modules I should understand first.

The model orients you in seconds: “This looks like a multi-account AWS setup; the network and eks modules are foundational, everything else depends on them.” That’s a week of poking around, compressed. It’s also a guess — but a guess that tells you where to point your own attention.

Trace dependencies it can actually see

The scariest question in a new codebase is “if I change this, what breaks?” AI can trace explicit dependencies from the code:

Here are these three modules’ main.tf and outputs.tf. Draw the dependency graph: which module’s outputs feed which module’s inputs? Flag anything that looks like a hidden coupling (remote state data sources, hardcoded ARNs).

Remote state references are the landmines:

data "terraform_remote_state" "network" {
  backend = "s3"
  config = {
    bucket = "acme-tf-state"
    key    = "network/terraform.tfstate"
  }
}

The AI flags these as cross-module couplings you’d otherwise miss until you broke one. Then you confirm with Terraform’s own view:

terraform graph | dot -Tsvg > graph.svg

The terraform graph output is ground truth; the AI’s narrative is the readable version. Cross-check them — where they disagree, trust the graph.

Pro Tip: Ask the AI to list every data "terraform_remote_state" and every hardcoded ARN or ID across the modules. Those are the implicit dependencies that make “small” changes dangerous, and they’re exactly what a deterministic grep plus an AI summary surfaces together far faster than reading by hand.

Have it explain the parts that look insane

Every old codebase has a module that makes you say “why on earth.” Often there’s a good reason buried in the history. Ask:

This module uses a for_each over a flattened nested map and a dynamic block three levels deep. Explain in plain English what it produces and why someone might have written it this way.

locals {
  rules = flatten([
    for sg_key, sg in var.security_groups : [
      for rule in sg.rules : {
        sg_key = sg_key
        rule   = rule
      }
    ]
  ])
}

The model decodes the flatten-into-for_each pattern — “this builds one rule resource per (group, rule) pair so each gets a stable address.” Understanding that in two minutes instead of an hour is the entire value. But verify the explanation against a real plan before you act on it; a confident wrong explanation is the trap.

The first change: plan, don’t apply

When you finally make your Friday change, the AI helps you predict the plan and then you read the real one:

terraform plan -out=tfplan
terraform show -json tfplan | jq '[.resource_changes[].change.actions] | flatten | group_by(.) | map({(.[0]): length})'

Ask the AI: “I expect my change to only modify the autoscaling group. Here’s the plan summary — does anything else change? Anything destroyed?” If the plan touches resources you didn’t expect, stop — the map was incomplete. The plan is always the authority over both your mental model and the AI’s.

The boundary matters most when you’re lost

Being new and uncertain is precisely when it’s tempting to let the AI “just figure it out” with real access. Don’t. It reads code, summarizes structure, and explains patterns. It does not get the backend credentials, does not run apply, and does not get state-write access. Everything it tells you is a hypothesis you confirm with terraform plan and terraform graph — deterministic tools that can’t be wrong about your actual infrastructure. A fast junior engineer drawing you a map is invaluable; a junior with prod keys and no context is how brand-new engineers cause outages.

For onboarding-oriented prompts, see the prompts library and prompt packs. The prompt workspace is handy for keeping a running set of “explain this module” prompts as you go. More under AI for Terraform.

Conclusion

Inheriting a giant Terraform estate is a reading problem, and AI reads faster than you ever will — use it to build a map of the modules, dependencies, and scary patterns in hours instead of weeks. But the map is a hypothesis: confirm dependencies with terraform graph, confirm your first change with terraform plan, and never hand the model state or credentials. It’s the fast junior who gets you oriented; the plan is what keeps you safe.