AGENTS.md Template for Vector Database Architecture

Overview

Direct answer: This AGENTS.md Template defines a vector database architecture workflow for AI coding agents, enabling both single-agent execution and multi-agent orchestration across planning, indexing, retrieval, governance, and human-in-the-loop review.

It specifies operating context, roles, memory, and tool governance to ensure repeatable, auditable vector search pipelines and safe production behavior.

When to Use This AGENTS.md Template

• When building an end-to-end vector database workflow that requires planning, indexing, retrieval, and evaluation by multiple agents.
• When you need a shared operating context that enforces tool governance, memory rules, and a single source of truth.
• When you want a reusable template that documents agent roles, handoff rules, and escalation paths for vector search architectures.

Copyable AGENTS.md Template

Use this block to initialize the agent operating context for vector database architecture. It is intended to be pasted into a project-level AGENTS.md file.

# AGENTS.md

Project role: Vector Database Architecture Agent Collaboration for end-to-end vector search pipeline, including index construction, retrieval, ranking, and governance, with multi-agent orchestration.

Agent roster and responsibilities:
- Planner: defines goals, constraints, and a plan for vector database tasks; decomposes work into tasks for Implementer, Researcher, domain-expert; sets success criteria.
- Implementer: implements code paths, integrates with vector DB API, builds ingestion and indexing pipelines, ensures compatibility with embedding models.
- Validator: checks quality, tests results, ensures data privacy, memory usage, and alignment with requirements.
- Tester: executes unit, integration, and performance tests; validates query accuracy and latency.
- Researcher: investigates indexing strategies (e.g., HNSW, IVF), embeddings, and retrieval algorithms.
- Domain-expert: provides domain-specific context (e.g., text vs. image embeddings, similarity thresholds).

Supervisor or orchestrator behavior:
- Orchestrator coordinates tasks, enforces constraints, tracks state and memory, applies governance rules, and triggers escalation when needed.

Handoff rules between agents:
- Planner passes a defined task list to Implementer; Implementer passes results to Validator; Validator flags issues back to Planner or to Domain Expert if domain questions arise; Escalations go to Human Review.

Context, memory, and source-of-truth rules:
- All decisions are recorded in a central memory file; the source of truth is a versioned data store or knowledge base; memory is append-only with versioning and traceable outputs.

Tool access and permission rules:
- Access vector DB APIs with restricted read/write to allowed indices, embeddings service, and evaluation metrics; secrets must be stored in a secret manager; no hard-coded keys.

Architecture rules:
- Modular architecture with clear boundaries between ingestion, indexing, retrieval, ranking, and governance.

File structure rules:
- Use a minimal, workflow-centric structure:
  vector-database-workflow/
  ├─ agents/
  │  ├─ planner/
  │  ├─ implementer/
  │  ├─ validator/
  │  ├─ tester/
  │  ├─ researcher/
  │  └─ domain-expert/
  ├─ memory/
  ├─ tools/
  ├─ data/
  ├─ src/
  ├─ tests/
  └─ docs/

Data, API, or integration rules:
- Follow data governance: encrypt sensitive data, respect vector database access controls, and audit API usage.

Validation rules:
- Validate embeddings shapes and dimensions; ensure index health and retrieval accuracy; verify results meet latency targets.

Security rules:
- Do not log secrets; enforce encryption at rest and in transit; rotate keys; enforce least privilege.

Testing rules:
- Unit tests for vector primitives; integration tests for indexing and retrieval pipelines; end-to-end tests simulating real queries.

Deployment rules:
- Use canary deployments for index updates; track versioned deployments and configs; rollback on failure.

Human review and escalation rules:
- For critical failures or design changes, escalate to a human reviewer; require sign-off before production changes.

Failure handling and rollback rules:
- On failure during indexing or deployment, rollback to last-good index snapshot or configuration; replay data changes as needed.

Things Agents must not do:
- Do not operate outside granted indices, do not hard-code secrets, do not perform unsupervised changes to production systems, do not bypass validation or testing.

Recommended Agent Operating Model

The recommended model assigns clear decision boundaries and escalation paths. Planner defines the objective, constraints, and acceptance criteria; Implementer builds the artifact; Researcher proposes indexing choices; Domain-expert validates domain fit; Validator confirms quality; Tester verifies performance; Orchestrator enforces governance and memory rules; Human Review intervenes for high-risk changes or failures.

Recommended Project Structure

vector-database-workflow/
├─ agents/
│  ├─ planner/
│  ├─ implementer/
│  ├─ validator/
│  ├─ tester/
│  ├─ researcher/
│  └─ domain-expert/
├─ memory/
├─ tools/
├─ data/
├─ src/
├─ tests/
└─ docs/

Core Operating Principles

• One source of truth and a versioned memory store for all decisions and outputs.
• Clear ownership and escalation paths for each task in the vector DB workflow.
• Deterministic handoffs with explicit success criteria and traceability.
• Least privilege and secrets management for all tools and APIs.
• Auditable changes with ability to rollback production updates safely.

Agent Handoff and Collaboration Rules

Planner communicates goals and plan; Implementer executes and records progress; Researcher suggests indexing and embedding options; Validator verifies outputs; Tester validates behavior; Domain-expert reviews domain fit; Orchestrator enforces timing, memory, and policy rules, triggering escalation when needed.

Tool Governance and Permission Rules

• Commands to vector DB APIs must be scoped to permitted indices and operations.
• All file edits and deployments require code review and approval gates.
• Secrets must be retrieved from a dedicated secret manager; never logged or embedded in code.
• Production systems require role-based access control and activity auditing.
• External service calls must be authenticated and rate-limited.

Code Construction Rules

• All new code paths in the vector DB workflow must include unit tests and integration tests.
• Index updates must be versioned; avoid hot-swaps without canary verification.
• Embeddings and models selected must be compatible with the existing vector index schema.
• All data imports should be validated for schema, type, and boundary conditions.

Security and Production Rules

• Encrypt data at rest and in transit; rotate credentials on schedule.
• Enforce least privilege and segregate duties for data access, indexing, and deployment.
• Monitor for anomalous API usage; trigger automatic rollback on suspicious activity.

Testing Checklist

• Unit tests for vector operations and transforms.
• Integration tests for ingestion, indexing, and retrieval.
• Performance tests for latency and throughput with representative workloads.
• End-to-end tests simulating real-world queries and ranking.
• Security and access control tests for secrets and tooling.

Common Mistakes to Avoid

• Silencing memory/versioning without a single source of truth.
• Allowing unrestricted tool access or embedding secrets in code.
• Overcomplicating the workflow with unnecessary parallelism and architecture drift.
• Skipping validation or performing production changes without approval.

Related implementation resources: AI Use Case for Xero Reports and Business Performance Insights and AI Use Case for Policy Documents and Internal Question Answering.

FAQ

What is the purpose of this AGENTS.md Template?

It defines the operating model for vector database architecture using AI coding agents, enabling single-agent and multi-agent collaboration.

How does multi-agent orchestration work in this template?

It coordinates Planner, Implementer, Researcher, Validator, Tester, Domain-Expert with a central orchestrator and memory store to ensure governance and handoffs.

What are the failure handling and rollback rules?

On failure, the system reverts to last-good index/config and replays steps; the orchestrator triggers human review if needed.

How are tool access and permission managed?

Access is granted via secret managers; limited scopes per tool; secrets never logged; least privilege.

How should human review be integrated?

Human review is triggered for critical failures or design decisions; requires sign-off before production changes.