Envoy Proxy System Design AGENTS.md Template - AGENTS.md template

Overview

Direct answer: This AGENTS.md template provides a complete operating manual for coordinating single-agent and multi-agent workflows around Envoy config, routing, and control-plane interactions.

When to Use This AGENTS.md Template

• Use when designing or evolving an Envoy-based service mesh or edge proxy with dynamic config via a control plane or management plane.
• Use to coordinate multiple AI coding agents across config generation, validation, rollout, and monitoring.
• Use to establish clear handoffs, memory rules, and governance for Envoy-related automation.

Copyable AGENTS.md Template

# AGENTS.md
Project role: Platform Engineer or Site Reliability Engineer leading Envoy system design.
Agent roster and responsibilities:
- PlannerAgent: designs the workflow and sequencing for Envoy config changes.
- ConfigGenAgent: generates Envoy listener/cluster/route configurations based on input specs.
- ValidatorAgent: validates generated configs against schema, policies, and compatibility rules.
- DeployerAgent: applies changes to Envoy via control plane APIs and ensures zero-downtime rollout.
- MonitorAgent: observes traffic, metrics, and health to detect anomalies post-deploy.
- ReviewerAgent: performs on-call review and approves changes for production.
- ResearchAgent: investigates edge cases, alternative configs, and performance considerations.
- DomainSpecialistAgent: provides domain-specific guidance (security, routing, or observability).
Supervisor or orchestrator behavior:
- Orchestrator has final say on sequencing, timing, and rollbacks; it logs decisions and enforces approvals for production.
Handoff rules between agents:
- Planner -> ConfigGen: handoff plan and input specs; produce a concrete candidate config.
- ConfigGen -> Validator: handoff generated config; include validation results.
- Validator -> Deployer or Reviewer: if valid, proceed to deploy; if not, loop back to Planner with fixes.
Context, memory, and source-of-truth rules:
- Use a single source of truth: the git repo with commit SHAs and an auditable change log.
- Memory is scoped to the current run; avoid cross-run leakage.
- All decisions recorded in the orchestrator log and linked to the change request.
Tool access and permission rules:
- Access to git repos, Envoy Admin APIs, and control plane interfaces is RBAC-protected.
- Secrets stored in a vault; avoid hard-coding credentials.
Architecture rules:
- Event-driven, idempotent, and auditable changes; support replay in case of failure.
File structure rules:
- Keep changes under configs/envoy/, policies/, and manifests/.
Data, API, or integration rules:
- All changes are validated before apply; use feature flags for risk mitigation.
Validation rules:
- YAML/JSON syntax validation; schema conformance; route/cluster consistency checks.
Security rules:
- Enforce mTLS, least privilege, and rotate credentials on change; restrict admin ports.
Testing rules:
- Unit tests for config generation; integration tests with a mock Envoy; end-to-end tests in staging.
Deployment rules:
- CI/CD gates, canary or blue-green rollout; rollback paths documented.
Human review and escalation rules:
- When confidence is below threshold or risk is high, escalate to on-call engineer; require human sign-off for production.
Failure handling and rollback rules:
- If deployment fails, rollback to previous good config and notify on-call; preserve rollbacks in changelog.
Things Agents must not do:
- Modify beyond scope; bypass approvals; reveal secrets in logs; skip validation; perform unsupervised production changes.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are designed for Envoy system design. Planner and ConfigGen determine the candidate config; Validator ensures correctness; Deployer executes with safe rollout; Monitor validates post-deploy; Human and Domain Specialists provide oversight when risk is elevated.

Recommended Project Structure

envoy-system-design/
├── agents/
│   ├── planner/
│   │   └── planner_agent.py
│   ├── config-gen/
│   │   └── config_gen_agent.py
│   ├── validator/
│   │   └── validator_agent.py
│   ├── deployer/
│   │   └── deployer_agent.py
│   ├── monitor/
│   │   └── monitor_agent.py
│   ├── reviewer/
│   │   └── reviewer_agent.py
│   ├── researcher/
│   │   └── researcher_agent.py
│   └── domain-specialist/
│       └── domain_specialist_agent.py
├── configs/
│   └── envoy/
│       ├── production/
│       └── staging/
├── policies/
├── manifests/
├── tests/
└── docs/

Core Operating Principles

• Single source of truth via a version-controlled change log and config repo.
• Idempotent, deterministic agent actions with clear outcomes.
• Explicit handoffs and verifiable state between agents.
• Automation with governance and human-in-the-loop when risk is elevated.

Agent Handoff and Collaboration Rules

• Planner provides the overall plan and constraints; ConfigGen consumes the plan.
• ConfigGen reports generation results and conflicts back to Planner and Validator.
• Validator enforces schema and policy compliance; if issues arise, it prompts Planner for changes.
• Deployer coordinates rollout windows and health checks; Monitor observes outcomes and triggers rollback if needed.
• Researcher and Domain Specialist provide guidance on edge cases and best practices.

Tool Governance and Permission Rules

• Command execution requires explicit approval in the orchestrator; destructive actions require on-call or change control.
• Edits to configs/files are tracked in the change log and repository; secrets are never written to logs.
• External service calls must go through approved interfaces; credentials are rotated and stored securely.
• Production systems require review for safety and compliance; automated tests must pass before deploy.

Code Construction Rules

• All generated Envoy configs must be idempotent and deterministic.
• Use templates and parameterization for repeatable config generation.
• Validate configs against the Envoy schema before apply.
• Do not bypass tests; do not skip validation or security checks.

Security and Production Rules

• Enforce mTLS; restrict admin interfaces; rotate credentials; audit all changes.

Testing Checklist

• Unit tests for config generation; integration tests with a mock Envoy; end-to-end tests in staging; canary tests for production.

Common Mistakes to Avoid

• Skipping validation or security checks.
• Directly editing production configs without approvals.
• Unclear handoffs or missing memory rules leading to drift.

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 for Envoy proxy system design?

This AGENTS.md template provides a complete operating manual for coordinating single-agent and multi-agent workflows around Envoy config, routing, and control-plane interactions.

How should handoffs occur between Planner, ConfigGen, Validator, and Deployer?

Handoff follows a strict plan: Planner -> ConfigGen with input specs, ConfigGen -> Validator with the generated config and results, Validator -> Deployer (or Reviewer) if valid; otherwise Planner revises and repeats.

How are Envoy configs validated and deployed safely?

Configs are validated against the Envoy schema and policies, then deployed via controlled release mechanisms with health checks and canary or blue-green strategies.

What security considerations are specified in this template?

Secrets are stored in a vault, admin interfaces are protected, and access is restricted; all changes are auditable and rotated as needed.

How do you perform rollback when a deployment fails?

Rollback uses the previous good commit in the change log and config repo; monitor alerts trigger, and on-call engineers verify before promotion.