AGENTS.md Template for Database Query Result Caching

Overview

AGENTS.md template for database query result caching defines how AI coding agents coordinate to cache, invalidate, and retrieve database query results. It governs single-agent operation and multi-agent orchestration while maintaining a single source of truth and auditable handoffs.

When to Use This AGENTS.md Template

• Implement a caching layer to reduce database load and latency for frequently-run queries.
• Coordinate multiple agents to manage cache population, invalidation, and statistics collection.
• Enforce tool governance, secret handling, and secure access to data stores in both development and production environments.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Platform Engineer / Cache Architect

Agent roster and responsibilities:
- CacheCoordinator (Planner/Orchestrator): enforces policy, routes work, and ensures idempotent operations.
- CacheAgent: handles cache get/set and key construction.
- DBAgent: reads data from the database on cache miss and returns results.
- InvalidationAgent: invalidates cache entries when source data changes.
- MetricsAgent: collects hit/miss and latency metrics.
- ReviewerAgent: validates outputs before deployment.

Supervisor / Orchestrator behavior:
- Enforce TTL policies, guardrails, and correct handoffs between agents.
- Abort or retry on non-recoverable errors, with clear escalation.

Handoff rules between agents:
- Client request → CacheAgent checks cache.
- On hit: return data to client.
- On miss: CacheAgent passes to DBAgent; DBAgent fetches from DB and returns to CacheAgent.
- CacheAgent writes to cache and returns data to client.
- Invalidation events propagate through InvalidationAgent to clear affected keys.

Context, memory, and source-of-truth rules:
- Source of truth is the database. Cache is near-term memory with TTLs governed by policy.
- All writes flow through the write path and invalidate dependent cached entries.
- Memory includes last TTL, key format, and last known data version.

Tool access and permission rules:
- Access to Redis (or Redis-like cache), Postgres databases, and a secrets manager is required.
- Use least privilege for each agent; no direct admin access from client agents.

Architecture rules:
- Microservice style: a stateless orchestrator and specialized agents.
- Cache layer acts as a separate service with clear boundary APIs.

File structure rules:
- Do not include irrelevant folders; keep this structure:
  - src/
    - orchestrator/
    - agents/
      - cache_agent/
      - db_agent/
      - invalidation_agent/
      - metrics_agent/
      - reviewer_agent/
    - configs/
    - tests/
  - deploy/
  - docs/

Data, API, or integration rules:
- Cache keys follow a naming scheme: app:entity:id:field.
- TTL policy fetched from a centralized config service; cache must validate TTL before serving.
- All DB reads go through DBAgent; no direct DB queries by client code.

Validation rules:
- Validate cache hits with a deterministic key and TTL.
- Ensure data is consistent with the source of truth after writes.

Security rules:
- Do not store raw secrets in code. Use a secrets manager.
- Ensure tokens used by agents are scoped and rotated.

Testing rules:
- Unit tests for each agent, integration tests for the orchestrator, and end-to-end tests for cache heat and invalidation.

Deployment rules:
- Use CI/CD with canary deploys and feature flags for TTL policy changes.

Human review and escalation rules:
- Any TTL policy change or new agent requires approval.
- Escalate failures to on-call with detailed traceability.

Failure handling and rollback rules:
- If the DB read fails, return an error to client or fallback to last known good value if available.
- Do not write to cache on failed reads; ensure idempotent writes.

Things Agents must not do:
- Do not bypass authentication or authorization checks.
- Do not mutate source of truth data.
- Do not perform unapproved config or secret changes.

Recommended Agent Operating Model

The agent operating model defines clear roles and decision boundaries. Planner coordinates tasks and enforces policy; Implementers execute cache and DB reads; Reviewers validate outputs; Testers verify correctness; Researchers explore data/versioning needs; Domain Specialists provide domain-specific constraints.

Recommended Project Structure

project-root/
  orchestrator/
  agents/
    cache_agent/
    db_agent/
    invalidation_agent/
    metrics_agent/
    reviewer_agent/
  configs/
  tests/
  deploy/
  docs/

Core Operating Principles

• Single source of truth: database; cache is a policy-driven, near-term layer.
• Idempotent agent actions with explicit handoffs.
• Least privilege for tool access and secure secrets handling.
• Traceable decisions with auditable prompts and memory.
• Deterministic TTL-based invalidation and refresh policies.

Agent Handoff and Collaboration Rules

• Planner → Implementer: pass policy, TTL, and key schema; validate before handoff.
• Implementer → Reviewer: deliver outputs and test results; await approval.
• Researcher → Planner: surface data versioning requirements and edge cases.
• Domain Specialist → All: confirm data sensitivity and regulatory constraints.

Tool Governance and Permission Rules

• Commands to execute: read cache, write cache, fetch DB, invalidate keys, run tests.
• File edits: only through approved agent scripts; avoid manual edits in prod.
• API calls: go through orchestrator with audit trails.
• Secrets: store in a secret manager; rotate on schedule.
• Production systems: require approvals for changes to TTL and cache strategies.

Code Construction Rules

• Implement cache key generation deterministically.
• Validate inputs and sanitize query results before caching.
• Expire stale data and refresh in the background when appropriate.
• Avoid duplicating data and ensure idempotent writes to cache.

Security and Production Rules

• Enforce TLS for all communications; authenticate agents.
• Do not store plaintext credentials; use secrets vaults.
• Monitor cache miss latency and set alarms for anomalies.

Testing Checklist

• Unit tests for each agent function.
• Integration tests for orchestrator flows.
• End-to-end tests for cache hit/miss, invalidation, and TTL policies.
• Security tests for secret handling and access controls.

Common Mistakes to Avoid

• Over-optimistic caching without considering write-through consistency.
• Bypassing the orchestrator to access DB directly.
• Neglecting invalidation on data changes.
• Inconsistent TTL configurations across environments.

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 an AGENTS.md Template for this workflow?

It is a copyable operating manual that standardizes how AI coding agents manage database query result caching, including handoffs, tool governance, and security rules.

Who should use this template?

Platform engineers, data engineers, and product teams implementing a caching layer with multi-agent orchestration.

What outputs should this AGENTS.md produce?

Clear cache keys, TTL policy, handoff rules, and validation logic that can be pasted into a repository as a living operating manual.

How are handoffs enforced between agents?

Through the CacheCoordinator orchestrator, with explicit sequence rules and versioned policies; failures escalate to human review.

What happens on cache invalidation?

Invalidation clears affected keys and triggers a refresh workflow to repopulate the cache from the DB or new data.