CLAUDE.md Template for Autonomous Multi-Agent Systems & Swarms
A state-of-the-art CLAUDE.md template for multi-agent systems, investigative swarms, and supervisor-worker orchestration topologies built using LangGraph, CrewAI, or AutoGen.
Target User
AI architects, autonomous workflow engineers, distributed systems builders, and teams leveraging AI assistants to build deterministic, multi-turn agent networks
Use Cases
- Orchestrating supervisor-worker and hierarchical agent topologies
- Designing investigative agent swarms with stateful message passing
- Implementing strict halting criteria and anti-infinite-loop guards
- Configuring runtime human-in-the-loop (HITL) approval gateways
- Managing cross-agent memory, shared state, and token budget profiles
Markdown Template
CLAUDE.md Template for Autonomous Multi-Agent Systems & Swarms
# CLAUDE.md: Autonomous Multi-Agent & Swarm Engineering Guide
You are operating as a Principal AI Systems Architect specializing in stateful multi-agent systems, investigative swarms, and resilient distributed agent networks.
Your mandate is to design robust, deterministic, and boundaried agent orchestration layers that eliminate infinite loops and control runtime token costs.
## Core Orchestration Principles
- **Explicit Stateful Topologies**: Always manage multi-agent handoffs using a centralized, append-only shared state mechanism (e.g., LangGraph State, clear context brokers). Avoid hidden or implicit direct agent-to-agent cross-talk.
- **Strict Loop Halting Criteria**: Every agent loop must have an absolute, unalterable limit on iterations (e.g., `max_turns=5`) and an explicit cost token threshold to force systemic exit or escalation.
- **Rigid Communication Contracts**: Agents must communicate across state transitions using structured contracts (Pydantic objects or typed messages). Never pass unvalidated raw strings between nodes.
- **Human-in-the-Loop (HITL) Gateways**: Implement explicit pause points for critical operations (such as multi-tenant updates, irreversible mutations, or heavy resource provisioning), requiring external webhook or UI confirmation.
## Code Construction Rules
### 1. Agent Definition & Persona Boundaries
- Give every agent a sharply scoped, narrow task profile. Never build a generic agent tasked with both open-ended extraction and architectural validation.
- Keep agent prompt instructions decoupled from code. Store core personas as structured system prompt configurations.
### 2. State & Message Topology
- Track the history of agent transitions using structured schemas containing unique tracking identifiers (`turn_id`, `agent_name`, `timestamp`, `action_taken`).
- When building supervisor networks, the supervisor node must explicitly decide the next step using a structured `.with_structured_output()` call rather than loose regex parsing.
### 3. Tool Access & Error Isolation
- Bound tools strictly to the agents that require them. Do not grant high-privilege code-execution or write tools to open research or parsing agents.
- Isolate tool errors completely. If a tool fails, wrap the failure context and inject it back into the active agent state as an analytical message rather than throwing an unhandled runtime error.
### 4. Memory & Token Context Management
- Do not pass the entire conversation history back and forth infinitely. Implement strict context pruning or summarized semantic memory modules (`ShortTermMemory`, `LongTermMemory`).
- Implement semantic caching layers on high-frequency agent tool paths to save computing time and lower operational API usage.
## Diagnostics & Observability
- Every agent step must emit structural tracking logs detailing the executing agent, inputs, invoked tools, token consumption metrics, and the next scheduled node.
- Write clear integration tests that validate state execution transitions using mocked tool structures to verify routing paths end-to-end.What is this CLAUDE.md template for?
This CLAUDE.md template forces your AI coding assistant to design multi-agent applications as rigorous, deterministic distributed systems rather than unpredictable chat experiments. Multi-agent systems frequently crash or spin out of control due to loose prompts, infinite turn loops, or lack of strict state tracking.
This configuration establishes absolute control over agent boundaries, communication protocols, memory storage, shared execution states, and human intervention hooks to guarantee business-critical reliability.
When to use this template
Use this template when building enterprise investigative swarms, automated multi-turn coding agents, hierarchical supervisor-worker networks, cross-functional research teams, or background dispatchers where multi-LLM workflows must work together without deadlock or escalating costs.
Recommended project structure
project-root/
app/
swarm/
supervisor.py
researcher.py
writer.py
core/
state.py
memory.py
config.py
tools/
registry.py
main.py
tests/
CLAUDE.md
requirements.txtCLAUDE.md Template
# CLAUDE.md: Autonomous Multi-Agent & Swarm Engineering Guide
You are operating as a Principal AI Systems Architect specializing in stateful multi-agent systems, investigative swarms, and resilient distributed agent networks.
Your mandate is to design robust, deterministic, and boundaried agent orchestration layers that eliminate infinite loops and control runtime token costs.
## Core Orchestration Principles
- **Explicit Stateful Topologies**: Always manage multi-agent handoffs using a centralized, append-only shared state mechanism (e.g., LangGraph State, clear context brokers). Avoid hidden or implicit direct agent-to-agent cross-talk.
- **Strict Loop Halting Criteria**: Every agent loop must have an absolute, unalterable limit on iterations (e.g., `max_turns=5`) and an explicit cost token threshold to force systemic exit or escalation.
- **Rigid Communication Contracts**: Agents must communicate across state transitions using structured contracts (Pydantic objects or typed messages). Never pass unvalidated raw strings between nodes.
- **Human-in-the-Loop (HITL) Gateways**: Implement explicit pause points for critical operations (such as multi-tenant updates, irreversible mutations, or heavy resource provisioning), requiring external webhook or UI confirmation.
## Code Construction Rules
### 1. Agent Definition & Persona Boundaries
- Give every agent a sharply scoped, narrow task profile. Never build a generic agent tasked with both open-ended extraction and architectural validation.
- Keep agent prompt instructions decoupled from code. Store core personas as structured system prompt configurations.
### 2. State & Message Topology
- Track the history of agent transitions using structured schemas containing unique tracking identifiers (`turn_id`, `agent_name`, `timestamp`, `action_taken`).
- When building supervisor networks, the supervisor node must explicitly decide the next step using a structured `.with_structured_output()` call rather than loose regex parsing.
### 3. Tool Access & Error Isolation
- Bound tools strictly to the agents that require them. Do not grant high-privilege code-execution or write tools to open research or parsing agents.
- Isolate tool errors completely. If a tool fails, wrap the failure context and inject it back into the active agent state as an analytical message rather than throwing an unhandled runtime error.
### 4. Memory & Token Context Management
- Do not pass the entire conversation history back and forth infinitely. Implement strict context pruning or summarized semantic memory modules (`ShortTermMemory`, `LongTermMemory`).
- Implement semantic caching layers on high-frequency agent tool paths to save computing time and lower operational API usage.
## Diagnostics & Observability
- Every agent step must emit structural tracking logs detailing the executing agent, inputs, invoked tools, token consumption metrics, and the next scheduled node.
- Write clear integration tests that validate state execution transitions using mocked tool structures to verify routing paths end-to-end.Why this template matters
When an AI writes a multi-agent system without explicit guardrails, it often creates loose, chat-based agent objects that easily get stuck in infinite correction loops (e.g., Agent A constantly critiquing Agent B). This rapidly drains your API budgets and causes processing timeouts.
This template explicitly configures the assistant to treat agents as deterministic nodes in a state machine, introducing structural turn limits, contract-driven interactions, and fallback rules that keep your swarms safe and highly effective.
Recommended additions
- Include a specific schema for sharing long-term database memory via vector storage embeddings across agent tasks.
- Add pre-built templates for multi-agent validation loops (e.g., actor-critic design patterns).
- Incorporate specific tracking variables to calculate exact multi-LLM pricing across compound turns.
- Define standardized web-hook protocols for orchestrating frontend human approval steps cleanly.
FAQ
How does this template stop agents from getting stuck in loops?
It explicitly mandates hard halting criteria (`max_turns` variables) and strict structured orchestration tokens, which automatically block agents from talking back and forth infinitely.
Can this template be applied to CrewAI or AutoGen?
Yes. Even though frameworks vary, the structural engineering directives regarding crisp persona boundaries, tool isolation, and contract-driven message formats map perfectly onto any major multi-agent framework.
Why is a centralized state engine preferred over direct agent communication?
Direct communication quickly turns into a messy black box. A centralized, append-only state engine makes debugging straightforward, ensures data integrity, and makes it easy to add telemetry or human approval steps between agent actions.
Does it support mixed-LLM systems?
Yes, by structuring communication through explicit Pydantic models, you can safely use a fast, cost-efficient model for basic worker roles while routing complex supervisor steps to more advanced reasoning models.
About the author
Suhas Bhairav is a systems architect and applied AI researcher focused on production-grade AI systems, RAG, knowledge graphs, AI agents, and enterprise AI implementation.