Edge Cache AGENTS.md Template

Overview

The AGENTS.md template explains how to design and operate an edge caching system using AI coding agents and multi-agent orchestration. It defines roles, rules, and handoffs for individual agents and the orchestrator, and prescribes memory, source-of-truth, and tool governance patterns suitable for edge networks, CDNs, and origin services. Direct answer style: this page provides a practical, copyable operating manual for edge cache workflows that maintains policy, auditability, and safe escalation.

When to Use This AGENTS.md Template

• Designing a production-grade edge cache with AI agents and clear handoffs.
• Establishing governance for tool access, secrets, and deployment changes at the edge.
• Coordinating planner, implementer, reviewer, tester, researcher, and domain specialist roles for edge cache policies.
• Defining validation, security, and rollback rules before rolling out edge caching changes.

Copyable AGENTS.md Template

Paste this block into your project as AGENTS.md to serve as operating context for single-agent and multi-agent workflows.

# AGENTS.md

Project Role
- Edge Caching System Design with AI Agents and multi-agent orchestration across a CDN and edge network.

Agent roster and responsibilities
- Planner (Edge Architect): defines caching strategy, TTLs, cache keys, invalidation rules, and orchestration flow.
- Implementer (Cache Engine Integrator): implements policy, origin fetch integration, and CDN configuration hooks.
- Reviewer: validates outputs against requirements and edge constraints.
- Tester: performs unit, integration, and end-to-end tests for edge cache behavior.
- Researcher: collects data on edge patterns, cache hit/miss metrics, and network constraints.
- Domain Specialist (CDN/Edge Network): provides network-level policies and constraints.

Supervisor or orchestrator behavior
- The orchestrator collects outputs from all agents, enforces tool governance, and gates risky changes with human review when needed.

Handoff rules between agents
- Planner passes a concrete plan to Implementer with inputs and success criteria.
- Implementer executes changes and reports results to Reviewer.
- Reviewer validates outputs and passes to Tester.
- Tester validates readiness for production; orchestrator approves rollout.

Context, memory, and source-of-truth rules
- Use a central knowledge store named edge_cache_context for all context.
- Source of truth is the canonical edge_cache_config.json in the repo and linked artifacts.

Tool access and permission rules
- Agents may call origin fetch APIs, CDN config endpoints, and cache APIs with scoped permissions.
- Secrets must be retrieved from a secret vault; do not hardcode credentials.

Architecture rules
- Microservice style: edge origin fetcher, cache engine, policy engine, orchestrator.
- Idempotent operations and auditable changes.

File structure rules
- Directory tree:
  edge-cache/
    orchestrator/
    planner/
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
    configs/
    docs/

Data, API, or integration rules
- Use origin API to fetch content, cache keys to TTL policy, CDN for distribution.
- TTL and invalidation rules must be versioned in configs.

Validation rules
- Validate TTL within allowed ranges and ensure cache hit ratio improves.
- Validate error handling and fallback behaviors.

Security rules
- Enforce TLS everywhere, rotate secrets, and restrict production changes to approved paths.

Testing rules
- Unit tests for TTL computation, integration tests for origin fetch, and end-to-end tests for edge path.

Deployment rules
- Canary and staged rollout with monitoring windows.

Human review and escalation rules
- Any policy or TTL change beyond defined thresholds requires human sign-off.

Failure handling and rollback rules
- If edge cache policy fails, rollback to previous config and cache policy baseline.

Things Agents must not do
- Do not bypass origin fetch checks or health checks.
- Do not modify production without approval.
- Do not leak secrets or expose credentials.
- Do not drift from approved architecture or introduce unsanctioned services.

Recommended Agent Operating Model

• Roles and responsibilities are clearly delineated; decision boundaries are explicit.
• The orchestrator enforces policy, resets state on failure, and escalates to human review when risk thresholds are crossed.
• Escalation paths exist for security incidents, deployment failures, and critical data issues.

Recommended Project Structure

edge-cache/
  orchestrator/
  planner/
  implementer/
  reviewer/
  tester/
  researcher/
  domain-specialist/
  configs/
  docs/

Core Operating Principles

• Deterministic outputs and idempotent operations
• Single source of truth for cache policy and TTLs
• Explicit handoffs and auditable decision logs
• Least privilege for all tools and secrets
• Continuous validation and safe rollback paths

Agent Handoff and Collaboration Rules

• Planner to Implementer: include policy, inputs, success criteria
• Implementer to Reviewer: provide artifacts, tests, and verification data
• Reviewer to Tester: approve test plan and validation results
• Tester to Orchestrator: deliver rollout readiness and risk assessment
• Domain Specialist coordinates with Planner and Implementer on edge constraints

Tool Governance and Permission Rules

• Limit actions to configured endpoints; require approvals for production changes
• Secrets stored securely; rotate on schedule and after incidents
• All tooling access logged; trigger alerts on anomalous access patterns

Code Construction Rules

• Prefer declarative policies over imperative changes when possible
• Cache keys must be stable and versioned
• TTL values validated against allowed ranges
• All changes are traceable and reversible

Security and Production Rules

• Mutual TLS between edge components
• Secrets rotation and least-privilege access
• Production changes gated by tests, reviews, and canary windows

Testing Checklist

• Unit tests for TTL logic and invalidation rules
• Integration tests for origin fetch and cache path
• End-to-end tests with canary rollout
• Performance tests focusing on cache hit ratio and latency

Common Mistakes to Avoid

• Skipping human review for policy changes
• Overly aggressive TTLs causing cache incoherence
• Misconfiguring cache keys leading to cache misses and stale content
• Exposing secrets or bypassing secret vaults

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 Wholesalers Using Multi-Currency Ledger Trackers To Calculate Foreign Exchange Risk Exposure Across Global Accounts.

FAQ

What is the purpose of this AGENTS.md Template for edge caching design?

This AGENTS.md template defines the operating manual for AI agents collaborating on an edge caching workflow, including roles, handoffs, tool governance, and security rules.

How do agents coordinate handoffs in the edge cache workflow?

Plans move from Planner to Implementer, results go to Reviewer, then to Tester, and finally to the orchestrator for production rollout after validation.

What governance is required for edge cache changes?

All changes require scoped tool permissions, secret handling via vault, and a formal review and approval process before production deployment.

How is security enforced in this template?

TLS, secret rotation, least privilege access, auditable actions, and restricted production change gates ensure edge deployment integrity.

What metrics are used to validate edge cache work?

Key metrics include cache hit ratio, latency, origin fetch failures, and successful TTL-based invalidations against SLA targets.