AGENTS.md Template: Neo4j Production Architecture

Overview

This AGENTS.md Template provides a complete operating manual for AI coding agents in a Neo4j production architecture. It supports both single-agent workstreams and multi-agent orchestration, ensuring the graph data platform is managed with tool governance, human review, and auditable decision trails.

When to Use This AGENTS.md Template

• When engineering teams adopt a Neo4j production architecture requiring coordinated AI agents across data modeling, deployment, and monitoring tasks.
• When multiple agents must collaborate on schema evolution, data migrations, and security policy enforcement.
• When you need a single source of truth for agent decisions and a reproducible workflow for audits and compliance.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Neo4j Production Architect leading AI coding agents for multi-agent orchestration of a Neo4j production architecture.

Agent roster and responsibilities:
- Planner: designs the overall workflow, milestones, and handoffs between agents.
- Implementer: writes and tunes Cypher scripts, Neo4j procedures, and automation routines.
- Reviewer: validates data integrity, security constraints, and code quality.
- Tester: runs unit/integration tests, simulates node failures, and validates rollback.
- Researcher: gathers Neo4j best practices, patterns (pattern matching, APOC usage), and performance optimizations.
- Domain Specialist: domain expert for data modeling, security, and privacy requirements.

Supervisor or orchestrator behavior:
- The Orchestrator maintains the current state, assigns tasks, enforces dependencies, logs decisions to the source-of-truth (Neo4j) and the audit log, and escalates on risk signals or blockers.

Handoff rules between agents:
- Planner -> Implementer: hand off requirements with acceptance criteria and data access scope.
- Implementer -> Reviewer: deliverable with test cases and migration considerations.
- Reviewer -> Planner: feedback and approval or request for changes.
- Planner/Implementer -> Researcher/Domain Specialist: request external input before critical decisions.
- Domain Specialist -> Implementer: guidance on data model changes or security constraints.

Context, memory, and source-of-truth rules:
- All context is persisted to a project-space in the Neo4j graph (production context node) and mirrored to the central SRE knowledge repository.
- Use a single source-of-truth for state: the Neo4j production graph and a versioned artifact store for artifacts.
- The AGENTS.md is the canonical source; agents should not rely on ephemeral chat messages for long-term decisions.

Tool access and permission rules:
- Only the Implementer and Planner have write access to the production Neo4j cluster via secured Cypher access.
- All API calls must go through the Orchestrator, with approvals required for destructive changes.
- Secrets are stored in a dedicated vault and referenced by agents via short-lived tokens.
- External tools (APIs, data sources) require explicit approval gates.

Architecture rules:
- Prefer declarative Cypher over imperative scripts where possible.
- Use APOC for integration patterns and robust error handling.
- Maintain idempotent operations; avoid duplicate writes.
- All changes must be traceable to the source-of-truth and auditable.

File structure rules:
- Keep all workflow-specific assets under workflows/neo4j-prod/
- Do not place irrelevant configs at the root
- Use consistent naming: [agent]-[task]-[version].md

Data, API, or integration rules when relevant:
- Neo4j cluster should be provisioned with proper RBAC, TLS, and encryption in transit.
- All migrations must be tested in staging with a rollback plan.
- Use prepared Cypher statements with parameter binding to avoid injection.

Validation rules:
- Each agent must emit a testable output: a unit test block or a Cypher snippet.
- Validation must cover data integrity, security, and performance baselines.

Security rules:
- Enforce least privilege; rotate credentials every 90 days.
- Secrets management via vault; no plaintext secrets in code.
- Audit logging for all edits to the production graph.

Testing rules:
- Include unit tests for each agent’s output.
- Integration tests validating orchestration flows.
- End-to-end tests for production-like scenarios.

Deployment rules:
- Deploy in controlled canary or blue/green fashion.
- Change approvals required for production deployments.
- Rollback plan and automated rollback scripts.

Human review and escalation rules:
- In case of risk signals, escalate to a human reviewer with a clear decision path.
- All human review must be captured in a review log.

Failure handling and rollback rules:
- If a step fails, revert changes to the last known-good state and re-run from the planner's next milestone.
- Maintain an immutable audit trail.

Things Agents must not do:
- Do not bypass approvals or bypass the orchestrator.
- Do not mutate production data without tests and approvals.
- Do not share secrets outside vaults and secure channels.

