AGENTS.md Template for Cloud Networking Architecture

Overview

Direct answer: This AGENTS.md template codifies the cloud networking architecture agent workflow into a single operating manual that supports both single-agent execution and multi-agent orchestration across planning, implementation, validation, and governance. It defines the project-level operating context for AI coding agents responsible for cloud networking tasks (VPC design, subnets, routing, firewall policies, NAT, and security posture) and the governance around tool access, memory, and source-of-truth to ensure auditability and reproducibility.

The template enables both individual agent work and collaborative, multi-agent workflows with explicit handoffs, escalation paths, and rollback strategies. It emphasizes cloud-native automation, policy-as-code, and a canonical project structure to prevent context drift in cloud networking architecture projects.

When to Use This AGENTS.md Template

• When you need a repeatable, auditable cloud networking automation workflow guided by AI coding agents
• When governance, security, and auditability matter across cloud accounts and regions
• When you require explicit handoffs between planner, implementer, validator, reviewer, and monitor agents
• When multi-agent orchestration is needed to design, provision, validate, and operate cloud networking infrastructure
• When you want a canonical project structure and memory with a single source of truth for cloud state

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Cloud Networking Architect for AI agent workflows

Agent roster and responsibilities:
- Planner: designs VPC topology, subnets, routing, NAT, security posture; produces a topology spec with constraints and success criteria.
- Implementer: translates topology into cloud infrastructure configurations (Terraform/CloudFormation) and applies them.
- Validator: validates config against policy rules, security checks, and drift detection.
- Reviewer: approves changes before deployment; signs off on security posture.
- Researcher: sources vendor documentation and best-practice guidance to inform decisions.
- Ops/Monitor: monitors deployment, telemetry, drift, and alerts; triggers rollbacks if needed.

Supervisor or orchestrator behavior:
- Orchestrator coordinates tasks, enforces memory and memory-versioning, maintains single source of truth, and enforces escalation gates.

Handoff rules between agents:
- Planner -> Implementer: transfer topology spec, required parameters, and validation criteria.
- Implementer -> Validator: transfer deployed state, configuration diffs, test results.
- Validator -> Reviewer: present policy checks, risk assessment, and change impact.
- Reviewer -> Ops/Monitor: finalize deployment with monitoring and alerts enabled.

Context, memory, and source-of-truth rules:
- Context is derived from a canonical cloud state (cloud provider state, Terraform state, policy as code). Memory is versioned and stored in a central store with references to sources.
- All critical decisions must be traceable to source facts and artifacts (docs, policy, config files).

Tool access and permission rules:
- Access to cloud APIs must be via least privilege roles; credentials stored in a secrets manager; no hard-coded keys.

Architecture rules:
- Use a modular VPC design: separate account boundaries if needed; standard subnets; NAT and gateway architecture; centralized DNS; IAM roles restricted to task scope.

File structure rules:
- infra/
  - network/
    - vpc/
    - subnets/
    - routing/
  - security/
  - policies/
  - state/
  - orchestrator/
  - agents/
  - docs/

Data, API, or integration rules:
- All data exchanges must be validated against a schema; API credentials rotated; audit logs retained.

Validation rules:
- Config diffs must be validated; drift checks performed; tests in staging.

Security rules:
- Encrypt at rest and in transit; guard sensitive data; enforce MFA for sensitive actions.

Testing rules:
- Unit tests for config generation; integration tests for network provisioning; end-to-end tests for production drift.

Deployment rules:
- Deploy to staging first; gating via feature flags; canary with rollback if issues observed.

Human review and escalation rules:
- High-risk changes require human-in-the-loop review; on-call escalation path.

Failure handling and rollback rules:
- If tests fail, revert to last good state; preserve logs; rollback automatically if drift detected.

Things Agents must not do:
- Do not bypass approvals; do not modify production network outside approved change windows; do not ignore drift.

Recommended Agent Operating Model

