AGENTS.md Template: Lambda Architecture Design for AI Coding Agents | Suhas Bhairav

Overview

The AGENTS.md Template for Lambda architecture design documents how AI coding agents operate across the batch, speed, and serving layers. It covers both single-agent execution and multi-agent orchestration, ensuring clear handoffs, shared context, and governed access to tools and data sources.

When to Use This AGENTS.md Template

When implementing a Lambda architecture for data processing with AI coding agents.
When coordinating multiple agents across batch and streaming tasks.
When you need explicit handoff rules, sources of truth, and governance to prevent drift.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Lambda Data Platform Project Owner responsible for governing the Lambda architecture design for AI coding agents.

Agent roster and responsibilities:
- Planner/Orchestrator: coordinates tasks, enforces handoffs, validates contracts, and collects results.
- BatchProcessor: processes historical data in the batch layer, materializes batch views.
- StreamingProcessor: ingests and transforms streaming data in near real-time, updates speed layer views.
- ServingLayer: exposes queryable views, serves low-latency results, and handles serving cache.
- DataQualityAgent: validates contracts, data quality, lineage, and schema drift.
- Researcher/DomainSpecialist: provides domain rules, data sources, and validation logic.
- Reviewer: human-in-the-loop for critical changes or schema changes.
- Tester: executes unit and integration tests for each agent.
- SecurityAgent: enforces secrets management and access controls.

Supervisor or orchestrator behavior:
- LambdaOrchestrator governs all agent interactions, routes tasks, and applies validation gates.
- Agents declare intent, inputs, and outputs via contracts; orchestrator enforces determinism and retries.
- Handoffs occur only via formal signals and validated contracts.

Handoff rules between agents:
- Planner assigns tasks to BatchProcessor and StreamingProcessor as data enters the system.
- DataQualityAgent validates contracts before downstream steps.
- Results are handed to the next agent or ServingLayer with a durable memo.
- Human Reviewer may intervene for critical anomalies or drift.

Context, memory, and source-of-truth rules:
- All contracts, schemas, and lineage live in a central Data Catalog and Schema Registry.
- Agents access a single source of truth; memory is a bounded cache of recent contracts and results.

Tool access and permission rules:
- Agents may call approved APIs and read/write to permitted storage only through the orchestrator.
- Secrets are injected via a secure vault; no secrets are printed or committed in logs.

Architecture rules:
- Enforce Lambda architecture separation: batch, speed, and serving layers with well-defined interfaces.
- Ensure idempotent operations and deterministic outcomes.

File structure rules:
- Code lives under agents/ with subdirectories per agent.
- Configs live under configs/; tests under tests/.

Data, API, or integration rules:
- Data contracts define input/output schemas; interfaces must be versioned and stable.

Validation rules:
- Contracts are validated before progression; tests must pass before deployment.

Security rules:
- Encrypt data at rest and in transit; apply least privilege and rotate secrets.

Testing rules:
- Unit tests per agent; integration tests for end-to-end Lambda flow; CI tests must cover failure handling.

Deployment rules:
- Use feature flags and canary deployments for agent changes.

Human review and escalation rules:
- Route critical issues to domain experts; require manual approval for production changes.

Failure handling and rollback rules:
- Implement exponential backoff retries; on persistent failure, rollback to last stable batch or wave and alert operators.

Things Agents must not do:
- Do not mutate source data directly; do not bypass governance; do not exfiltrate secrets; do not perform unsanctioned deployments.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to support both single-agent execution and multi-agent orchestration in a Lambda workflow.

Recommended Project Structure

project-root/
├── agents/
│   ├── planner/
│   ├── batch_processor/
│   ├── streaming_processor/
│   ├── serving_layer/
│   ├── data_quality/
│   ├── researcher/
│   ├── domain_specialist/
│   ├── reviewer/
│   └── tester/
├── orchestrator/
├── configs/
├── data/
├── infra/
├── tests/
└── docs/

Core Operating Principles

Clear contracts between agents with versioned schemas.
Idempotent, deterministic agent behavior with explicit failure handling.
Single source of truth for data contracts, lineage, and configurations.
Strict tool governance and least-privilege access.
Explicit escalation to human reviewers for critical decisions.

Agent Handoff and Collaboration Rules

Plan→Implementer handoffs follow contract validation gates.
Reviewer approves changes before production exposure.
Tester validates end-to-end flows and rollback paths.
Researcher updates data sources and domain rules; domain specialists validate applicability.
Planner coordinates cross-agent signals to avoid context drift.

Tool Governance and Permission Rules

Only approved commands and APIs may be invoked by agents; all actions are auditable.
Secrets must be accessed from a vault; avoid hard-coding or logging secrets.
Production systems require approvals and feature flags for changes.
External services are accessed via controlled endpoints with rate limits and retries.

Code Construction Rules

Use idempotent functions; avoid side effects outside the orchestrator.
Contracts define input/output; implement adapters for versioned endpoints.
All data transformations must be traceable to source contracts.

Security and Production Rules

Data at rest and in transit must be encrypted; rotate credentials regularly.
Access controlled by least privilege; monitor for anomalous access patterns.
Audit logs retained for incident response and compliance needs.

Testing Checklist

Unit tests for each agent; integration tests for cross-agent flows.
Schema validation tests and drift detection in the Data Catalog.
End-to-end tests of the Lambda data pipeline with simulated data loads.
Deployment tests including canary and rollback checks.

Common Mistakes to Avoid

Skipping contract validation before progression.
Ignoring schema drift or data quality regression.
Bypassing the orchestrator for tool usage or secret access.
Assuming real-time correctness without testing under load.

FAQ

What is this AGENTS.md template for Lambda architecture design?

It provides a complete operating manual and copyable AGENTS.md block tailored for Lambda data processing with AI coding agents, including handoffs, governance, and human review.

Who should use this AGENTS.md Template?

Engineering leaders, platform teams, data engineers, and AI product teams implementing Lambda-based data pipelines with multi-agent orchestration.

How are agent handoffs handled in this template?

Handoffs occur through formal contracts and validation gates orchestrated by the Planner; downstream agents await validated signals before execution.

What governance rules are included for tools and secrets?

Secrets are retrieved from a vault, all tool calls are auditable, and production changes require approvals and feature flags.

How do I customize for my data sources and domain rules?

Update the Researcher and Domain Specialist sections to reflect your sources and rules; ensure data contracts and schemas are versioned in the central catalog.

What are the escalation paths for issues?

Schema drift or data quality failures escalate to the DataQualityAgent and, if unresolved, to a human Reviewer and Domain Expert for approval.

AGENTS.md Template: Lambda Architecture Design for AI coding agents (AGENTS.md template)

Target User

Use Cases