Lesson 16: Q&A (Part 1) Multi-Agent Architecture & Routing

⏱ Est. reading time: 8 min Updated on 5/7/2026

Scenario: This issue focuses on answering the most common task scheduling, concurrency conflicts, and performance bottleneck questions developers face when attempting to upgrade from a "lone wolf" single-agent mode to a multi-agent architecture.

Q1: Routing Mechanism

Q: How does the Router Agent (i.e., Team Lead) decide which Sub-Agent to distribute a task to? If dispatched incorrectly, how do we rollback?

A: The Team Lead relies on the Role Description you defined in TeamCreate or CLAUDE.md during project initialization.

Upon receiving a task, the Team Lead uses semantic matching for responsibilities. For example, if ui-dev's description is "Focuses on React components and CSS", and the new task is "Fix calculator overflow Bug", the Lead will lean towards assigning it to logic-dev.

If dispatched incorrectly (e.g., frontend Agent modifying the backend library): You don't need to kill the entire process. Since each Agent has an independent Inbox, the Team Lead can call SendMessage at any time to send a forced interrupt command: "Stop current operation, this task has been handed over to backend-dev. Clear your modifications (git checkout) and exit."

Q2: [Mermaid Swimlane] File Conflict Resolution

Q: When two parallel Sub-Agents attempt to modify the same file (e.g., Calculator.ts) simultaneously, how does the underlying system handle it?

A: Claude Code Teams does not have magical built-in real-time collaborative editing (OT/CRDT) mechanisms; it relies entirely on OS-level file locks and Git conflict merging. The actual underlying processing flow is as follows:

sequenceDiagram
    participant Lead as Team Lead
    participant A1 as Agent 1 (UI)
    participant A2 as Agent 2 (Logic)
    participant FS as Local File System
    
    Lead->>A1: Task: Modify Calculator.ts Interface
    Lead->>A2: Task: Modify Calculator.ts Algorithm
    
    A1->>FS: Read Calculator.ts (Version v1)
    A2->>FS: Read Calculator.ts (Version v1)
    
    A1->>FS: Write interface modifications (Success, becomes v2)
    A2->>FS: Attempt to write algorithm modifications...
    
    rect rgb(254, 252, 232)
        Note over A2, FS: Detected file was externally modified after reading!
        FS-->>A2: Throw FileModifiedError blocking write
    end
    
    A2->>A2: Re-read latest file (Version v2)
    A2->>FS: Re-apply algorithm modifications based on v2 (Success, becomes v3)

Pitfall Guide: Although the underlying layer will automatically retry (as shown above), highly concurrent modifications to the same file can easily cause logical overwriting. Best practice: Always perform file isolation assignments during the routing phase, or forcefully serialize them using TaskUpdate(blockedBy).

Q3: Parallel Bottlenecks

Q: Why did the speed of project refactoring become slower than serial (single Agent) after I enabled parallel Teams mode?

A: This is usually because you hit the LLM's Token concurrency limits or tool read/write lock contentions.

  1. API Concurrency Rate Limiting (429 Error): If 4 Agents initiate requests simultaneously, it's very easy to trigger Anthropic/Gemini's RPM (Requests Per Minute) or TPM (Tokens Per Minute) caps, causing all Agents to fall into dozens of seconds of Exponential Backoff waiting.
  2. Lock Contention: If multiple Agents frequently execute git status, npm install, or write to different log files simultaneously, underlying system lock contention causes massive I/O waits.

Solutions: Don't parallelize just for the sake of it. Keep the number of active Sub-Agents within 2-3, and try to assign CPU-intensive (e.g., static code analysis) or network-independent tasks to parallelize.

Q4: Role-based Architecture

Q: Can I rigidly specify that one Agent only writes frontend, another only writes backend, and a third exclusively writes tests? How should this be configured?

A: Yes, and this is the most efficient architecture. The key lies in combining Prompt Injection and Workspace Mounting:

  1. During TeamCreate, inject a prompt for frontend-dev: "You can only read and modify directories src/components and src/pages. If the task involves the backend, return it immediately."
  2. Inject rules for tester: "You can only create files under the tests/ directory and only execute npm test; you are forbidden from modifying core business code under src/."

Q5: Optimizing CLAUDE.md Token Usage

Q: The system rules in CLAUDE.md are too long, causing each Sub-Agent to consume a massive amount of Tokens per conversation. How can we fold and optimize instructions?

A: In Teams mode, a lengthy CLAUDE.md inflates token costs significantly because every independent Agent process carries it in every API request.

Optimization Strategy: Use a Progressive Rule Tree instead of a flat document. Do not hardcode all rules into CLAUDE.md. Slim it down to just two sentences:

"1. This project uses the React+Node stack. 2. Based on your role, please first read .agent/rules/frontend.md or .agent/rules/backend.md to get detailed rules."

This way, only the frontend Agent will read and load the detailed frontend rule set, greatly reducing the initial Token overhead.

Q6: Process Lifecycle

Q: If I forcefully stop the master Agent via Ctrl+C, what happens to the Sub-Agents still running in the background? Will it create orphan processes?

A: By default, it will create orphan processes.

Because each Sub-Agent in Claude Code is spawned within independent Tmux Sessions. When you kill the master Agent (Team Lead), it might not have time to send termination signals to all tmux sessions.

Cleanup Plan: Execute tmux list-sessions to view residual Agents. Then run the team destruction tool TeamDelete, or simply perform a brutal cleanup: tmux kill-server (Note this will kill all tmux sessions on your computer).

Q7: Context Sharing

Q: In Teams mode, can different Agents share memory caches or ChromaDB's historical vector context?

A: Isolated by default, but bridgeable via plugins.

At the memory level, Agents are completely isolated independent Node.js processes. ui-dev doesn't know what prompt logic-dev just sent to the LLM.

However, if a persistent memory plugin like claude-mem is integrated into the project, all Agents, upon triggering the PostToolUse hook, will write operational summaries into the same local SQLite/ChromaDB database. When the Team Lead needs to summarize progress, it can view the collective memory of all parallel Agents via search(), essentially forming a database-based "Blackboard Pattern".