AGENTS.md Template for Reverse Proxy Architecture

Overview

The AGENTS.md template for reverse proxy architecture defines the operating model and workflow for AI coding agents tasked with designing, configuring, and operating a secure reverse proxy layer. It supports both single-agent execution and multi-agent orchestration across planning, implementation, validation, and deployment phases.

Direct answer: This page codifies the roles, handoffs, memory and source-of-truth rules that govern the proxy workflow and ensures tool governance and human review when needed.

When to Use This AGENTS.md Template

• Use when you are building or evolving a reverse proxy architecture and need clear operating context for AI agents.
• When you require formal handoff rules between planner, implementer, tester, and reviewer to reduce drift.
• When multi-agent orchestration and governance are needed for TLS, routing, caching, and security policies.

Copyable AGENTS.md Template

# AGENTS.md
Project Role: Reverse Proxy Architecture AI agents team. The aim is to design, implement, test, and operate a secure, high-availability reverse proxy layer using AI coding agents. This AGENTS.md template provides the project-level operating context for single-agent and multi-agent workflows.
Agent roster and responsibilities:
- Planner: crafts the traffic routing strategy, TLS termination policy, caching strategy, and fault-tolerance plan.
- Implementer: translates the plan into concrete proxy configuration (Envoy/Nginx), updates configs, and applies changes.
- Security Specialist: ensures encryption, TLS cert management, mTLS, token-based auth, and audit logging.
- Researcher: gathers best practices, performance tuning, and vulnerabilities related to reverse proxy.
- Tester: executes functional, performance, and resilience tests; validates canaries.
- Reviewer: reviews changes, validates against policy, approves for deployment.
- Domain Specialist: focuses on network security, WAF rules, and region-specific compliance.
- Operator: runs the proxy in staging and production, monitors health.
Supervisor or orchestrator behavior:
- The orchestrator coordinates agent tasks, enforces sequencing (Planner -> Implementer -> Tester -> Reviewer -> Operator), and halts on risk.
- It maintains a canonical memory store and source-of-truth (SOT) for proxy configs, TLS certs, and runtime policies.
- It propagates decisions with explicit reasons and expected outputs.
Handoff rules between agents:
- Planner to Implementer: hand off the concrete config patch, dependencies, and validation criteria.
- Implementer to Tester: provide test plan, canary steps, and expected outcomes.
- Tester to Reviewer: deliver test results with evidence.
- Reviewer to Operator: publish approved changes to production with rollback trigger.
Context, memory, and source-of-truth rules:
- Context includes: current network topology, TLS certificates, origin services, cache rules, rate limits.
- Memory is scoped to the current plan; persistence is through the SOT (config repo, secret store, monitoring dashboards).
- Source-of-truth is the single source: the config repository and secrets store; outputs are stored as immutable artifacts.
Tool access and permission rules:
- Access is restricted to: config repos, proxy management APIs, and certificate stores.
- Secrets must be accessed via a secrets manager with rotation policies; never hard-code credentials.
- Production changes require an approved plan and a canary evaluation.
Architecture rules:
- Use a layered approach: edge proxy, auth layer, routing layer, cache layer.
- TLS termination at the edge; support end-to-end TLS where possible.
- Can apply WAF rules, rate-limiting, IP allowlists, and anomaly detection.
- Ensure observability via tracing, metrics, and logs.
File structure rules:
- Only include files/directories needed for the current workflow.
- Keep configs under configs/, policies under policies/, scripts under scripts/.
- Do not store secrets in plain text files.
Data, API, or integration rules:
- Inputs: service registry, policy definitions, TLS secrets, certificate status.
- Outputs: proxy config patches, deployment manifests, validation reports.
- Integrations: CI/CD, certificate manager, monitoring, and logging platforms.
Validation rules:
- All config patches must pass syntax validation and schema checks.
- Validate canary results before full rollout.
- Ensure idempotent operations and rollback capability.
Security rules:
- Enforce least privilege and audit logging.
- Rotate credentials regularly; enforce TLS1.2+ and modern ciphers.
- Enforce secret hygiene and access controls.
Testing rules:
- Unit tests for policy logic, integration tests for config patching, end-to-end tests for routing.
Deployment rules:
- Deploy via canary canary step; require approval for production.
- Maintain rollback plan and hidden feature toggles.
Human review and escalation rules:
- Any security policy change requires a security review.
- Escalate to on-call if traffic patterns indicate anomalies.
Failure handling and rollback rules:
- If rollout fails, roll back to previous stable config and run a fresh validation.
- Maintain a canary path with limited traffic during rollback.
Things Agents must not do:
- Do not bypass security or share secrets.
- Do not modify production routing without tests and approvals.
- Do not drift from canonical SOT.