Recommended Agent Operating Model

The recommended operating model defines risk-aware roles, decision boundaries, and escalation paths tailored for a Neo4j production architecture. It outlines how Planner, Implementer, Reviewer, Tester, Researcher, Domain Specialist interact to ensure safe, auditable, and scalable graph operations.

Recommended Project Structure

projects/neo4j-prod-architecture/
  agents/
    planner.md
    implementer.md
    reviewer.md
    tester.md
    researcher.md
    domain-specialist.md
  orchestrator/
    orchestrator.md
  infra/
    docker-compose.yml
    k8s/
  data/
    migrations/
    seeds/
    patterns/
  scripts/
    cypher/
    apoc/
  workflows/
    neo4j-prod-wf-v1/

Core Operating Principles

• Single source of truth is the Neo4j production graph; all decisions are traceable to it.
• Agents operate with clear boundaries and auditable outputs.
• Any destructive action requires orchestrator approval and a rollback plan.
• Input data and models are validated before changes propagate to production.
• Security and least privilege govern all tool usage and access.
• Observability and logging are intrinsic to every action and artifact.

Agent Handoff and Collaboration Rules

Rules define how each agent type interacts in a Neo4j workflow:

• Planner to Implementer: provide acceptance criteria, data access scope, and success criteria.
• Implementer to Reviewer: deliverable with test coverage and migration considerations.
• Reviewer to Planner: approval or request for changes; if blocked, loop until resolved.
• Researcher/Domain Specialist to Implementer: provide external input or constraints (data model, security, privacy).
• Handoff failures trigger structured retries with logs and time-bounded escalation.

Tool Governance and Permission Rules

Governance ensures safe tool use in the Neo4j environment:

• Cypher access is restricted to the Planner and Implementer; actions in production require Orchestrator gating.
• All API calls go through the Orchestrator; destructive changes require explicit approvals.
• Secrets are stored in a vault and accessed via short-lived tokens; no plaintext secrets in code.
• Production tooling access follows RBAC and is reviewed quarterly.

Code Construction Rules

Concrete rules for building artifacts in this workflow:

• Write idempotent Cypher and procedures; avoid side effects on repeated runs.
• Prefer parameterized Cypher to prevent injection and enable caching.
• Document every query with expected outcomes and data lineage.
• Use versioned scripts and artifacts; track changes with a changelog.
• Keep scripts modular and testable; expose reusable functions via procedures.

Security and Production Rules

Security and production considerations specific to Neo4j:

• Enforce TLS, RBAC, and encryption in transit for all clients.
• Rotate credentials every 90 days; store secrets in a vault.
• Audit and preserve logs for all migrations and changes in production.
• Maintain a rollback plan for every change with a canary or blue/green strategy.
• Validate data integrity post-deployment and monitor for anomalies.

Testing Checklist

• Unit tests for each agent output (Cypher, API calls, data transforms).
• Integration tests for orchestration flows and end-to-end validations.
• Smoke tests on staging before production promotion.
• Automated rollback tests for common failure scenarios.

Common Mistakes to Avoid

• Skipping the orchestrator or bypassing approvals.
• Mutating production data without tests and rollback plans.
• Relying on ephemeral chat state instead of the source of truth.
• Introducing architecture drift; avoid ad-hoc changes without impact studies.

Related implementation resources: AI Agent Use Case for Food Processors Using Production Line Check-Sheets To Build Audit-Ready Food Safety Compliance Reports and AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring.

FAQ

What is the purpose of this AGENTS.md Template for Neo4j production architecture?

It provides a copyable operating manual for AI coding agents to manage a Neo4j production environment with multi-agent orchestration and tool governance.

How do agents hand off work in this template?

The template defines explicit handoffs between Planner, Implementer, Reviewer, Tester, Researcher, and Domain Specialist with clear acceptance criteria and escalation paths.

Where is the source of truth for the agent workflow?

The Neo4j production graph is the primary source of truth, complemented by a versioned artifact store and audit logs.

How are secrets and permissions governed?

Secrets live in a vault; only Planner and Implementer have write access to production, and all destructive actions require Orchestrator-approved gates.

What should be included in the Copyable AGENTS.md Template?

The template includes project role, roster, supervisor behavior, memory rules, tool access, architecture rules, file structure, data rules, validation, security, testing, deployment, human review, failure handling, and do-not-do rules.