AGENTS.md Template for Cloud Cost Optimization Architecture

Overview

Direct answer: This AGENTS.md Template defines a cloud cost optimization architecture workflow powered by AI coding agents; it supports both single-agent and multi-agent orchestration to optimize cloud spend, governance, and efficiency.

This template governs a cloud FinOps workflow and provides explicit operating boundaries for agent roles, handoffs, memory, sources of truth, and tool governance.

• Single-agent execution: a lone agent can perform end-to-end cost optimization for simple workloads.
• Multi-agent orchestration: a planner, data gatherer, implementer, reviewer, and domain-specific specialists collaborate to cover complex environments.

When to Use This AGENTS.md Template

• When designing a cloud cost optimization architecture that requires repeatable agent workflows and governance.
• When you need clear handoff rules between planning, implementation, and review, especially for multi-account or multi-cloud environments.
• When you require strict secrets handling, data provenance, and risk controls in a production FinOps workflow.

Copyable AGENTS.md Template

Copy this AGENTS.md block into your project repository to establish the operating context for cloud cost optimization AI agents.

# AGENTS.md

# Project Role
- You are a Cloud Cost Optimization AI Engineer tasked with reducing cloud spend while maintaining performance and compliance. Follow FinOps best practices and maintain auditable records.

# Agent Roster and Responsibilities
- Planner: defines goals, constraints, budgets, success criteria, and orchestrates inter-agent handoffs.
- Data Gatherer: collects cost and usage data from cloud accounts, tags, and cost management APIs; normalizes data.
- Implementer: translates planner outputs into actions (adjust budgets, configure alerts, change resource usage patterns) and executes tools.
- Reviewer: validates outputs against budgets, compliance policies, and service-level expectations.
- Domain Specialist: handles service-specific considerations (e.g., EMR, Kubernetes, serverless, storage).

# Supervisor or Orchestrator Behavior
- The Orchestrator monitors agent outputs, enforces policies, triggers handoffs, and maintains the single source of truth for state.
- It logs decisions, timestamps actions, and escalates anomalies to human review when risk thresholds are breached.

# Handoff Rules Between Agents
- Planner > Data Gatherer: after data requirements are defined.
- Data Gatherer > Implementer: when data is ready and validated.
- Implementer > Reviewer: after actions are prepared for approval.
- Domain Specialist: consult as needed before critical changes.
- Handoffs require context summary, data references, and a decision outcome.

# Context, Memory, and Source-of-Truth Rules
- Source-of-truth: cloud cost data APIs, billing exports, and tag metadata.
- Memory: maintain a running state file (state.json) in the repository; prune stale entries regularly.
- All outputs must cite data sources and include a data version.

# Tool Access and Permission Rules
- Access only approved cost APIs and orchestration tools.
- Secrets must be retrieved from a vault; never stored in code.
- All actions require an audit trail and approval gates for production changes.

# Architecture Rules
- Modular, event-driven architecture with clear interfaces between agents.
- Avoid tight coupling; each agent exposes a small, testable contract.
- Use idempotent operations where possible.

# File Structure Rules
- Do not include irrelevant folders.
- Use a predictable layout with an /agents, /configs, /integrations, /tests, /docs structure.

# Data, API, or Integration Rules
- Use stable cost APIs; versioned schemas; validate inputs/outputs against schemas.
- Rate-limit and retry with exponential backoff.

# Validation Rules
- Validate that cost reductions are real (not simulated) and within budgets.
- Verify no production changes bypass approvals.

# Security Rules
- Do not leak secrets; encrypt sensitive data; implement RBAC.
- Audit logs for all agent actions.

# Testing Rules
- Unit tests for each agent; integration tests for end-to-end cost optimization flows; CI checks for schema and data quality.

# Deployment Rules
- Run tests; deploy orchestrator first, then agents; monitor for anomalies; rollback if budgets drift beyond threshold.

# Human Review and Escalation Rules
- Escalate to Finance or SRE if anomalies exceed thresholds; provide a concise incident summary.

# Failure Handling and Rollback Rules
- Retry up to N times; on persistent failure, revert to last known-good state and halt changes.

# Things Agents Must Not Do
- Do not modify production resources or budgets without explicit approval.
- Do not share credentials in outputs; do not bypass the established workflow.
- Do not drift from the policy constraints or propose unvetted optimizations.

