AI-Enhanced Infrastructure: Why Markdown Beats Terraform Modules

November 2025 · Masrur Hossain

After a decade of building and operating cloud infrastructure at scale, I've reached a conclusion that would have seemed heretical just two years ago: we should replace most of our Terraform modules with markdown files.

This isn't about abandoning infrastructure-as-code. It's about recognizing that the way we write and manage infrastructure is fundamentally changing with the rise of capable AI agents.

The Problem with Terraform Modules

Terraform revolutionized infrastructure management. But as our infrastructure has grown more complex, so have our Terraform codebases. We've created elaborate module hierarchies, abstract interfaces, and reusable components—all in the name of DRY principles and maintainability.

Here's what we've actually built: cognitive load machines.

Consider a typical scenario. You need to deploy a new service that requires:

You reach for your organization's Terraform modules. The EKS module has 47 input variables. The RDS module has 63. Each module was designed to handle every possible use case across your organization, which means none of them do exactly what you need without extensive configuration.

Worse, when you use a prebuilt module, you inherit its opinions. You get outputs you don't need. You create resources you didn't ask for. You spend hours reading module source code to understand why that security group rule exists or why that IAM policy is attached.

Every Infrastructure Is Different

Here's the uncomfortable truth that module authors rarely acknowledge: every infrastructure deployment is unique.

Yes, there are patterns. Yes, there are best practices. But the specific combination of requirements for any given service—its performance characteristics, compliance needs, cost constraints, integration points, and operational requirements—is almost always different from the last one.

Prebuilt modules optimize for reusability across these differences. But that optimization comes at a cost: they become complex, over-parameterized, and difficult to reason about. The abstraction that was supposed to simplify your infrastructure becomes another layer you have to understand and debug.

Infrastructure is expected to change and grow. Modules that were perfect at creation become technical debt as requirements evolve. You end up with version pinning hell, upgrade treadmills, and the constant fear that updating a shared module will break something in production.

The Markdown Alternative

What if instead of encoding our infrastructure in HCL modules, we described it in plain language?

Consider a markdown file like this:

# Payment Service Infrastructure

## Compute
- Kubernetes deployment in the `payments` namespace
- 3 replicas minimum, auto-scale to 10 based on CPU (target: 70%)
- Resource requests: 500m CPU, 1Gi memory
- Resource limits: 2 CPU, 4Gi memory
- Liveness probe: /health endpoint, 10s interval
- Readiness probe: /ready endpoint, 5s interval

## Database
- PostgreSQL 15 on RDS
- Instance: db.r6g.large (production), db.t3.medium (staging)
- Multi-AZ enabled for production
- Automated backups: 7 days retention
- Enable Performance Insights

## Storage
- S3 bucket for payment receipts
- Lifecycle: move to Glacier after 90 days, delete after 7 years
- Enable versioning
- Block all public access

## Monitoring
- Alert if error rate exceeds 0.1% over 5 minutes
- Alert if p99 latency exceeds 500ms
- Alert if pod restarts more than 3 times in 10 minutes

This document is:

AI Agents as Infrastructure Operators

This is where the paradigm shift happens. AI agents have become remarkably capable at:

When you give an AI agent a well-written markdown specification, it can generate Terraform code that does exactly what you need—nothing more, nothing less. No inherited complexity. No unwanted resources. No 47-variable module interfaces.

The generated code is specific to your use case. It's readable. It's auditable. And if your requirements change, you update the markdown and regenerate.

The Critical Practice: Plan Review

This approach requires discipline. AI agents are powerful but not infallible. The critical practice is:

Always ask AI agents to create a plan and review the plan before approving.

Never let an AI agent apply infrastructure changes without human review. The workflow should be:

  1. Update your markdown specification
  2. Ask the AI agent to generate a plan
  3. Review the generated code and the execution plan
  4. Approve only after understanding every change

This isn't different from reviewing pull requests or Terraform plans today. The difference is that the human focuses on intent and outcomes rather than implementation details.

When This Works Best

This approach shines when:

It may not be the right fit for organizations that have heavily invested in module ecosystems and have stable, rarely-changing infrastructure patterns.

Key Takeaway

The goal isn't to eliminate Terraform or infrastructure-as-code. It's to shift the source of truth from complex HCL modules to human-readable specifications that both engineers and AI agents can understand and act upon. The code becomes an artifact of the specification, not the specification itself.

Getting Started

If you want to experiment with this approach:

  1. Start with a new, isolated piece of infrastructure
  2. Write a markdown file describing exactly what you need
  3. Use an AI agent to generate the Terraform (or use direct API calls)
  4. Review the generated code carefully
  5. Apply, observe, and iterate

You might find, as I have, that the clarity of thinking required to write a good specification is itself valuable—and that the resulting infrastructure is simpler, more understandable, and easier to maintain than what any module could have provided.