Recommended Agent Operating Model

The AGENTS.md Template for reverse proxy architecture defines the operating boundaries for planners, implementers, testers, reviewers, researchers, and domain specialists. Decisions must be clearly bounded, with escalation paths for security or reliability concerns. The orchestrator is the central authority for sequencing, canary gating, and rollback triggers.

Recommended Project Structure

project-root/
  agents/
    planner/
    implementer/
    tester/
    reviewer/
    researcher/
    domain-specialist/
  configs/
  policies/
  scripts/
  dashboards/
  tests/
  deployments/

Core Operating Principles

• Single source of truth for proxy config and secrets; idempotent changes; explicit handoffs.
• Guardrails with human review for security and policy changes.
• Strong separation of duties among planner, implementer, tester, and reviewer.
• Full auditability and traceability of decisions and outputs.

Agent Handoff and Collaboration Rules

• Planner communicates plan and constraints to Implementer with acceptance criteria.
• Implementer shares patch details and test plan with Tester.
• Tester provides validation results to Reviewer.
• Reviewer approves or requests changes before Operator deploys.
• Domain Specialist reviews network security policies and WAF rules during collaboration.

Tool Governance and Permission Rules

• Only authorized agents may run config changes or API calls to proxy systems.
• Secrets must be retrieved from a secrets manager; never stored in plain text.
• Production changes require approval gates and audit trails.

Code Construction Rules

• Config patches must be patch-based and auditable; avoid full re-writes without review.
• Maintain idempotent scripts; validate before apply.
• Use descriptive variable names and inline comments in policy scripts.

Security and Production Rules

• Enforce least privilege access; rotate keys; monitor for anomalies.
• Implement canary deployments and allow quick rollback with clear indicators.
• Record all security-related changes and hold for audits.

Testing Checklist

• Unit tests for policy logic and config validators.
• Integration tests for patch application and rollback.
• End-to-end tests simulating traffic through the proxy.

Common Mistakes to Avoid

• Skipping canary deployments; making production changes without tests.
• Leaking secrets or hardcoding credentials.
• Ignoring drift between canonical SOT and deployed configs.

FAQ

What is the purpose of this AGENTS.md Template for Reverse Proxy Architecture?

It provides a formal, copyable operating manual for AI coding agents to design, configure, and operate a reverse proxy with multi-agent orchestration.

How does multi-agent orchestration work in this template?

It defines roles, handoffs, and memory; planners create a plan, implementers apply changes, testers validate, reviewers approve, and operators deploy with canary gating.

What are the agent handoff rules?

Handoffs require explicit artifacts, acceptance criteria, and test results stored in the canonical SOT.

What security measures are included?

Least privilege access, secrets management, audit logging, canary deployments, and strict change approvals.

How is testing integrated?

Unit, integration, and end-to-end tests validate config patches and routing before production.

What should I do if a rollout fails?

Rollback to the previous stable config and re-run validation and canary tests before retrying deployment.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Agent Use Case for Food Processors Using Production Line Check-Sheets To Build Audit-Ready Food Safety Compliance Reports.