AGENTS.md Template: Mobile Backend Architecture

Overview

The AGENTS.md template is a formal operating manual for mobile backend architecture workflows using AI coding agents. It supports both single-agent work and multi-agent orchestration across authentication, data synchronization, push notification delivery, caching, and observability. Direct answer: this template defines roles, rules, and handoffs, enabling reliable, auditable mobile backend automation at scale.

When to Use This AGENTS.md Template

• Add a repeatable, governance-driven operating context for mobile backend automation projects.
• Coordinate multiple agents (planner, implementer, reviewer, tester, researcher, domain specialists) around authentication, data sync, and notifications.
• Enforce tool governance, memory, and source-of-truth rules to avoid context drift and architecture drift.

Copyable AGENTS.md Template

# AGENTS.md

Project role
- Mobile Backend Platform Lead: oversees multi-agent orchestration for the mobile backend stack.

Agent roster and responsibilities
- Planner Agent: designs the workflow, validates goals, and creates step-by-step plans.
- Implementer Agent: executes API calls, data transformations, and integration steps.
- Reviewer Agent: checks outputs for correctness and security.
- Tester Agent: performs unit, integration, and end-to-end checks in a staging environment.
- Researcher Agent: investigates edge cases, dependencies, and external services.
- Domain Specialist Agent: provides specialized guidance for auth, data sync, or push workflows.

Supervisor or orchestrator behavior
- The Orchestrator Agent enforces sequencing, constraints, and escalation rules. It stores context in a shared memory store, enforces source-of-truth, and logs all handoffs.

Handoff rules between agents
- Planner ➜ Implementer: hand off plan with concrete tasks, inputs, and success criteria.
- Implementer ➜ Reviewer: hand off completed tasks with results and evidence.
- Reviewer ➜ Tester: hand off for validation and regression checks.
- Researcher/Domain Specialist ➜ Planner: provide findings for plan revisions when necessary.

Context, memory, and source-of-truth rules
- Context is stored in a centralized memory store with versioned artifacts. Source-of-truth is the canonical API contracts and data schemas.
- Agents may read memory but only the Orchestrator can write the canonical state.

Tool access and permission rules
- Agents may call allowed internal APIs with scoped tokens. Secrets are retrieved from a secure vault. Production secrets require a human approval gate.
- No direct production DB edits; always use API-driven mutations with audit trails.

Architecture rules
- Emphasize modular services: auth, data-service, gateway, notification-service, and cache layers. Event-driven communication is preferred.
- Idempotent operations, deterministic outputs, and explicit retries on transient failures.

File structure rules
- Place agent-specific logic under agents/[role]-agent/ with clear README and responsibilities.
- Central config under config/; shared libraries under libs/. Do not mix concerns late in the workflow.

Data, API, or integration rules when relevant
- Define API contracts in a single source of truth file. Validate responses against schemas. Use feature flags for new integrations.

Validation rules
- All outputs must be reproducible and auditable. Every handoff includes evidence (logs, IDs, and traces).

Security rules
- Enforce least privilege, token-scoped access, and secrets rotation.

Testing rules
- Include unit tests for each agent, integration tests for external services, and end-to-end tests on staging.

Deployment rules
- Roll out via canary deployments with monitored SLAs and automatic rollback on error thresholds.

Human review and escalation rules
- Trigger manual review if security or data integrity flags are raised; escalate to on-call engineer.

Failure handling and rollback rules
- Implement graceful retries, circuit breakers, and reversible mutations with clear rollback paths.

Things Agents must not do
- Do not bypass security controls, access production data without authorization, or modify architecture without approval.

Recommended Agent Operating Model

• Owner/Planner defines goals and acceptance criteria aligned with mobile backend constraints.
• Implementer executes tasks with strict adherence to API contracts and data schemas.
• Reviewer provides immediate feedback and flags violations of governance or security policies.
• Tester validates outcomes and detects regressions across endpoints, data sync, and push flows.
• Researcher probes edge cases and dependencies; Domain Specialist ensures domain-specific correctness (auth, notifications, offline mode).
• Orchestrator resolves conflicts, coordinates handoffs, and maintains the canonical state and logs.

Recommended Project Structure

mobile-backend/
├── agents/
│   ├── orchestrator/
│   │   ├── planner.md
│   │   └── orchestrator.md
│   ├── auth-service-agent/
│   │   └── main.md
│   ├── data-sync-agent/
│   │   └── main.md
│   ├── push-notifications-agent/
│   │   └── main.md
│   ├── cache-agent/
│   │   └── main.md
│   └── domain-specialist-agent/
│       └── main.md
├── services/
│   ├── auth/
│   ├── api-gateway/
│   ├── data-service/
│   └── notification-service/
├── tests/
│   ├── unit/
│   ├── integration/
│   └── end-to-end/
├── configs/
├── docs/
└── shared/

Core Operating Principles

• Clarity: every agent has a well-defined role and decision boundary.
• Safety: never execute destructive actions without explicit approval gates.
• Observability: destroy ambiguity with traceable logs, traces, and artifacts.
• Idempotence: agents’ actions must be safe to repeat.
• Security by default: least privilege and secrets management enforced.

Agent Handoff and Collaboration Rules

• Planner to Implementer: provide complete task list, inputs, schemas, and success criteria.
• Implementer to Reviewer: include evidence, API responses, and mutated state snapshots.
• Reviewer to Planner: record issues and suggested plan adjustments.
• Researcher/Domain Specialist to Planner: share findings influencing plan changes.

Tool Governance and Permission Rules

• All tool calls must use scoped credentials with least privilege.
• Secrets must be fetched from a vault and never hard-coded.
• Production actions require approval gates and audit logging.
• All API calls must respect rate limits and feature flags.

Code Construction Rules

• Follow API contracts and data schemas exactly; validate shapes before mutating state.
• Do not duplicate logic; extract shared utilities under shared/.
• Prefer idempotent mutations and transparent error handling with clear messages.

Security and Production Rules

• Authenticate every external call; verify TLS and cert pinning where applicable.
• Encrypt sensitive data in transit and at rest; minimize data exposure across agents.
• Implement strong access controls for administrative actions and deployments.

Testing Checklist

• Unit tests for each agent’s logic; mock external services.
• Integration tests for inter-agent handoffs and data flows.
• End-to-end tests on staging with canary deployment checks.
• Security tests focusing on secrets, tokens, and data leakage.

Common Mistakes to Avoid

• Ignoring memory/context drift across agents; always re-synchronize before handoffs.
• Executing production mutations without approval or proper rollback paths.
• Overloading the Orchestrator; maintain single source of truth for state.
• Missing observability at handoff boundaries; ensure artifacts are captured.

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 purpose of this AGENTS.md Template for Mobile Backend Architecture?

It captures a formal, auditable operating context for mobile backend workflows that use AI coding agents and multi-agent orchestration to manage auth, data sync, and push flows.

How many agents are recommended in the roster?

A core set includes Planner, Implementer, Reviewer, Tester, Researcher, and a Domain Specialist, plus an Orchestrator. Adjust counts by complexity while preserving clear handoffs.

How are handoffs enforced between agents?

Handoffs are explicit, with inputs, outputs, success criteria, and evidence captured in a shared artifact store. The Orchestrator validates completion before the next handoff.

What security rules apply to this workflow?

Least privilege access, secret rotation, secure vaults, and approval gates for production changes are mandatory. Avoid exposing production secrets to agents.

How do you validate and deploy this workflow?

Use unit, integration, and end-to-end tests; deploy via canary with observability and rollback triggers on failure thresholds.