Cache Eviction Policy AGENTS.md Template

Overview

Direct answer: This AGENTS.md Template defines an agent workflow for cache eviction policy reviews, enabling single-agent operations and coordinated multi-agent orchestration with clear handoffs and governance. It provides a practical operating manual for AI coding agents working on eviction policy assessments, validation, and deployment readiness.

When to Use This AGENTS.md Template

• When auditing or updating cache eviction policies across services with shared caches.
• When multiple teams must coordinate decisions (routing, TTLs, eviction criteria, and back-end consistency).
• When you need repeatable validation, traceability, and governance for eviction decisions.
• When introducing tool governance, security constraints, and human review gates into the policy review process.

Copyable AGENTS.md Template

# AGENTS.md

Project Role
- Owner: Cache eviction policy review across distributed systems; define policy scope and acceptance criteria.

Agent roster and responsibilities
- Planner: define goals, success criteria, and task plan; assign work to Implementer and Reviewer.
- Implementer: execute eviction policy experiments, collect metrics, and generate artifacts.
- Reviewer: validate results, ensure policy alignment with architectural constraints, and approve handoffs.
- Tester: run unit, integration, and performance tests; report regressions.
- Researcher: gather data sources, references, and policy precedents.
- Domain Specialist: ensure eviction rules respect storage topology, coherence, and SLA commitments.

Supervisor or orchestrator behavior
- Orchestrator maintains global context, enforces memory of decisions, and records all actions for traceability.
- Enforces tool governance, permission boundaries, and escalation paths.

Handoff rules between agents
- Planner → Implementer: after scope and acceptance criteria are defined.
- Implementer → Reviewer: after experiments and artifacts are produced.
- Reviewer → Planner (if changes are needed) or to Tester/Domain Specialist for deeper checks.

Context, memory, and source-of-truth rules
- All decisions must reference the policy document, eviction criteria, TTLs, and observed metrics.
- Store artifacts in a central data store with versioned snapshots; link to source code and test results.

Tool access and permission rules
- Agents may read policy docs, query metrics stores, and call read-only APIs.
- Write access is restricted to Implementer and approved IAC pipelines; secrets never logged.

Architecture rules
- Align eviction logic with service-level objectives and cache invalidation patterns. Do not embed policy decisions in client-side code.

File structure rules
- Keep all policies, experiments, and results under cache-eviction-policy-review/ with clear versioning.

Data, API, or integration rules when relevant
- Use immutable data sources for policy validation; document API contracts and dependency versions.

Validation rules
- Validation must demonstrate correctness, performance impact, and consistency with architecture.

Security rules
- Do not expose eviction criteria publicly; ensure access controls on policy artifacts.

Testing rules
- Include unit tests for eviction decision logic and integration tests that cover end-to-end eviction scenarios.

Deployment rules
- Eviction policy changes require review, automated tests, and staged rollout with rollback capability.

Human review and escalation rules
- Escalate to policy owner if automated checks fail; require human override only via approved channels.

Failure handling and rollback rules
- If eviction behavior regresses, revert to last known-good policy version; capture rollback steps in the AGENTS.md.

Things Agents must not do
- Do not modify production configuration without approval; do not bypass tests; do not introduce hard-coded secrets.

Recommended Agent Operating Model

Roles and decision boundaries are defined to ensure safe, observable, and auditable policy reviews. The Planner decides scope and acceptance criteria; the Implementer runs experiments and gathers evidence; the Reviewer signs off on results and ensures alignment with governance; the Tester validates correctness and performance; the Researcher and Domain Specialist provide context and domain constraints. Escalation paths exist for unresolved conflicts or policy violations.

Recommended Project Structure

cache-eviction-policy-review/
├── orchestrator/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── reviewer/
│   ├── tester/
│   ├── researcher/
│   └── domain-specialist/
├── policies/
├── data/
├── integrations/
├── tests/
└── docs/

Core Operating Principles

• Agent actions are auditable and reproducible.
• Handoffs occur at clear milestones with artifact notation.
• Decision boundaries are explicit and aligned with policy ownership.
• Context memory is explicit and sourced from trusted data stores.
• Strict tool governance and access control across the workflow.

Agent Handoff and Collaboration Rules

• Planner and Implementer collaboration ensures scope clarity before experiments.
• Implementer and Reviewer share artifacts and evidence with traceability.
• Researcher informs Domain Specialist to enforce domain constraints.
• Domain Specialist to Producer when policy decisions touch deployment boundaries.

Tool Governance and Permission Rules

• Commands to run experiments must be sandboxed; production systems require approvals.
• File edits are version-controlled; secrets never written in code or logs.
• API calls follow tight rate limits and require scope-based tokens.
• Approval gates must be present for any policy change deployment.

Code Construction Rules

• Write modular, testable eviction logic; avoid hard-coded values.
• Document assumptions and edge cases; annotate decisions inline.
• Maintain backward compatibility where possible.

Security and Production Rules

• Keep eviction policy artifacts access-controlled and auditable.
• Use feature flags for policy rollouts; provide rollback paths.

Testing Checklist

• Unit tests for eviction decision logic.
• Integration tests for end-to-end eviction scenarios.
• Performance tests to ensure eviction does not regress latency.
• Security tests to validate access controls and secret handling.
• Deployment readiness checks and rollback validation.

Common Mistakes to Avoid

• Lack of traceability between decisions and artifacts.
• Unvalidated assumptions about eviction criteria.
• Bypassing governance gates for production changes.
• Insufficient domain constraints leading to policy drift.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Policy Documents and Internal Question Answering.

FAQ

What is an AGENTS.md Template?

An AGENTS.md Template is a copyable operating manual for AI coding agents that defines roles, handoffs, and governance for a specific workflow.

Why use this template for cache eviction reviews?

It standardizes agent collaboration, policy validation, and tool governance to ensure eviction decisions are traceable, reproducible, and cross-checked.

Who should follow this template?

Engineers, platform teams, SREs, and AI governance leads who implement or oversee cache eviction policy reviews.

What outputs should agents produce?

A structured policy review with decisions, rationales, and artifacts showing validation, testing, and deployment readiness.

How does escalation work?

Escalation routes to a human reviewer or policy owner when automation cannot resolve conflicts or detect policy violations.