AGENTS.md Template for Kubernetes Production Architecture and AGENTS.md template Guidelines

Overview

The AGENTS.md template for Kubernetes production architecture defines how AI coding agents operate in a Kubernetes production environment, supporting both a single-agent workflow and multi-agent orchestration.

When to Use This AGENTS.md Template

Use when designing Kubernetes production architecture that relies on AI coding agents to manage deployments, config, and observability.
Use to establish a repeatable operating context for single-agent and multi-agent workflows in Kubernetes.
Use to enforce tool governance, security, and human review with clear handoff rules.

Copyable AGENTS.md Template

This is an AGENTS.md template for Kubernetes production architecture designed for both single-agent and multi-agent orchestration.

# AGENTS.md
Project Role: Kubernetes Production Architecture with AI coding agents
Agent roster and responsibilities:
- Planner: designs deployment topology, quotas, scaling, and governance constraints.
- Implementer: translates plans into manifests, Helm charts, and operators.
- Reviewer: validates changes against policy, lint, security checks, and compliance.
- Tester: runs integration tests, canary tests, and post-deploy checks.
- Researcher: researches best practices, observability, and performance tuning.
- Domain Specialist: provides workload context, data locality, and compliance guidance.
Supervisor or orchestrator behavior:
- Orchestrator coordinates tasks, tracks memory, enforces timeouts, logs decisions, and triggers escalations when needed.
Handoff rules:
- Plan -> Implementer: pass context and goals.
- Implementer -> Reviewer: pass changes for validation.
- Reviewer -> Tester: trigger validation and tests.
- Tester -> Orchestrator: report results and gate production rollout.
- If tests pass, Orchestrator promotes changes to Production; otherwise, revert or revise plan.
Context, memory, and source-of-truth rules:
- Context lives in the central project repository and Kubernetes manifests.
- Memory is per execution; source-of-truth is the GitOps repository and cluster state via the Kubernetes API.
Tool access and permission rules:
- Access limited to Kubernetes API, GitOps tooling, and Secrets managers.
- Secrets must never be exposed in logs; kubeconfig access is restricted and audited.
Architecture rules:
- Use namespaces, RBAC, resource quotas, and network policies; prefer declarative configurations and idempotent changes.
File structure rules:
- manifests/ for Kubernetes manifests
- apps/ for application definitions
- config/ for configuration
- charts/ or operators/ for operator code
- docs/ for templates and runbooks
Data, API, or integration rules when relevant:
- Integrations via Kubernetes APIs, GitOps, Prometheus, and traces; use Operators for complex workloads.
Validation rules:
- YAML validation, linting, and schema checks; CI must fail on invalid manifests.
Security rules:
- Secrets encrypted at rest; least privilege RBAC; image scanning; PodSecurity standards.
Testing rules:
- Unit tests for manifests, integration tests, canary tests, and end-to-end checks.
Deployment rules:
- Canary or blue-green deployments; observe metrics; require approval gates for production.
Human review and escalation rules:
- Critical changes require human review after automated checks; escalate to SRE for production incidents.
Failure handling and rollback rules:
- Rollback to previous manifest if production metrics degrade beyond threshold; keep backups in Git.
Things Agents must not do:
- Do not bypass tool governance; do not deploy without tests; do not drift architecture; do not modify production without review.

Recommended Agent Operating Model

The recommended operating model defines clear roles, decision boundaries, and escalation paths for Kubernetes production architecture when using AI coding agents. It specifies how planners, implementers, reviewers, testers, researchers, and domain specialists collaborate, how decisions are escalated to human review when risk thresholds are exceeded, and how recovery happens after failures.

Recommended Project Structure

k8s-prod-architecture/
  manifests/
  apps/
  config/
  charts/
  operators/
  monitors/
  pipelines/
  docs/
  tests/

Core Operating Principles

Single source of truth: GitOps repo is the canonical source of all Kubernetes manifests.
Idempotent actions: repeated runs should yield the same state without side effects.
Explicit handoffs: every transition between agents is logged and validated.
Auditability: all decisions and actions are traceable via the orchestrator.
Least privilege: tools and agents only have the minimal permissions necessary.

Agent Handoff and Collaboration Rules

Establish explicit rules for planner, implementer, reviewer, tester, researcher, and domain specialist agents to coordinate work with minimal context drift.

Tool Governance and Permission Rules

Tool usage follows strict access control, secrets handling, and approval gates aligned with Kubernetes governance.

Code Construction Rules

Ensure code is declarative, linted, YAML-validated, and idempotent; use Helm/Kustomize where appropriate; avoid embedding secrets in code.

Security and Production Rules

Enforce encryption at rest, TLS everywhere, RBAC least privilege, image scanning, and secure supply chain checks.

Testing Checklist

Unit tests for manifests
YAML linting and schema validation
Integration tests against a staging cluster
Canary deployment checks

Common Mistakes to Avoid

Skipping human review for production changes
Ignoring drift between GitOps and cluster state
Using hard-coded secrets or non-idempotent scripts

FAQ

What is the purpose of this Kubernetes AGENTS.md Template?

To define a reproducible, auditable operating model for Kubernetes production architecture using AI coding agents and multi-agent orchestration.

How does multi-agent orchestration work in Kubernetes production architecture?

It assigns specialized roles (Planner, Implementer, Reviewer, Tester, Researcher, Domain Specialist) and coordinates handoffs via a central Orchestrator to manage deployments, config, and monitoring.

What are the handoff rules between agents?

Handoffs occur at defined decision checkpoints; the Planner passes context to the Implementer; the Implementer passes validated changes to the Reviewer; the Reviewer triggers Tests; upon success, the Orchestrator promotes to Production.

How are secrets and access controlled?

Use GitOps with encryption, least-privilege RBAC, and centralized Secrets management; restrict kubeconfig access; audit logs.

How do you validate changes before production?

Automated tests, canary deployments, risk checks, and human review when thresholds require approval.

Target User

Use Cases