Field-tested guardrails and patterns for letting AI agents operate safely on real cloud infrastructure — multi-account AWS, Kubernetes/GitOps, Terraform and CI/CD — without handing them a loaded footgun.
Modern coding agents can already run kubectl, terraform and gh against live
systems. The hard part isn't getting them to act — it's constraining them so they
act correctly, reversibly and auditably in environments where a single wrong
command is expensive. This repo distills the operating model that makes that safe.
Platform, infrastructure and DevOps engineers who want to put AI agents to work on IaC, Kubernetes and release pipelines — and stay firmly in control of the blast radius.
- Least privilege, per task. An agent holds the narrowest credential that completes the job, and nothing wider sits in its shell "just in case."
- Make mutations explicit and reversible. The target environment is stated before any write; destructive actions are confirmed, never assumed.
- GitOps over imperative. Persistent change lands through a reviewed PR and a
reconciler — not through an agent typing
applyagainst a cluster. - One writer per branch/environment. Parallel agents isolate on their own branch + worktree and announce their claim, so they can't corrupt shared state.
- Agents propose, humans merge. The agent opens the PR; a human approves it.
- Shrink the blast radius and the context. Delegate bounded subtasks to focused sub-agents and keep the coordinator's working set lean.
| Area | Practice | Why it matters |
|---|---|---|
| Credentials | Scoped, per-purpose credentials; never echo or commit secrets; no silent interactive-auth fallback | A leaked or over-broad credential is the highest-cost agent failure |
| Environment safety | Require an explicit target env (dev/test/uat/prod) before any write; read-only discovery is fine while clarifying |
Stops "which cluster was that?" accidents |
| Change control | GitOps / pipeline-only; no manual kubectl/terraform apply as a workflow |
Keeps Git the single source of truth; every change is reviewable and revertible |
| Version control | Short-lived feature branches → PR → review; never push to protected branches | Human approval gate; clean, auditable history |
| Promotion | Forward-only across environments, small and frequent | Prevents drift and giant, unreviewable change sets |
| Parallel isolation | One branch + worktree per session; a lock/reservation before mutating | Lets many agents run at once without trampling each other |
| Orchestration | Delegate discovery/validation to sub-agents; return only decisions to the main thread | Keeps the coordinator focused and cheap |
| Supply chain | Pull only from private registries you control; mirror upstream deliberately | No surprise dependency on a public registry that can vanish or be poisoned |
| Communication | Lead with the outcome; full URLs for PRs; plain language | Human-readable, skimmable, auditable updates |
Each of these is unpacked with rationale in docs/patterns.md.
AGENTS.template.md is a drop-in operating contract you can
copy into a repo and fill in for your own accounts, environments and tooling. It's the
fastest way to give an agent a safe lane to work in.
curl -O https://raw.githubusercontent.com/valentevidal/agentic-platform-engineering/main/AGENTS.template.md
# rename to AGENTS.md (and/or CLAUDE.md), then fill in the bracketed sectionsIssues and PRs welcome — especially war stories about agent failure modes and the guardrail that fixed them. Keep examples generic; never paste real credentials, account IDs or internal hostnames.
MIT © Valente Vidal