This guide helps you understand how IaC Spec Kit approaches infrastructure specifications using generic terms rather than cloud-specific service names.
Important: You don't need to memorize or manually apply these guidelines. IaC Spec Kit is designed to guide AI assistants to follow these patterns when generating specifications through commands like /iac.specify. This guide helps you:
- Understand the approach IaC Spec Kit encourages AI assistants to follow
- Review and refine AI-generated specifications more effectively
- Provide better input by knowing what the AI is optimizing for
IaC Spec Kit's commands and templates are structured to help AI assistants generate specifications following these patterns. While AI assistants may not always follow them perfectly, IaC Spec Kit nudges them in the right direction. You focus on describing what you need—IaC Spec Kit helps the AI structure it appropriately.
Infrastructure specifications face a unique challenge compared to application development:
- Application specs can often be completely tech-agnostic: "Users need to see their data in real-time" doesn't assume React, Vue, or any specific framework
- Infrastructure specs need some technical context: decisions like "managed vs self-managed database" or "serverless vs VMs" affect costs, operations, and feasibility
The key principle: Use generic infrastructure terms in specifications, translate to cloud-specific services in plans.
You might already know your cloud provider (e.g., IBM Cloud or AWS), but your spec should describe requirements using generic terms like "managed database" or "object storage" instead of cloud-specific service names like "RDS", "S3", or "Cloud SQL".
The question is: How much technical detail belongs in the specification vs the plan?
IaC Spec Kit encourages a balanced approach. The toolkit's commands and templates guide AI assistants to include certain types of information while avoiding others:
The toolkit guides AI assistants to include architectural patterns and service categories that significantly impact your requirements:
Compute Models:
- "Serverless functions" vs "Virtual machines" vs "Containerized workloads"
- "Auto-scaling compute" vs "Fixed capacity"
Data Storage:
- "Managed database service" vs "Self-managed database on VMs"
- "Relational database" vs "NoSQL database" vs "Time-series database"
- "Object storage" vs "Block storage" vs "File storage"
Networking:
- "Content delivery network for static assets"
- "Load balancer for traffic distribution"
- "Private network isolation"
Operations:
- "Automated backups with point-in-time recovery"
- "Multi-zone deployment for high availability"
- "Monitoring and alerting infrastructure"
Why include these? They affect cost, operational complexity, and feasibility. A team comfortable with VMs might struggle with serverless, affecting timeline and risk.
The toolkit guides AI assistants to avoid cloud provider-specific services or implementation details in specifications:
Generally discouraged:
- Cloud providers: "AWS", "Azure", "GCP", "IBM Cloud"
- Specific services: "RDS", "Lambda", "S3", "EKS", "Cloud Run", "Azure Blob Storage"
- Service tiers: "db.t3.micro", "F1 instance", "Standard_B2s"
- Provider features: "AWS WAF rules", "Azure Front Door", "GCP Cloud Armor"
- IaC tools: "Terraform modules", "CloudFormation templates", "Pulumi programs"
Why avoid these? They belong in the implementation plan (generated by /iac.plan), where the AI researches the specific cloud provider and makes informed technical decisions based on available services, pricing, and features.
These examples show the patterns that IaC Spec Kit encourages AI assistants to follow. You don't need to write specs this way yourself—just describe your needs, and the toolkit helps the AI structure them appropriately.
❌ Too Cloud-Specific:
"Use AWS RDS PostgreSQL with db.r5.large instance type in Multi-AZ configuration with 500GB GP3 storage"
✅ Tech-Agnostic with Appropriate Detail:
"Managed relational database service (PostgreSQL-compatible) with automated backups, point-in-time recovery, and multi-zone deployment for high availability. Estimated capacity: 4 vCPU, 16GB RAM, 500GB storage."
Why it works: Specifies requirements (managed service, HA, backup capabilities) and sizing without locking into AWS RDS.
❌ Too Vague:
"Needs to be scalable"
❌ Too Cloud-Specific:
"Deploy on AWS Lambda with 512MB memory and 30-second timeout"
✅ Tech-Agnostic with Appropriate Detail:
"Serverless compute for event-driven processing. Each invocation processes 1-100 records, requires 512MB memory, completes within 30 seconds. Must auto-scale to handle 0-10,000 requests/minute."
Why it works: Specifies the compute model (serverless), performance requirements, and scale without choosing Lambda, Cloud Functions, or Azure Functions.
❌ Too Cloud-Specific:
"Use S3 Standard storage class with lifecycle policies to move to Glacier after 90 days"
✅ Tech-Agnostic with Appropriate Detail:
"Object storage for media files with automatic tiering to archive storage after 90 days. Hot storage: <100ms access latency. Archive storage: retrieval within 12 hours acceptable. Estimated 1TB initially, growing 100GB/month."
Why it works: Describes storage characteristics (object storage, tiering, latency) without specifying S3/Glacier.
❌ Too Cloud-Specific:
"Use AWS VPC with 10.0.0.0/16 CIDR, public subnets in us-east-1a and us-east-1b, NAT Gateway for private subnet egress"
✅ Tech-Agnostic with Appropriate Detail:
"Isolated virtual network with public and private subnets across multiple availability zones. Public subnets host load balancers, private subnets host application and database resources. Private resources require outbound internet access for updates."
Why it works: Specifies network topology and isolation requirements without dictating VPC or specific subnet configurations.
IaC Spec Kit's commands and templates encourage AI assistants to follow these patterns. Understanding them helps you provide better input and review the output effectively.
IaC Spec Kit encourages describing service categories and characteristics rather than naming specific services:
| Instead of... | Use... |
|---|---|
| "AWS ECS Fargate" | "Managed container orchestration service (serverless model preferred)" |
| "Azure Application Gateway" | "Load balancer with SSL termination and path-based routing" |
| "Google Cloud Storage" | "Object storage with 99.99% availability SLA" |
| "IBM Databases for MySQL" | "Managed relational database (MySQL-compatible) with automated backups" |
IaC Spec Kit encourages focusing on capabilities and performance rather than specific configurations:
| Instead of... | Use... |
|---|---|
| "Use CDN" | "Content delivery network to serve static assets with <50ms latency globally" |
| "Enable auto-scaling" | "Compute resources must scale from 2 to 20 instances based on CPU utilization (target: 70%)" |
| "Configure monitoring" | "Monitoring infrastructure to track response times, error rates, and resource utilization with 1-minute granularity" |
IaC Spec Kit encourages emphasizing desired outcomes rather than implementation details:
| Instead of... | Use... |
|---|---|
| "Set up CloudWatch alarms" | "Alert operations team when response time p95 exceeds 500ms or error rate exceeds 1%" |
| "Configure RDS automated backups" | "Database backups taken daily with 30-day retention and point-in-time recovery capability" |
| "Implement IAM roles" | "Service components must use temporary credentials with least-privilege access following the principle of separation of duties" |
Sometimes you have legitimate technical requirements that should be included in specifications. IaC Spec Kit helps AI assistants recognize these situations:
Acceptable:
"Database must support encryption at rest using FIPS 140-2 validated cryptographic modules"
Why: Compliance requirement that affects provider selection.
Acceptable:
"Must integrate with existing MySQL 8.0 database using native replication protocol"
Why: Technical constraint from existing systems.
Acceptable:
"Team has expertise in containerized deployments but not serverless architectures. Prefer container-based solutions."
Why: Affects risk, timeline, and operational success.
Acceptable:
"Budget constraint of $500/month favors serverless or managed services over self-managed infrastructure to minimize operational overhead"
Why: Technical decision directly driven by business constraint.
IaC Spec Kit encourages AI assistants to generate success criteria that are measurable and technology-agnostic. Here's what to expect:
✅ Good Success Criteria:
- "Infrastructure deploys in under 15 minutes"
- "System handles 10,000 requests/second with p95 latency under 200ms"
- "Database failover completes in under 5 minutes with zero data loss"
- "Costs remain under $500/month for projected traffic (5,000 daily users)"
❌ Bad Success Criteria:
- "Uses terraform-aws-modules" (implementation detail)
- "RDS instance is db.t3.small" (too specific, not outcome-focused)
- "Three availability zones" (architecture detail, not outcome)
- "VPC has /16 CIDR" (implementation detail)
Understanding where technical decisions happen helps you know what to expect at each stage. IaC Spec Kit guides AI assistants through a progression from generic to specific:
1. /iac.specify
→ Requirements specification (cloud-agnostic with high-level technical decisions)
→ Example: "Managed database service", "Serverless compute"
2. /iac.clarify (optional)
→ Resolve ambiguities (still cloud-agnostic)
→ Example: Clarify "managed database" → PostgreSQL vs MySQL
3. /iac.plan
→ Cloud provider and specific services (cloud-specific)
→ Example: AWS → RDS PostgreSQL, GCP → Cloud SQL PostgreSQL
→ Generates: plan.md with inline research
4. /iac.tasks
→ Generate actionable task breakdown
→ Example: Phased implementation with validation checkpoints
5. /iac.implement
→ Generate IaC code (provider-specific)
→ Example: Terraform with terraform-aws-modules
For enterprise or complex projects, add these optional steps:
0. /iac.principles (before /iac.specify)
→ Project governance rules (cloud-agnostic)
→ Example: "Prefer managed services", "Progressive complexity"
3.5. /iac.enrichplan (after /iac.plan)
→ Deep research and comprehensive documentation
→ Generates: research.md, architecture.md, modules.md, quickstart.md
Key insight: Technical decisions progressively refine from general (managed database) to specific (RDS PostgreSQL db.r5.large) as you move through the workflow. IaC Spec Kit helps AI assistants manage this progression—you guide it with your requirements.
Use this reference to understand the patterns IaC Spec Kit encourages:
Use generic terms:
- ✅ "Managed database service" → ❌ "RDS"
- ✅ "Object storage" → ❌ "S3"
- ✅ "Serverless compute" → ❌ "Lambda"
- ✅ "Container orchestration" → ❌ "EKS"
- ✅ "Load balancer" → ❌ "ALB"
- ✅ "Content delivery network" → ❌ "CloudFront"
Include high-level technical decisions:
- ✅ "Managed vs self-managed"
- ✅ "Serverless vs VMs vs containers"
- ✅ "Relational vs NoSQL database"
- ✅ "Multi-zone deployment for HA"
- ✅ "Automated backup and recovery"
Focus on outcomes:
- ✅ Performance targets (latency, throughput)
- ✅ Availability goals (uptime, failover time)
- ✅ Security requirements (encryption, isolation)
- ✅ Cost constraints (budget limits)
- ✅ Operational needs (monitoring, alerting)
When using IaC Spec Kit commands:
- Describe your needs naturally: IaC Spec Kit helps AI assistants structure them into proper specifications
- Don't worry about perfect terminology: IaC Spec Kit guides AI assistants to translate your intent into appropriate technical terms
- Review and refine: Check the generated spec and ask for adjustments if needed
- Trust the process: IaC Spec Kit's commands and templates guide AI assistants toward these patterns, though results may vary
- See examples/ for complete specification examples showing these patterns in practice
- Review the WordPress example showing cloud-agnostic specs deployed to 4 clouds
- Check the spec template to see the structure IaC Spec Kit encourages
- Use
/iac.specifyand let IaC Spec Kit guide the AI through the formatting