AGENTS.md Template: AWS VPC and Subnet Design

Overview

Direct answer: This AGENTS.md template defines a repeatable operating manual for AWS VPC and subnet design using AI coding agents. It supports both single-agent workflows and multi-agent orchestration, with explicit handoffs, memory, and a shared source of truth. The template enforces tool governance, validation, and escalation rules to ensure auditable, productive outcomes.

It codifies roles, responsibilities, decision boundaries, and escalation paths so a team can design, validate, and deploy VPCs and subnets with confidence and traceability.

When to Use This AGENTS.md Template

• You're designing or auditing an AWS VPC and its subnet topology for a project or product line.
• You need a formal operating model for single-agent work or multi-agent orchestration across cloud networking tasks.
• You require explicit handoffs between planner, implementer, reviewer, tester, researcher, and domain specialist agents.
• You want a single source of truth for design decisions, policies, and deployment steps that is easy to audit.
• You must enforce tool governance, secrets handling, and production guardrails in a cloud network design workflow.

Copyable AGENTS.md Template

Use this as the project-level operating context for AI coding agents working on AWS VPC and subnet design.

# AGENTS.md

Project Role: Cloud Network Architect coordinating VPC and subnet design using AI coding agents.

Agent roster and responsibilities:
- Planner: crafts high-level VPC/subnet strategy, CIDR blocks, and routing plan.
- Implementer: provisions resources, writes IaC, applies network changes in staging.
- Reviewer: validates CIDR ranges, route tables, NAT/IGW, and security posture.
- Tester: executes network reachability, failover, and performance tests; verifies drift and idempotence.
- Researcher: aggregates AWS best practices, constraints, and governance requirements.
- Domain Specialist (Security/Network Engineer): ensures compliance with security design and regulatory controls.

Supervisor/Orchestrator: coordinates handoffs, tracks decisions, and maintains the single source of truth for the VPC design.

Handoff rules:
- Planner → Implementer: deliver plan artifacts (CIDR blocks, VPC/subnet design).
- Implementer → Reviewer: deliver IaC and configuration for validation.
- Reviewer → Implementer: request changes or approve for deployment.
- Implementer → Tester: run integration tests in staging.
- Tester → Reviewer: report test results; if issues persist, loop back to Planner.
- Researcher/Domain Specialist can escalate to Supervisory review when policy constraints are violated.

Context, memory, and source-of-truth rules:
- Store decisions in a central Design Document repository and a versioned IaC repo.
- Reference the current design document as the single source of truth; do not mutate decisions in transient chat.
- Memory must be updated after each handoff with rationale and evidence (diagrams, CIDR calculations, risk notes).

Tool access and permission rules:
- Agents have read/write access to IaC repos and staging environments only; production access requires explicit approval gates.
- Secrets must be retrieved from a secure vault; never hardcode credentials.
- Use the AWS account IAM roles defined in the design document; apply least privilege.

Architecture rules:
- Design modular VPCs with clear isolation boundaries; subnets mapped to availability zones where possible.
- Use standard routing patterns (public/private subnets, NAT gateway/bastion where appropriate).
- Apply security groups and network ACLs in line with the design specification.

File structure rules:
- vpc-design/
  - plans/
  - implementations/
  - tests/
  - reviews/
  - researchers/
  - domain-specialists/
  - configs/
  - docs/

Data, API, or integration rules:
- Use AWS SDK/CLI in a controlled manner; perform actions in staging before prod.
- Centralize design data in the repository; reference external data sources only via validated adapters.

Validation rules:
- CIDR blocks must not overlap; each subnet must be within the VPC CIDR.
- Route tables and NAT/GW placements must align with the plan.
- Security groups must implement the least-privilege model per design.

Security rules:
- Never commit secrets; rotate credentials; enforce MFA on privileged actions.
- Production changes require multi-person approval and a change window.

Testing rules:
- Unit tests for CIDR math; integration tests for routing and access controls; end-to-end tests in staging.
- All tests must pass before deployment.

Deployment rules:
- Changes move from plans to implementations to staging; production changes require approved plan and staged rollout.
- Rollback script must be ready and tested; ensure a quick revert path.

