Using opencode with Terraform: a practical guide

opencode is a terminal coding agent you start with opencode inside a Terraform repository. It reads project instructions from AGENTS.md, so you can encode module boundaries, state rules, and validation commands. This guide walks through a practical workflow for using opencode on Terraform projects. For a general walkthrough, see How to use opencode: a step-by-step guide.

Why opencode fits Terraform projects

Terraform codebases are mostly declarative HCL with a small set of moving parts: providers, resources, data sources, variables, outputs, modules, and backend/state settings. opencode is useful here because it works directly in the project folder, reads AGENTS.md, and can inspect the whole repository before changing .tf files. It handles repetitive HCL edits well: renaming a variable across a root module and its child modules, moving a set of resources into a new module, updating a provider version, generating missing variables or outputs, and adding tags to every resource. It can read existing variable and output definitions to keep a consistent interface, and it can follow provider version constraints already in required_providers. Because Terraform has fast local feedback through terraform fmt, terraform validate, and terraform plan, the agent can iterate safely when you ask it to run those commands after each edit. For state, it can run plan and show exactly which resources will change, but you must make the rules explicit. The main value is not generating new infrastructure from a blank page; it is using repository context to keep changes consistent with your existing module contracts and naming conventions.

Set up AGENTS.md for Terraform

Create an AGENTS.md file at the repository root. opencode reads it as project instructions, so keep it specific and short. For Terraform, the file should state the exact commands for build, test, lint, the folder layout, and rules that prevent unsafe state or apply behavior.

# AGENTS.md

## Commands
- Validate: terraform fmt -check -recursive && terraform validate
- Lint: tflint --recursive
- Test: terraform test
- Plan: terraform plan -out=plan.tfplan

## Layout
- modules/ contains reusable modules; each module has variables.tf, outputs.tf, main.tf
- environments/ contains root modules (dev, staging, prod)
- Do not create new environments without approval.

## Terraform rules
- Always run terraform plan before apply and show the diff.
- Do not edit .terraform.lock.hcl by hand; let Terraform update it.
- Pin provider versions in required_providers.
- Keep state configuration in backend.tf; never move state without confirmation.
- Prefer variables over hard-coded values; add outputs for values used elsewhere.

This gives the agent enough context to run the right checks and avoid common mistakes. The commands section should match your actual toolchain: if you use terraform fmt -recursive instead of -check, use that. The layout section prevents the agent from placing environment-specific code into shared modules. The rules section is the safety boundary; without it, the agent may edit backends or run apply when you only asked for a plan. If you use different environments or a remote backend, include that here; if you use Terragrunt, spell out the wrapper command too. The file should not be a full architecture document; it should be the minimum contract the agent needs before touching code.

Iterate with plan, small steps, and review

Start opencode in the repo root and give it one focused task at a time. Ask for a small change rather than refactor the whole network. The agent will edit files, then you should have it run the validation commands and show the diff. Review the plan output before any apply. A reliable loop is: request a change, let the agent edit only the necessary files, run terraform fmt -check -recursive, terraform validate, tflint --recursive, and terraform plan -out=plan.tfplan, then inspect the diff. If the plan shows unexpected resource replacement or a large number of changes, stop and ask for a smaller change. For example, when moving resources into a module, ask the agent to show the exact terraform state mv commands it would run, and do not let it run state moves without showing them first. The plan should be clean before you proceed.

Examples of good prompts:

• Add a private_subnets variable to the VPC module and thread it through the staging root module, then run fmt, validate, and plan.
• Update the AWS provider version constraint in all environments and run terraform plan to show any changes; do not apply.
• Move the security group resources from environments/staging/main.tf into a new module under modules/security-group, add variables and outputs, and run terraform test.
• Add S3 lifecycle rules to the module that manages state bucket backups, then show the diff and terraform plan output.
• Fix all tflint warnings in modules/networking and show a summary of the changes.

What opencode does well and where to be careful

opencode is good at structural HCL edits, but Terraform has sharp edges around state and provider behavior.

The agent is also good at adding missing outputs, generating terraform-docs sections, and converting repeated inline blocks into dynamic blocks. Watch it closely when it touches backend.tf, provider lock files, terraform.tfstate, or remote state data sources. It may assume a clean apply path and try to run terraform apply -auto-approve; your AGENTS.md should forbid that unless you explicitly approve. Another pitfall is large multi-resource refactors that produce huge plan diffs; ask for small, verifiable steps. When the agent updates provider versions, it may also update the lock file and cause a large diff; ask it to show the lock file changes separately. When adding lifecycle rules, ensure prevent_destroy does not conflict with existing ignore_changes or replace_triggered_by. In for_each or count changes, a key change can cause resource replacement; ask for a plan that shows no unexpected replacement.

Verify Terraform changes safely

Treat the agent’s edits like any other code change. Have opencode run terraform fmt -check -recursive to enforce style, terraform validate to catch HCL and interpolation errors, tflint --recursive for provider-specific warnings, and terraform test when you have test files in modules. For changes that affect live infrastructure, always ask for terraform plan -out=plan.tfplan and then terraform show plan.tfplan so you can review the exact actions without re-running plan, including resource actions and any known-after-apply values. If you use a remote backend, confirm the plan is running against the right workspace and state file. Ask the agent to show the diff before and after commands; if terraform validate fails, it should reply with the exact error and fix only that. For modules, run terraform test from the module directory or the root to verify variable contracts and outputs without applying real infrastructure. Use terraform plan -detailed-exitcode only in scripts, not as a replacement for human review.

Run multiple agents with AgentVera

AgentVera is a desktop app that runs opencode and other CLI agents side by side in real terminal panels. For Terraform work, the most useful parts are parallel git worktrees, so several agents can edit different modules or environments without overwriting each other; automatic code review with file:line findings, which helps catch HCL mistakes and provider/state issues before they reach apply; and token budgets, which keep plan-and-apply iterations from consuming unlimited context. The Git view ties worktrees, commits, and pull requests to each agent’s changes, so you can review infrastructure changes like normal code. For more on parallel agents, see the guide on running AI coding agents in parallel.

Wrap-up

opencode works well for Terraform when you treat it like a junior engineer who has read your AGENTS.md: give it one focused task, require validation commands, and review every plan diff. The key is to put your Terraform conventions, commands, and safety rules in AGENTS.md, then iterate in small steps. Use terraform fmt, validate, plan, and test as the primary verification loop, and only apply when the diff is small, expected, and approved. By encoding your Terraform conventions in AGENTS.md and working in focused increments, opencode becomes a reliable pair for infrastructure changes without the usual agent surprises.