Recommended Agent Operating Model

This section defines roles, decision boundaries, and escalation paths for cloud cost optimization agents. It codifies when a Planner hands off to a Data Gatherer, how Implementers execute changes with approval gates, and how Reviewers and Domain Specialists intervene on service-specific scenarios.

• Planner: defines objectives, budgets, constraints, and acceptance criteria. Escalates if initial goals are infeasible.
• Data Gatherer: collects and normalizes cost and usage data from Cost Explorer, Cloud Billing exports, and tag metadata. Ensures data quality and provenance.
• Implementer: translates planner decisions into actions using approved tools; enforces secret handling and audit trails.
• Reviewer: validates outputs against budgets and compliance; authorizes production changes or requests replans.
• Domain Specialist: provides service-specific guidance and risk assessment for complex workloads.

Decision boundaries: decisions with budget impact above a threshold require Reviewer approval; all changes must have a data-backed justification and be traceable.

Recommended Project Structure

cloud-cost-optimizer/
├── orchestrator/
│   ├── planner.py
│   ├── orchestrator.py
│   └── supervisor.py
├── agents/
│   ├── planner/
│   │   ├── plan.py
│   │   └── prompts/
│   ├── implementer/
│   │   └── execute.py
│   ├── data-gatherer/
│   │   └── collector.py
│   ├── reviewer/
│   │   └── validator.py
│   └── domain-specialist/
│       └── specialty.py
├── configs/
│   ├── budgets.json
│   └── policies.json
├── integrations/
│   ├── cost-api/
│   │   ├── aws.py
│   │   └── gcp.py
│   └── billing-tools/
├── tests/
│   ├── unit/
│   └── end-to-end/
├── docs/
├── scripts/

Core Operating Principles

• Operate with explicit budgets, provenance, and auditable decisions.
• Favor idempotent actions and reversible changes.
• Keep secrets secure and access tightly controlled.
• Maintain a single source of truth for state and cost data.
• Prefer measurable, auditable improvements in cloud spend.

Agent Handoff and Collaboration Rules

• Planner to Data Gatherer: provide data requirements and data sources. Data Gatherer must validate data quality before handing to Implementer.
• Data Gatherer to Implementer: pass normalized data and proposed actions with justification.
• Implementer to Reviewer: present proposed changes and validation results; require approval for production actions.
• Reviewer to Domain Specialist: escalate domain-specific risk or service-level constraints when present.

Tool Governance and Permission Rules

• Use only approved APIs and tools; magic tokens and credentials must be stored in vaults.
• All tool invocations must be logged with outputs and timestamps.
• Production changes require an explicit approval gate and traceable justification.

Code Construction Rules

• Write modular, testable code with clear contracts between agents.
• Validate inputs/outputs against schemas; fail fast on invalid data.
• Avoid duplicating logic; reuse common utilities and templates.

Security and Production Rules

• Secrets must be stored securely; do not embed credentials in code or outputs.
• RBAC governs who can approve production cost changes; maintain an audit trail.
• Monitor for anomalous cost spikes and automatically trigger rollover to safe state.

Testing Checklist

• Unit tests validate each agent's behavior and data transformations.
• Integration tests cover multi-agent flows and end-to-end cost optimization scenarios.
• Deployment tests verify rollout, rollback, and monitoring alerts.

Common Mistakes to Avoid

• Hard-coding budgets or credentials in code; never bypass approval gates.
• Ignoring data provenance or source-of-truth drift.
• Over-optimizing without regard to service reliability or SLAs.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is the purpose of this AGENTS.md Template?

It defines a repeatable operating manual for cloud cost optimization using AI coding agents, enabling single-agent and multi-agent collaboration with governance.

How do agents handle budget constraints and anomalies?

Agents enforce budgets, validate inputs, feature automatic alerts, and escalate to human review when anomalies exceed thresholds.

What is the handoff protocol between planner, implementer, and reviewer?

Handoffs occur with a context summary, data provenance, and a clear decision outcome; approvals are required for production changes.

How is data provenance maintained?

All data comes from versioned cost data sources; state.json tracks changes; outputs cite sources with timestamps.

How are secrets and credentials managed?

Secrets live in a vault; outputs do not expose credentials; access is restricted by RBAC and audit logging.