Kubernetes Cost Optimization AGENTS.md Template

Overview

AGENTS.md template for Kubernetes cost optimization defines the operating model for cost governance using AI coding agents. It supports both single-agent execution and multi-agent orchestration, with explicit handoffs, shared context, and a supervisor orchestrator to coordinate tasks and validate outcomes.

Direct answer: This AGENTS.md Template codifies roles, rules, and workflows to optimize Kubernetes spend while preserving reliability and governance through agent handoffs and source of truth.

When to Use This AGENTS.md Template

• When you need repeatable, auditable Kubernetes cost optimization across clusters and environments.
• When multiple teams share cloud spend and require clear ownership and handoffs.
• When you want to codify data sources, metrics, and SLAs for cost governance.
• When introducing multi-agent orchestration to run cost-aware actions with validation gates.
• When you need a growth-ready operating model that scales with new cost controls and provider APIs.

Copyable AGENTS.md Template

# AGENTS.md

Project role: CostsOps Lead, SRE, Platform Engineer

Agent roster and responsibilities:
- Planner: defines cost-optimization tasks, derives constraints, and prepares the handoff to the Implementer.
- Implementer: executes changes in Kubernetes manifests, scaling policies, and cost-reduction configurations.
- Reviewer: validates changes against performance and reliability requirements before promotion.
- Auditor: ensures cost improvements are measurable and compliant with governance rules.
- Researcher: collects data on cost drivers, usage patterns, and provider pricing; feeds insights to Planner.
- Domain Expert (Cost): specializes in Kubernetes cost models and cloud pricing structures.

Supervisor or orchestrator behavior:
- The Supervisor maintains the lifecycle of optimization tasks, enforces stage gates, logs decisions, and triggers validation checks post-implementation.
- It persists state in a shared memory store and coordinates handoffs with explicit success/failure criteria.

Handoff rules between agents:
- Planner → Implementer: handoff includes task description, constraints, and data context.
- Implementer → Reviewer: handoff includes proposed changes, impact estimates, and validation plan.
- Reviewer → Auditor: handoff includes reviewed changes and approval status.
- Researcher (as needed) supports Planner with data pivots and cost-model inputs.

Context, memory, and source-of-truth rules:
- All decisions reference a single source of truth: Kubernetes cost data, cluster state, and provider pricing.
- Memory persists across sessions via a shared store; recent and historical decisions are versioned.

Tool access and permission rules:
- Read-only access to cost dashboards; write access to manifest repos under guarded branches; secrets stored in a vault.
- Cloud provider APIs accessed with least-privilege credentials; production actions require approval gates.

Architecture rules:
- Stateless agents; orchestrator persists state; modular components with clear interfaces.
- Idempotent operations; safe retry behavior; audit logs for every change.

File structure rules:
- Use a standard layout:
  ops/k8s-cost-optimization/
  agents/
    planner.md
    implementer.md
    reviewer.md
    auditor.md
    researcher.md
  workflows/
    kubernetes-cost-optimization/
  data/
    cost-metrics.json

Data, API, or integration rules:
- Pull cost metrics from provider APIs and metrics endpoints; limit data retention to governance needs.
- Use read-only data endpoints where possible; secrets in vault; rotate credentials per policy.

Validation rules:
- Validate cost reduction against baseline within a defined tolerance before apply.
- Verify no degradation in performance or availability post-implementation.

Security rules:
- Do not expose secrets in logs or artifacts.
- Enforce least-privilege for all agents; rotate keys regularly; require human approval for production changes.

Testing rules:
- Unit tests for cost calculations; integration tests against sandbox clusters; end-to-end tests of the orchestration flow.

Deployment rules:
- CI pipelines must run before merging to guarded branches; feature flags control rollout; monitor after deployment for regressions.

Human review and escalation rules:
- Any potential negative impact on latency or reliability requires human review before deployment.
- Escalate to SRE if k8s nodes show resource pressure during optimization.

Failure handling and rollback rules:
- If a change increases cost or harms reliability, rollback to the previous manifest and revalidate.
- Maintain a changelog of all optimizations and rollbacks.

Things Agents must not do:
- Do not perform production changes without approval; do not modify budgets without a policy; do not skip validation gates.
- Do not leak credentials or secrets in logs or artifacts.

Recommended Agent Operating Model

Roles and decision boundaries:

• Planner defines constraints, success criteria, and the cost-optimization path; boundary: can propose changes, not implement directly.
• Implementer carries out changes within policy-compliant contexts; boundary: changes must pass validation gates.
• Reviewer verifies performance, reliability, and governance; boundary: cannot authorize production changes without Auditor sign-off.
• Auditor validates measurable cost improvements against baseline; boundary: only approves if metrics meet thresholds.
• Researcher provides data, trends, and priors to Planner; boundary: data sources must be cited and versioned.

Recommended Project Structure

ops/k8s-cost-optimization/
  agents/
    planner.md
    implementer.md
    reviewer.md
    auditor.md
    researcher.md
  workflows/\u200b kubernetes-cost-optimization/
  data/\u200b cost-metrics.json

Core Operating Principles

• Single source of truth for cost data and Kubernetes topology.
• Idempotent, auditable changes with clear rollback paths.
• Clear, documented handoffs and decision boundaries.
• Least-privilege access and secrets management.
• Continuous validation of cost impact and reliability.

Agent Handoff and Collaboration Rules

Planner coordinates with Implementer and Researcher; Implementer reports validations to Reviewer; Reviewer and Auditor confirm outcomes; Human review triggers when thresholds are breached.

Tool Governance and Permission Rules

• Commands to cluster must pass policy checks; all edits go through guarded branches.
• API calls to cost providers require scoped credentials and audit trails.
• Secrets stored in a vault; access restricted by role and rotation policy.
• Production changes require an approval gate and post-deployment monitoring.

Code Construction Rules

• All cost-optimization logic is declarative and testable; avoid side effects outside approved manifests.
• Use feature flags to enable gradual rollout.
• Documentation must accompany every change.

Security and Production Rules

• Follow least-privilege principles; never embed secrets in code or logs.
• Rotate credentials regularly; enforce strict access controls.
• Maintain audit trails for all production actions.

Testing Checklist

• Unit tests for cost calculations and policy logic.
• Integration tests with sandbox clusters and mocked cost APIs.
• End-to-end tests of the orchestration flow with rollback scenarios.

Common Mistakes to Avoid

• Skipping validation gates or rushing production changes.
• Assuming cost reductions without performance impact checks.
• Leaking credentials or bypassing audit trails.

Related implementation resources: AI Agent Use Case for Wholesalers Using Multi-Currency Ledger Trackers To Calculate Foreign Exchange Risk Exposure Across Global Accounts and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is this AGENTS.md Template for Kubernetes cost optimization?

This template codifies the operating model for using AI coding agents to optimize Kubernetes costs, supporting single-agent and multi-agent orchestration with clear handoffs, source of truth, and governance.

When should I use this AGENTS.md Template?

Use this when you want repeatable, auditable cost optimization for Kubernetes clusters, across teams, environments, and cloud providers.

How do agents hand off work in this template?

Handoffs are defined in the supervisor orchestrator rules: planner proposes tasks, implementer executes, reviewer validates, and cost auditor confirms outcomes.

What are the security considerations?

Store credentials securely, enforce least privilege, rotate secrets, and require human review for production changes.

How do I validate cost improvements and rollback if needed?

Validate against baseline cost metrics, run dry-runs, and provide rollback rules to revert changes if KPIs regress.