AGENTS.md template for GraphQL Production Architecture — AGENTS.md Template

Overview

This AGENTS.md template defines the operating context for a GraphQL production architecture using AI coding agents. It governs both single-agent workflows and multi-agent orchestration, including schema design, data sources, resolver strategies, and governance. Direct answer: it codifies roles, rules, and handoffs to run GraphQL services with AI agents.

When to Use This AGENTS.md Template

• When building a GraphQL production architecture with multiple services, data sources, and adapters (REST, databases, caches) behind a gateway.
• When you need explicit agent roles, handoff points, and an auditable operating manual for production changes.
• When governance, security, and access control must be codified in a repeatable pattern.
• When introducing multi-agent orchestration (planner, implementer, reviewer, tester, researcher, domain specialist) to manage complex GraphQL workflows.
• When enforcing tool access, memory rules, and source-of-truth for schema and data sources.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: GraphQL Production Architect

Agent roster and responsibilities:
- Planner: defines the GraphQL schema strategy, federation vs stitching, and plan for data sources; coordinates handoffs.
- Implementer: builds resolvers, data-source adapters, and schema enhancements; implements performance and security patterns.
- Reviewer: enforces GraphQL schema quality, naming, and policy conformance; performs static checks.
- Tester: validates queries, mutations, and performance budgets; runs integration tests against data sources.
- Researcher: investigates data sources, access patterns, and security controls; documents edge cases.
- Domain Specialist: provides domain-specific constraints and validation rules for business logic.

Supervisor or orchestrator behavior:
- The GraphQL Orchestrator issues tasks, tracks dependencies, and coordinates handoffs between agents.
- It maintains a shared memory/context store with a single source of truth for schema version, data sources, and permission state.
- It validates outputs, routes issues to the appropriate agent, and gates production changes through approvals.

Handoff rules between agents:
- Planner → Implementer: handoff upon schema plan approval and data source mapping completion.
- Implementer → Reviewer: handoff once resolvers and data sources compile and pass local tests.
- Reviewer → Implementer: if issues are found, loop back with concrete fixes.
- Implementer → Tester: after integration build, trigger tests; Tester returns failures for remediation.
- Researcher/Domain Specialist → Planner: escalate domain or data source issues that require planning updates.

Context, memory, and source-of-truth rules:
- Context is stored in a centralized memory object with schema version, data sources, and access controls.
- All agent decisions must reference the canonical schema and data-source definitions as the source of truth.
- Do not rely on ephemeral memory for long-term decisions; persist results to the source of truth after validation.

Tool access and permission rules:
- Agents access data sources through read-only or restricted endpoints; write access is limited to Implementer under approval.
- Secrets are stored in a secrets vault and never embedded in code or messages.

Architecture rules:
- Prefer GraphQL federation for distributed data sources; avoid blind schema merging without validation.
- Enforce schema directives for authentication and authorization; expose only necessary fields in production.
- All changes require versioned schemas and validation checks before deployment.

File structure rules:
- Use a clear, mirrorable structure:
  - graphql-production/
    - orchestrator/
      - planner/
      - gatekeeper/
    - services/
      - gateway/
      - resolvers/
      - data_sources/
    - infra/
      - deployments/
      - monitoring/
    - tests/
    - docs/
    - policies/

Data, API, or integration rules when relevant:
- All data source connections must be defined in resolvers with safe fallbacks and timeouts.
- API keys must be present only in a secrets vault; never commit to repo.
- Rate limits and caching policies must be explicit in the data layer.

Validation rules:
- Validate GraphQL schema against a shared schema registry.
- Run unit tests for each resolver, integration tests for data sources, and end-to-end tests for common queries.

Security rules:
- Enforce role-based access and field-level permissions for production endpoints.
- Gate deploys behind a security review and an automated security scanning step.

Testing rules:
- Include unit tests for resolvers, integration tests for data sources, and performance tests within CI.

Deployment rules:
- Deploy to a staging environment first; require approvals before production deployment.
- Maintain a rollback plan and versioned releases with clear change logs.

Human review and escalation rules:
- Escalate failed validations to the Planner or Domain Specialist as needed.
- All human reviews must be documented with decisions and go/no-go outcomes.

