Skip to main content

ADR: LLM-Docs Adoption for Infrastructure as Code

Status: Accepted
Date: 2026-06-10
Author: Technical Documentation Engineer

Context​

Terraform modules are a form of reusable infrastructure code, yet documentation for the 12 modules in terraform-aws/modules/ has diverged significantly from source. The documentation gap creates friction for infrastructure consumers (Cloud Platform engineers, DevOps operators) who must read raw HCL to discover module capabilities, required inputs, and outputs.

The Problem: Manual documentation and HCL source code are two separate systems of record. When module signatures evolve, documentation lags. Result: consumers re-read .tf files on every integration; time-to-first-deploy increases; inference errors occur.

Measured Gap: Review of 12 modules (ACM, ALB, CloudFront, ECS, EFS, KMS, S3, SFTP, SSO, VPC, WAF, Web) identified 12 modules with outdated or missing documented examples and input/output descriptions. This gap motivates the decision.

Decision​

Adopt LLM-compiled documentation (llms.txt generated via gen-llms-txt.sh) as the single source of truth (SSOT) for infrastructure module discovery:

  1. Compilation: A deterministic script (gen-llms-txt.sh) extracts structured metadata from source HCL, module structure, and README templates
  2. No Manual Drift: Human writers maintain only the source HCL; compilation renders the index
  3. AI Discoverability: The compiled llms.txt becomes a structured artifact that AI agents (and human consumers) use to locate modules, understand capabilities, and make architecture decisions
  4. Version-Paired: Regenerated on each commit to modules/**/*.tf; terraform-aws release-please per-package ensures module versions and docs stay synchronized

What-If Missing​

If we do NOT adopt LLM-compiled documentation, the measured documentation gap recurs:

  • 12-module gap persists: Each module lacks discoverable input/output documentation
  • Consumer friction increases: Infrastructure teams waste hours re-reading HCL to understand module behavior
  • AI agents cannot discover: Both human and AI consumers re-parse .tf files instead of using a canonical index
  • Drift continues: Code and docs diverge on each release; manual update burden grows

Business Value​

  • Time-to-first-deploy reduction (qualitative): Infrastructure teams onboard new modules in minutes instead of hours by consulting the SSOT index
  • AI-discoverable IaC: Public registry modules become discoverable by AI agents via llms.txt, reducing friction for multi-team deployments
  • Documentation maintenance burden: Compilation removes the need for manual README updates; drift-free by design

Consequences​

Positive:

  • Drift Resistance: Documentation cannot diverge from code; compilation is deterministic (SHA256-verified)
  • Automation: Agents can discover terraform-aws modules directly from llms.txt without parsing raw HCL
  • Faster Onboarding: Infrastructure teams access canonical input/output/examples in seconds, not hours of HCL reading
  • Public Registry Compatibility: Modules published to Terraform Registry remain readable by human review; llms.txt index improves AI consumer discoverability

Negative / Mitigations:

  • Script Dependency: Regeneration relies on gen-llms-txt.sh (owned by ADLC Commerce plugin). Mitigation: script is version-pinned in CI; fallback: manual README updates survive script failure
  • Compilation Latency: Each PR triggers regeneration (<10s overhead). Acceptable for CI-gated workflows

References​

  • Script: /Volumes/Working/projects/adlc-framework/.claude/plugins/commerce/scripts/gen-llms-txt.sh
  • CI Integration: .github/workflows/docs-sync.yml (Regenerate llms.txt via gen-llms-txt.sh step)
  • Compiled Output: terraform-aws/llms.txt (179 pages, deterministically regenerated)
  • Inventory: 12 terraform-aws modules indexed; 2 accounts documented; identity-plane as composition root