claude-teams — AWS Infrastructure Audit with Specialized Claude Agents

This repository demonstrates a multi-agent Claude Code workflow for auditing AWS infrastructure defined in Terraform. Specialized subagents run in parallel, each owning a distinct domain, and write structured findings to a shared output directory.

What This Is

A proof-of-concept showing how to decompose a complex infrastructure review into focused, parallel AI agents — each with scoped tools, domain-specific rules, and designated output files — rather than asking a single generalist agent to do everything at once.

Repository Structure

claude-teams/
├── CLAUDE.md                        # Shared context: account layout, toolchain, tagging standards, agent rules
├── .claude/
│   └── agents/                      # Subagent definitions (one file per agent)
│       ├── aws-platform.md          # VPC, EKS, RDS, EC2, S3, Terraform conventions
│       ├── aws-iam.md               # IAM roles, policies, SCPs, OIDC federation
│       ├── aws-security.md          # Detective + preventive controls (read-only)
│       └── aws-finops.md            # Cost waste, tagging compliance, savings (read-only)
├── terraform/
│   └── envs/
│       └── dev/
│           └── main.tf              # Dev environment — intentionally contains issues for agents to find
└── shared/                          # Agent output directory (agents write here, never to source)
    ├── security-audit-dev.md
    ├── iam-audit-dev.md
    ├── finops-audit-dev.md
    ├── finops-audit-staging.md
    ├── platform-findings.md
    ├── iam-findings.md
    ├── security-findings.md
    └── finops-findings.md

The shared/ Folder — Agent Communication Bus

Since each subagent runs in its own isolated context with no shared memory, shared/ is how agents exchange findings:

• Write-only for agents — audit agents (aws-security, aws-iam, aws-finops) write findings here and never touch source Terraform files.
• Cross-agent input — an agent can read another agent's output file before writing its own, avoiding duplicate findings. For example, the IAM agent reads shared/security-audit-dev.md to build on the security agent's work rather than repeat it.
• Human-readable audit trail — all findings accumulate in one place, making it easy to review results, track remediation progress, or feed issues into a ticketing system.
• Scope enforcement — the rule "write findings only to your designated file under shared/" keeps agents from stepping on each other's work or accidentally modifying infrastructure.

In short: it replaces direct agent-to-agent memory since subagents are stateless by default.

The Four Specialized Agents

Agent	Domain	Tools	Output
aws-platform	VPC, EKS, RDS, EC2, S3, Terraform modules	Read, Write, Edit, Bash, Glob, Grep	shared/platform-findings.md
aws-iam	IAM roles/policies, SCPs, OIDC, permissions boundaries	Read, Write, Edit, Bash, Glob, Grep	shared/iam-findings.md
aws-security	CloudTrail, GuardDuty, Security Hub, Config, threat modeling	Read, Bash, Glob, Grep (read-only)	shared/security-findings.md
aws-finops	Cost waste, tagging gaps, RI/SP coverage, rightsizing	Read, Bash, Glob, Grep (read-only)	shared/finops-findings.md

Each agent is defined in .claude/agents/<name>.md with a frontmatter block specifying its name, description, and allowed tools. The CLAUDE.md file at the repo root injects shared context (account layout, tagging standards, toolchain) into every agent's context window.

How to Run

Invoke agents from the Claude Code CLI using the aws-<name>: prefix:

# Run a single agent
aws-security: audit all detective and preventive controls in terraform/envs/dev/main.tf

# Run multiple agents in parallel (Claude will launch them concurrently)
aws-security: audit terraform/envs/dev/main.tf
aws-iam: check all IAM roles and policies for least privilege and missing boundaries
aws-finops: identify waste and savings opportunities across terraform/envs/dev and terraform/envs/staging

Claude Code launches the agents in parallel, each reading the Terraform source and writing findings to its designated file under shared/.

What the Dev Environment Contains (Intentional Issues)

terraform/envs/dev/main.tf is seeded with deliberate misconfigurations for agents to find:

Security issues

• Hardcoded RDS password in plaintext ("SuperSecret123!")
• RDS instance with publicly_accessible = true
• SSH open to 0.0.0.0/0 on the bastion security group
• IMDSv2 not enforced (http_tokens = "optional")
• No CloudTrail, GuardDuty, VPC Flow Logs, or Security Hub

IAM issues

• Wildcard actions (s3:*, ec2:*, rds:*) on Resource: "*"
• No permissions boundary on the app role
• Inline policy instead of managed policy
• Trust policy with no condition keys (any EC2 in account can assume the role)

Cost/FinOps issues

• c5.4xlarge EC2 instance (oversized for dev — should be t3.large on Spot)
• Three NAT Gateways in dev (one is sufficient)
• RDS with multi_az = true (unnecessary in dev)
• No S3 lifecycle policy, no versioning, no public access block
• Mandatory tags missing from virtually every resource

Platform/architecture issues

• Wrong VPC CIDR (10.99.0.0/16 vs. convention 10.10.0.0/16)
• Only one AZ defined (should be three)
• MySQL instead of Postgres (org standard)

Agent Coordination Rules

Rules defined in CLAUDE.md apply to all agents:

• Agents announce their scope in the first message
• Findings are written only to shared/ — agents never modify source Terraform files
• terraform apply is never run — plan and validate only
• .terraform.lock.hcl files are never edited (causes merge conflicts)
• Agents message each other directly when blocked on another agent's output

Infrastructure Context

Environment	Purpose	Primary Region	DR Region
dev	Developer workloads	us-east-1	—
staging	Pre-prod validation	us-east-1	—
prod	Production	us-east-1	us-west-2
shared-svc	ECR, Vault, internal tooling	us-east-1	—

Toolchain: Terraform 1.9+, Terragrunt 0.55+, AWS CLI v2, Python 3.12 (Lambda), EKS 1.30

CI/CD: GitHub Actions with OIDC federation (no long-lived keys), promotion flow: dev → staging → prod with manual approval gate before prod, nightly drift detection via terraform plan.

Secrets: HashiCorp Vault (primary), AWS Secrets Manager (secondary) — all encrypted with customer-managed KMS keys.

Mandatory tags on all resources: Environment, Team, CostCenter, Owner, ManagedBy, Repo, Service