Human review and escalation rules:
- Design decisions must be reviewed by Domain Specialist for security posture.
- If a test fails or a policy is violated, escalate to Supervisors and log in the Design Document.

Failure handling and rollback rules:
- If deployment fails, revert to last known-good configuration; document failure and remediation steps.

Things Agents must not do:
- Do not bypass security controls or secrets vault; do not mutate production networks outside approved windows.
- Do not create overlapping CIDRs or misaligned route tables.
- Do not perform irreversible changes without approval.

Recommended Agent Operating Model

The planner determines goals and constraints; the implementer executes changes as coded; the reviewer validates against the design; the tester confirms behavior in staging; the researcher and domain specialist verify alignment with AWS best practices and security policies; escalation paths exist for policy violations or test failures. Clear decision boundaries ensure safe, auditable changes to AWS VPC and subnet configurations.

Recommended Project Structure

vpc-design/
  planners/
  implementers/
  reviewers/
  testers/
  researchers/
  domain-specialists/
  configs/
  docs/
  tests/

Core Operating Principles

• Single source of truth for design decisions and deployment steps.
• Idempotent, auditable actions with traceable rationale.
• Least privilege and secure handling of credentials and secrets.
• Clear handoffs and decision boundaries between agents.
• Early validation in staging before production changes.

Agent Handoff and Collaboration Rules

• Planner -> Implementer: deliver plan artifacts including CIDR plan, VPC/subnet topology, and routing strategy.
• Implementer -> Reviewer: deliver IaC, configuration, and compliance checks.
• Reviewer -> Implementer: request changes or approve for deployment.
• Researcher/Domain Specialist: provide policy rationale and security alignment when required.
• Planner can re-enter cycle if critical constraints or risks are identified by any agent.

Tool Governance and Permission Rules

• Only approved tools and SDKs may be used; secrets must be retrieved from a vault.
• Production changes require multi-person approval and a change window.
• All actions are logged and reversible via documented rollback scripts.

Code Construction Rules

• Use modular IaC with reusable VPC/subnet modules.
• Avoid hardcoded identifiers; parameterize all environment-specific values.
• Keep design decisions in version-controlled Design Documents and IaC repositories.
• Write tests for CIDR math, routing, and security posture.

Security and Production Rules

• All production changes require approved plans and audited sign-off.
• Secrets must not be committed; rotate credentials and enforce MFA for privileged actions.
• Subnet isolation and security groups adhere to the least-privilege principle.

Testing Checklist

• CIDR overlap checks and subnet sizing validated.
• Routing tables and NAT/GW paths tested in staging.
• Security posture confirmed with domain specialist.
• End-to-end connectivity tests pass in staging before production.

Common Mistakes to Avoid

• Overlapping CIDRs or misconfigured subnets that break isolation.
• Bypassing the design document for quick fixes.
• Untracked changes outside the approved change window.
• Hardcoding environment-specific values instead of using parameters.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Agent Use Case for Defense Subcontractors Using Compliance Databases To Verify It Infrastructure Alignment with Cybersecurity Rules.

FAQ

What is the purpose of this AGENTS.md Template for AWS VPC and Subnet Design?

It provides a complete operating manual for single-agent and multi-agent workflows to design, validate, and deploy AWS VPCs and subnets with governance and auditable decisions.

Who should use this AGENTS.md Template?

Cloud network engineers, platform teams, and AI coding agents tasked with VPC/subnet design and governance in cloud environments.

How are handoffs between agents handled?

Handoffs follow a defined sequence: Planner → Implementer → Reviewer; with escalations to Domain Specialist or Supervisor when needed.

What constitutes the single source of truth in this template?

The Design Document repository and the versioned IaC repository act as the authoritative sources for decisions, with memory updated after each handoff.

How is security incorporated into the workflow?

Security is embedded in design decisions, least-privilege policies, vault-based secrets management, and multi-person approvals for production changes.

What happens if a deployment fails?

Rollback scripts revert to the last known-good configuration; failures are logged with remediation steps and reviewed by the supervisor.