Failure handling and rollback rules:
- If a deployment fails, revert to the previous stable schema and data source configuration.
- Log all rollback actions and notify stakeholders.

Things Agents must not do:
- Do not modify production data directly without approval.
- Do not bypass the orchestrator or gates.
- Do not rely on stale memory for decisions.
- Do not introduce new data sources without validation and security checks.

Recommended Agent Operating Model

Roles and responsibilities are aligned to GraphQL production needs. The Planner defines schema strategy and data source plan; the Implementer builds resolvers and adapters; the Reviewer enforces policy and quality; the Tester validates behavior and performance; the Researcher uncovers data access pitfalls; the Domain Specialist enforces domain-driven constraints. Decision boundaries are explicit: planners decide architecture and data source mapping; implementers implement against approved designs; reviews ensure policy and safety; escalations route to Domain Specialists or the Planner when business or data constraints are encountered. Escalation paths are documented in the AGENTS.md template and enforced by the Orchestrator.

Recommended Project Structure

graphql-production-arch/
  orchestrator/
    planner/
    gatekeeper/
  services/
    gateway/
    resolvers/
    data_sources/
  infra/
    deployments/
    monitoring/
  tests/
  docs/
  policies/

Core Operating Principles

• Single source of truth for GraphQL schema and data sources.
• Explicit, testable handoffs between agents with deterministic outcomes.
• Codified constraints for security, access, and compliance.
• Continuous validation and auditable deployment processes.
• Clear escalation paths for domain, data source, or policy issues.

Agent Handoff and Collaboration Rules

• Planner to Implementer: hand off when schema plan, resolver strategies, and data source mappings are approved.
• Implementer to Reviewer: hand off when resolvers compile, tests pass, and schema adheres to policies.
• Reviewer to Implementer: provide remediation guidance if issues are found.
• Researcher to Planner: escalate unverified data sources or domain constraints.
• Domain Specialist to Planner: update domain constraints based on evolving business rules.

Tool Governance and Permission Rules

• Query execution, mutations, and data source access are restricted by role; production actions require orchestrator approval.
• Secrets must be retrieved from a vault; never embedded in code or prompts.
• All API calls, schema changes, and deployments are auditable with logs and versioning.
• Surge guardrails exist for long-running or destructive queries in production.

Code Construction Rules

• Define GraphQL types, inputs, and enums with consistent naming and documentation.
• Resolvers must reference the canonical data sources and respect security rules.
• All changes are versioned, validated, and tested before deployment.
• Do not hard-code credentials or secrets; use environment-based configs and vaults.

Security and Production Rules

• Enforce authentication and authorization at field level where applicable.
• Implement rate limiting and caching with safe cache invalidation strategies.
• Audit all production changes and maintain rollback pathways.

Testing Checklist

• Unit tests for each resolver and data source adapter.
• Integration tests covering GraphQL schema, data sources, and security constraints.
• End-to-end tests for typical client workloads and error paths.
• Performance tests to ensure latency budgets are met under load.
• Deployment validations including staging smoke tests.

Common Mistakes to Avoid

• Skipping schema validation or relying on ad-hoc migrations.
• Allowing unsanctioned data source changes without vetting by the Planner.
• Bypassing the orchestrator or weaponizing memory outside the source of truth.
• Undervaluing security constraints in early design.
• Neglecting test coverage for authentication and authorization rules.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is the role of AGENTS.md in GraphQL production architecture?

It defines the operating manual for GraphQL production workflows, detailing agent roles, handoffs, and governance.

How are agent handoffs between planner, implementer, and reviewer handled?

Handoffs occur at clearly defined milestones: when the plan is approved, when resolvers compile, and when tests pass; the orchestrator enforces the sequence and records outcomes.

How are memory and source-of-truth maintained?

Context is stored in a centralized memory object with a canonical schema and data source definitions serving as the source of truth; long-term decisions reference this source rather than ephemeral memory.

What are the deployment and rollback rules?

Deployments require staging validation and approvals; failures trigger a rollback to the previous stable schema and data source configuration with full logging.

What do agents must not do?

Do not modify production data without approval, bypass governance gates, or rely on stale memory for decision-making.