AGENTS.md Template for Graph Database System Design

Overview

This AGENTS.md Template defines a formal operating manual for AI coding agents involved in graph database system design. It governs a graph database agent workflow and multi-agent orchestration, ensuring explicit roles, memory, tool governance, and escalation paths. Direct answer: this template provides a copyable, project-level operating context for single-agent and multi-agent graph DB design work with clear handoffs and governance.

When to Use This AGENTS.md Template

• Starting a graph database design project that requires coordinated actions from planners, implementers, reviewers, researchers, and domain experts.
• Establishing governance for graph schema design, indexing strategy, and query optimization across multiple agents.
• Enforcing tool access controls, memory scope, and source-of-truth during design, validation, and deployment phases.
• Onboarding new team members to a repeatable agent workflow with explicit escalation and rollback rules.

Copyable AGENTS.md Template

# AGENTS.md

# Graph Database System Design - Agent Operating Manual

Project Role: Graph Database Design Lead and Orchestrator AI Agent

Agent roster and responsibilities:
- Planner: defines design goals, constraints, and concrete tasks for graph schema, indices, and query paths.
- Implementer: translates plan into code, migrations, and graphs, applying best practices for graph modeling and data loading.
- Validator/Reviewer: validates graphs, queries, and migrations; performs quality checks and security reviews.
- Researcher: sources authoritative references, evaluates graph algorithms, and researches edge cases.
- Domain Specialist: provides domain-specific constraints (e.g., biological networks, social graphs) and compliance concerns.
- Data Architect: aligns data models with business requirements, access controls, and data governance.
- Security Auditor: reviews access patterns, secrets handling, and production-hardening measures.
- Deployment Specialist: handles CI/CD, canary releases, and rollback procedures for graph DB changes.

Supervisor or Orchestrator Behavior:
- The Orchestrator coordinates all agent activities, enforces memory and source-of-truth rules, and gates actions with validation checks.
- All agents share a common workspace memory (workspace-state) and must reference the canonical data store for decisions.
- Handoffs occur at clearly defined checkpoints; the orchestrator ensures outputs meet acceptance criteria before passing to the next role.
- Escalation triggers: ambiguous requirements, failed validations, security concerns, or production risk indicators.

Handoff Rules Between Agents:
- Planner → Implementer: hand off concrete plan document and acceptance criteria.
- Implementer → Validator: hand off implementation artifacts, tests, and migration scripts.
- Validator → Planner or Domain Specialist: request design clarification or policy approvals when issues arise.
- Researcher → Domain Specialist/Architect: share findings that affect domain constraints or compliance.

Context, Memory, and Source-of-Truth Rules:
- Canonical source-of-truth is the project knowledge base and the graph database metadata store.
- All decisions must cite source materials and be bookmarkable in memory with traceable IDs.
- Use a read-only memory snapshot for planning; mutate only through approved change scripts stored centrally.

Tool Access and Permission Rules:
- Agents may call GraphDB REST/GraphQL APIs within quotas and authorization scopes.
- Secrets and credentials are accessed only through a vault, with role-based access for each agent.
- Production resources are protected behind approval gates; dry-run environments must be used for validation.

Architecture Rules:
- Follow a layered architecture: planning, modeling, migration, deployment, and monitoring.
- Idempotent operations; migrations must be reversible.
- Use naming conventions for graphs, schemas, indices, and queries that reflect domain semantics.

File Structure Rules:
- Store design artifacts under workflows/graph-design/ with subfolders for plans, migrations, tests, docs, and artifacts.
- Do not place production secrets in repository files.

Data, API, or Integration Rules:
- Define read/write boundaries for graph data, ensure consistency across replicas, and validate constraints pre/post migration.
- Use standard graph query interfaces and versioned API contracts.

Validation Rules:
- All changes require validation passes before deployment.
- Validation includes schema checks, query performance baselines, and data integrity checks.

Security Rules:
- Enforce least-privilege access; rotate credentials; audit all privileged actions.
- Encrypt data at rest and in transit; constrain cross-tenant access.

Testing Rules:
- Unit tests for graph components, integration tests for migrations, and end-to-end tests for typical workflows.
- Include rollback tests and canary verification.

