AGENTS.md Template for Ride Sharing System Design

Overview

The AGENTS.md template for ride sharing system design provides a project level operating manual for AI coding agents. It governs an agent workflow that can operate as a single agent or in multi-agent orchestration. It defines roles, handoffs, memory, tool access, and governance to keep rides safe, on time, and compliant.

When to Use This AGENTS.md Template

When starting a new ride sharing platform or feature that relies on AI powered agents
When you need repeatable, audit-friendly agent collaboration across dispatch, routing, pricing, and safety checks
When establishing tool governance and human review processes for production workloads
When you want a copyable reference that teams can paste into AGENTS.md for project context

Copyable AGENTS.md Template

# AGENTS.md

# Ride Sharing Agent Workflow AGENTS.md template

Project role
- Platform Architect for ride sharing services, enabling safe multi-agent orchestration

Agent roster and responsibilities
- DispatchAgent: assigns rides to drivers and coordinates with RoutePlanner
- RoutePlanner: computes optimal routes, considers traffic, ETA, and vehicle constraints
- DemandForecastAgent: predicts ride demand by region and time window
- PricingAgent: computes surge and pricing adjustments within policy bounds
- ComplianceAgent: monitors safety, regulatory, and privacy requirements
- ReviewAgent: performs human review when escalation is needed

Supervisor or orchestrator behavior
- The Orchestrator coordinates agent handoffs, memory state, and data sources
- It enforces tool access rules, validates outputs, and triggers human review on exceptions

Handoff rules between agents
- DispatchAgent hands off routing decisions to RoutePlanner with ride context
- RoutePlanner hands off ETA and route to DispatchAgent for execution
- When uncertainty exceeds threshold, RoutePlanner escalates to ReviewAgent

Context, memory, and source-of-truth rules
- Use a single memory store per ride session; mark sources with identifiers
- All decisions reference a common data catalog and source of truth

Tool access and permission rules
- Only the Dispatcher and RoutePlanner can invoke map and navigation APIs
- Sensitive data access requires approval from the Orchestrator

Architecture rules
- Stateless per-step processing with explicit memory passing
- Central orchestrator logs decisions and outcomes

File structure rules
- Keep agents under agents/ with a clear subfolder for each role
- Place a centralized config and README at project root

Data, API, or integration rules when relevant
- All APIs must be versioned and authenticated
- Cache ride state in a time-bounded store

Validation rules
- Validate outputs against defined success criteria before acting
- Re-validate after every handoff

Security rules
- Do not expose API keys in logs
- Rotate credentials regularly and encrypt sensitive data at rest

Testing rules
- Unit tests for each agent function; integration tests for end-to-end flows
- Include simulated traffic and edge cases

Deployment rules
- Canary deploys with rollback if metrics degrade
- Feature flags govern new behavior

Human review and escalation rules
- Trigger human review for safety concerns, policy violations, or anomalous results
- Maintain an auditable trail of escalations

Failure handling and rollback rules
- If a step fails, revert to prior known good state and notify Orchestrator
- Do not continue with partial state mutations

Things Agents must not do
- Do not bypass safety policies
- Do not access production systems outside approved workflows
- Do not share API keys or credentials in logs or messages

Recommended Agent Operating Model

Roles and responsibilities are defined with clear decision boundaries. The DispatchAgent leads ride allocation, the RoutePlanner combos routes, the DemandForecastAgent and PricingAgent drive demand and price logic within policy, and ComplianceAgent and ReviewAgent provide governance and human oversight. Escalations route to humans when risk is detected. This model supports both single-agent execution and multi-agent handoffs with explicit memory and a shared source of truth.

Recommended Project Structure

ride-sharing/
  agents/
    dispatch/
      main.py
      README.md
    planner/
      main.py
      README.md
    demand/
      main.py
      README.md
    pricing/
      main.py
      README.md
    compliance/
      main.py
      README.md
  workflows/
    ride_dispatch.yaml
  data/
    schemas/
  tools/
    map_api/
  config/
  tests/
  README.md

Core Operating Principles

Single source of truth for ride state and decisions
Deterministic, auditable agent outputs
Explicit memory and clearly scoped lifetimes
Transparent handoffs and escalation paths
Strong tool governance and access controls

Agent Handoff and Collaboration Rules

Planner agents propose next steps, implementers execute actions, reviewers validate results, testers verify behavior, researchers inform with data, and domain specialists provide policy alignment. Handoffs require passing context, memory, and sources, with explicit acceptance criteria at each step.

Tool Governance and Permission Rules

Execution of commands and API calls must follow approved workflows
Files edits require a supervisor review for production changes
Secrets must never be hard coded; use secure vaults
Production systems require feature flags and rollback plans
External services must be auditable and rate-limited

Code Construction Rules

Write pure, testable functions with clear input/output contracts
Avoid side effects outside orchestrated context
Document assumptions and data formats in interfaces
Avoid duplicating logic across agents; share common utilities

Security and Production Rules

Enforce least privilege for all agents
Encrypt data in transit and at rest; monitor for anomalies
Require approval gates before critical production changes

Testing Checklist

Unit tests for each agent function
Integration tests for end-to-end ride flow
Contract tests for API interfaces
Security and vulnerability checks
End-to-end deployment tests with rollback

Common Mistakes to Avoid

Overly broad agent scopes that drift from the workflow
Untracked memory growth or stale sources
Unsafe handoffs without acceptance criteria
Implicit tool access without audit trails

FAQ

What is the purpose of this AGENTS.md Template for Ride Sharing?

This template provides a copyable AGENTS.md block to govern a ride sharing agent workflow and multi-agent orchestration.

Who should use this AGENTS.md Template?

Platform teams, engineers, and product leaders building AI coding agents for dispatch, routing, and safety governance.

How do I customize the agent roster for my platform?

Identify core roles for your ride sharing workflow and adjust the roster while preserving handoff and memory rules.

How are handoffs and escalation handled in this template?

Handoffs pass context and memory to the next agent; escalation routes to a human reviewer when risk is detected.

How is memory and source of truth managed?

Use a centralized memory store per ride session with explicit sources and a data catalog as source of truth.

Target User

Use Cases