AGENTS.md Template for Layer 7 Load Balancer Design

Overview

AGENTS.md Template for Layer 7 Load Balancer Design governs the design and orchestration workflow for layer 7 proxies (HTTP/HTTPS) with AI coding agents. It supports both single-agent and multi-agent orchestration, with explicit roles, handoffs, memory, and source-of-truth rules.

Direct answer: This AGENTS.md template provides a repeatable operating context for designing, validating, and deploying a Layer 7 load balancer configuration using AI agents, with explicit roles and handoffs to ensure safe production changes.

When to Use This AGENTS.md Template

• Design Layer 7 routing policies (host/path rules, TLS termination, header manipulation) for HTTP/HTTPS traffic.
• Coordinate multi-agent workflows (planner, implementer, tester, reviewer) to avoid single-point failures.
• Ensure governance, auditability, rollback, and human review for production LB changes.
• Codify tool governance and security constraints for load balancer workflows.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Layer 7 Load Balancer Design Automation

Agent roster and responsibilities:
- Planner: defines scope, acceptance criteria, and high-level plan.
- Implementer: generates config fragments, implements routing and TLS rules.
- Tester: validates config syntax, routing behavior, and security constraints.
- Researcher: investigates LB features, best practices, and edge cases.
- Reviewer: verifies configuration, coverage, and safety.
- Domain Specialist: networking/DevOps expert for cross-cutting constraints.

Supervisor or orchestrator behavior:
- The orchestrator coordinates tasks, enforces plan-implement-check cycles, and triggers handoffs based on completion criteria. It also enforces escalation when blockers appear.

Handoff rules:
- Planner -> Implementer when plan is approved.
- Implementer -> Tester when build is ready.
- Tester -> Reviewer when tests pass.
- Domain Specialist involved for cross-cutting validations or when complex routing is in play.

Context, memory, and source-of-truth rules:
- Memory: store decisions, config fragments, and test results in a project memory block within AGENTS.md.
- Source of truth: architecture docs, config templates, and LB design repo.
- All decisions must reference the design artifacts in the repo.

Tool access and permission rules:
- Tools: Terraform/Ansible for infra, Envoy/Nginx config templating, certificate management tooling.
- Access: Planner and Implementer have write access to templates and configs; Tester has read access to code and write access to test results; secrets are restricted.

Architecture rules:
- Stateless LB instances, centralized policy engine, and consistent routing logic.
- TLS termination at edge or at gateway, with end-to-end options where needed.
- Centralized certificate management and rotation.

File structure rules:
- Only project-relevant folders: infra/lb/configs, infra/lb/templates, tests/, docs/, memory/.

Data, API, or integration rules when relevant:
- Fetch TLS certs from vault or CA service; use design templates for config generation; integrate with CI for validation.

Validation rules:
- Lint config, validate syntax, run unit and integration tests, ensure routing rules comply with requirements.

Security rules:
- Do not expose secrets; restrict edits via RBAC; require approvals for production changes; log all actions.

Testing rules:
- Unit tests for config templates; integration tests for routing; end-to-end tests in staging before prod.

Deployment rules:
- Deploy to staging; require human review for prod deployment; use canary where possible.

Human review and escalation rules:
- Any security risk or production risk triggers escalation to Eng Lead.

Failure handling and rollback rules:
- Rollback to last known-good config; preserve previous version in memory; enable feature flag to disable new changes.

Things Agents must not do:
- Do not mutate production resources directly; do not bypass tests or governance; do not drift from architecture.

Recommended Agent Operating Model

The agents operate with clear roles and decision boundaries for Layer 7 LB design. The Planner scopes the work and approves what the Implementer will execute. The Implementer translates the design into concrete configurations. The Tester validates syntax and behavior. The Reviewer signs off before production. The Domain Specialist provides architectural guardrails when routing policies are complex. Handoffs are explicit and reversible, with escalation to human review for high-risk changes.

Recommended Project Structure

infra/lb/
  configs/
    envoy.yaml
    nginx-ingress.yaml
  templates/
    lb_config_template.yaml
  tests/
    unit/
    integration/
docs/
memory/
scripts/
  generate_lb_configs.sh

Core Operating Principles

• Single source of truth for design decisions
• Explicit ownership and accountability
• Auditable changes with traceable memory and logs
• Idempotent, repeatable config generation
• Human review for production changes
• Clear separation of concerns between planning, implementation, and validation

Agent Handoff and Collaboration Rules

• Planner drafts plan and acceptance criteria; handoff to Implementer after approval
• Implementer generates configs and unit tests; handoff to Tester on completion
• Tester runs validation; if failures, hand back to Implementer or escalate to Reviewer
• Reviewer signs off; Domain Specialist validates cross-domain constraints; if issues, route to Planner

Tool Governance and Permission Rules

• Commands to deploy or modify production must pass a human gate
• Config edits are sandboxed; PR-based workflow; secrets never stored in plain text
• Infra changes require approval from security and SRE on-call rotation
• All tool actions are auditable in the memory and logs

Code Construction Rules

• Configs must be templated and parameterized
• Do not embed secrets in code or templates
• All changes must go through the AGENTS.md workflow
• Config generation should be deterministic and idempotent

Security and Production Rules

• Never bypass approvals for production changes
• Limit access to config generation tools via RBAC
• Encrypt secrets and rotate credentials regularly
• Audit all production deployments and maintain rollback points

Testing Checklist

• Unit tests for config templates
• Integration tests for routing rules and TLS termination
• Canary or staged deployment checks
• Security and compliance validations

Common Mistakes to Avoid

• Skipping human review for production changes
• Relying on undocumented handoffs or ambiguous decisions
• Exposing secrets or bypassing RBAC
• Inconsistent memory or source-of-truth references

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages.

FAQ

What is the purpose of this AGENTS.md Template for Layer 7 Load Balancer Design?

It defines a repeatable operating manual for AI coding agents involved in Layer 7 LB design, enabling explicit roles, handoffs, and governance.

Who is the intended audience?

Engineering teams building HTTP(S) routing solutions and AI agents coordinating LB workflows.

How are agent handoffs defined?

Handoffs follow Planner -> Implementer -> Tester -> Reviewer, with Domain Specialist involvement for cross-cutting validations and escalation as needed.

What should be stored in memory and what's the source of truth?

Decisions, tests, and config fragments go to the memory; architecture docs and config templates in the design repository are the source of truth.

What security measures apply?

Avoid secrets exposure, enforce RBAC, require approvals for prod changes, and maintain audit trails.