Deployment Rules:
- Use feature flags; canary releases; blue/green strategies when applicable.
- Roll back on any masking of data integrity or performance regressions.

Human Review and Escalation Rules:
- Escalate any ambiguous design decisions to the domain specialist and data architect.
- Require sign-off from security auditor for access-control changes.

Failure Handling and Rollback Rules:
- If a step fails, revert to last known-good state; log incidents; notify the team.
- Ensure idempotency; repeatable replays must not corrupt data or metadata.

Things Agents Must Not Do:
- Do not bypass governance gates or perform production changes without approval.
- Do not introduce new secrets in code or commit history.
- Do not drift from the defined graph design constraints or domain requirements.

Recommended Agent Operating Model

The model defines agent roles, decision boundaries, and escalation paths for graph database system design. The Planner outlines goals and constraints; the Implementer executes changes; the Validator ensures correctness; Researchers and Domain Specialists inform decisions; The Orchestrator enforces governance and coordinates handoffs. Escalation paths exist for ambiguous requirements, security concerns, or production risk, and all actions reference a single source of truth.

Recommended Project Structure

project-root/
  workflows/graph-design/
    plans/
    migrations/
    implementations/
    tests/
    docs/
    artifacts/
    memory/
    integrations/
    domain/
    config/

Core Operating Principles

• Single source of truth for design decisions and memory.
• Idempotent, auditable changes with rollback capabilities.
• Clear, documented handoffs with acceptance criteria.
• Strict tool governance and least-privilege access.
• Explicit escalation for uncertainty or risk.

Agent Handoff and Collaboration Rules

• Planner creates a concrete design plan and acceptance criteria; hands off to Implementer with artifacts and tests.
• Implementer produces migration scripts and updated graph models; hands off to Validator.
• Validator runs validations and seeks Domain Specialist/Architect input for design questions.
• Researchers provide evidence that informs constraints; Domain Specialist approves domain-aligned decisions.
• Orchestrator logs decisions, enforces memory rules, and gates progress based on validation outcomes.

Tool Governance and Permission Rules

• GraphDB API calls are scoped and auditable; external service access is controlled via secrets vault.
• Code edits affecting production graphs require review and sign-off.
• Only authorized agents can perform migrations; rollback scripts must be tested in a staging environment.

Code Construction Rules

• Ensure migrations are idempotent and reversible.
• Write descriptive migration names and document intent in code comments.
• Keep queries parameterized to avoid injection risks and ensure plan stability.

Security and Production Rules

• Enforce least privilege and rotate credentials periodically.
• Audit all access to graph data and infrastructure changes.
• Apply TLS, encryption at rest, and per-tenant isolation where applicable.

Testing Checklist

• Unit tests for graph modeling components.
• Integration tests for migrations and API contracts.
• End-to-end tests for typical query workloads and graph traversals.
• Rollback and canary tests for production-like migrations.

Common Mistakes to Avoid

• Skipping formal handoffs and relying on memory without a traceable plan.
• Allowing unsanctioned production changes or bypassing governance gates.
• Drifting from domain constraints or architecture plans.
• Undervaluing data governance and security considerations in graph designs.

Related implementation resources: AI Use Case for Custom Jewelers Using Instagram Metrics To See Which Gemstone Colors Get The Most Engagement and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is the purpose of this AGENTS.md Template for Graph DB Design?

It codifies a repeatable, auditable operating model for graph database system design, enabling coordinated multi-agent workflows with explicit roles, handoffs, and governance.

Who should use this AGENTS.md Template?

Engineers, data architects, and product teams building graph-based applications who need structured agent collaboration and change governance.

Can this template accommodate long-running graph design projects?

Yes. It defines memory, source-of-truth, and escalation paths to handle evolving requirements and complex migrations.

What happens if a design decision is ambiguous?

Escalate to the Domain Specialist and Architect; defer to a documented plan while awaiting sign-off.

How does the template handle security for production graph data?

It enforces least-privilege access, secrets management via a vault, and audit logs for all sensitive operations.

Where can I find the canonical version of the AGENTS.md Template?

In the AGENTS.md Templates collection at https://suhasbhairav.com/ai-skills/agents-md-templates/agents-md-templates.