The recommended operating model assigns clear boundaries and escalation paths for cloud networking tasks handled by AI agents. Roles include Planner, Implementer, Validator, Reviewer, and Monitor, with a Security Domain Specialist as needed for policy enforcement. Decision rights reside with the orchestrator, and cross-agent handoffs follow a strict protocol to preserve context and auditable history.

• Planner: decides design, constraints, and success criteria; informs Implementer with a formal topology spec.
• Implementer: materializes the spec in cloud infrastructure code and applies changes; reports results to Validator.
• Validator: ensures compliance with security, policy, and drift checks before reviewer sign-off.
• Reviewer: confirms risk and approves or rejects changes for production; triggers rollback if needed.
• Monitor: maintains observability, detects drift, and initiates remediation or escalation.
• Escalation: if uncertain or high-risk, escalate to the on-call on-call engineer and record rationale in memory.

Recommended Project Structure

infra/
  network/
    vpc/
      main.tf
      variables.tf
    subnets/
      public/
      private/
    routing/
  security/
  policies/
  state/
  orchestrator/
  agents/
  docs/

Core Operating Principles

• Single source of truth: cloud state, policy as code, and orchestration results.
• Idempotent actions: repeated runs converge to the same state.
• Deterministic decisions: agents rely on validated inputs and documented rules.
• Explicit handoffs: every transition includes context, rationale, and expected outputs.
• Auditability: all decisions, changes, and approvals are traceable.
• Security by default: least privilege, secrets managed, and MFA enforced.

Agent Handoff and Collaboration Rules

• Planner to Implementer: transfer topology spec, constraints, and success criteria.
• Implementer to Validator: provide deployed state, diffs, and test results.
• Validator to Reviewer: present policy checks, risk, and impact.
• Researcher to any agent: share authoritative docs and authoritative sources relevant to decisions.
• Domain Specialist to Planner/Implementer: supply policy constraints and expert guidance.

Tool Governance and Permission Rules

• Cloud API access via least privilege roles; rotate/expire credentials; no hard-coded secrets.
• Secrets stored in a centralized vault; audit access events.
• All tool actions require traceable provenance and change logs.
• Approval gates are required for production changes; failed gates halt automation.

Code Construction Rules

• Use idempotent, declarative configurations (Terraform/CloudFormation) with versioned state.
• Validate inputs against schemas; fail-fast on invalid configurations.
• Document every resource parameter and expected behavior in code comments.
• Avoid hard-coded values; use parameterization and secret references.

Security and Production Rules

• Enforce encryption at rest and in transit; rotate keys; limit exposure of IAM credentials.
• Implement network segmentation, strict firewall rules, and monitored drift.
• Require multi-party approval for production changes; maintain rollback plan and runbooks.

Testing Checklist

• Unit tests for config generation; test harness for policy validation.
• Integration tests against staging cloud environment; end-to-end tests for provisioning and teardown.
• Canary and feature-flag tests for production changes; verify rollback works.

Common Mistakes to Avoid

• Skipping policy and security checks in favor of speed.
• Allowing drift due to untracked manual changes.
• Unclear handoffs leading to duplicated work or missing outputs.
• Ignoring audit logs and traceability requirements.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Policy Documents and Internal Question Answering.

FAQ

What is the purpose of this AGENTS.md Template for cloud networking architecture?

It defines the operating context for AI coding agents and multi-agent orchestration around cloud networking tasks, with clear roles and governance.

How do agent handoffs work in multi-agent orchestration?

Handoffs are rule-driven: Planner -> Implementer transfers design specs; Implementer -> Validator shares config and test results; Validator -> Reviewer presents policy checks; Reviewer -> Monitor completes production deployment with monitoring enabled.

What governance rules govern tool access and secrets?

Access uses least privilege IAM roles; secrets live in a vault; no keys are hard-coded; all actions are auditable.

What should a cloud networking project structure look like?

Follow infra/network modular layout (vpc, subnets, routing) plus security, policies, and state management folders; keep orchestrator and agents separate for clarity.

How is security validated before deployment?

Security validation includes policy checks, encryption, access control reviews, and drift checks prior to deployment; high-risk changes require human review.