Lesson 18: Q&A (Part 3) State Sync & Macroscopic Topology

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

Scenario: This is the final issue of the practical tutorial. Written specifically for senior architects who need to orchestrate multi-language grand migrations and ultra-large-scale repository refactoring in real business scenarios.

Q15: [Mermaid State Machine] Agent Message Passing

Q: How do two independently running child Agents achieve "handshake communication" and state synchronization? Are they aware of what each other is doing?

A: In Claude Code Teams, peer Sub-Agents are mutually invisible by default. They must route through the file system or the Team Lead.

stateDiagram-v2
    state "Team Lead (Router)" as TL
    state "Agent: UI-Dev" as UI
    state "Agent: API-Dev" as API
    state "File: api_schema.json" as FS
    
    UI --> FS: 1. Attempt to read interface spec (Not found, Blocked)
    UI --> TL: 2. SendMessage("I'm stuck, need backend to define Schema first")
    
    TL --> API: 3. TaskUpdate(Generate schema, highest priority)
    API --> FS: 4. Write("api_schema.json")
    API --> TL: 5. SendMessage("Schema is completed")
    
    TL --> UI: 6. SendMessage("Backend spec is generated, you can continue reading")
    UI --> FS: 7. Read("api_schema.json"), resume development state

This asynchronous mechanism, similar to "semaphore publish/subscribe," ensures that parallel Agents don't turn into chaos on interdependent tasks.

Q16: Cross-language Workflow

Q: When conducting cross-language grand refactoring (e.g., migrating a Python backend to TypeScript), how do you design the most efficient dual-Agent collaborative pipeline?

A: Never let the same Agent read Python while writing TypeScript; this easily leads to cognitive confusion (hallucinations).

Dual-Agent Pipeline Design:

  1. Reader-Agent (Python Expert): Has read-only access to the original project directory. Its task is to read Python code, decompile pure business logic and test cases, and then write a standardized Markdown Spec (requirements specification).
  2. Writer-Agent (TS Expert): Has read access to the Spec and write access to the new project directory. It doesn't look at Python code at all, purely refactoring the TypeScript version based on the generated Spec.

This not only reduces cognitive load but naturally forms a highly decoupled, microservice-like AI production line.

Q17: Enforcing Git Workflow

Q: Why do my Agents often forget to submit a Git Commit after successfully fixing a Bug, and exit directly? How do I enforce this workflow?

A: LLMs have a natural tendency to "rush to hand in their homework." To enforce workflows, you must design insurmountable guardrails.

Add a Mandatory Closure Protocol in CLAUDE.md: "Before you mark a task as completed via TaskUpdate, you must execute git status. If there are uncommitted modifications, you must call Bash(git commit -am 'xxx'). If I find your task status is completed but the workspace is still dirty, the task will be deemed a complete failure." By using an extremely strict tone and clear causal relationships, such oversights can be drastically reduced.

Q18: MCP Distribution Topology

Q: When the system needs to connect to external services (like Jira or a remote Database) to fetch data, is it better for the master Agent to query uniformly and distribute, or let each child Agent connect to MCP individually?

A: We recommend adopting a "Fat Router, Thin Endpoints" pattern.

Allowing each child Agent to have MCP connections significantly elevates the risk of permission leaks and increases context noise. The optimal topology is: The Team Lead connects to the JIRA MCP, pulls macroscopic requirements, breaks them down into fine-grained Markdown task tickets written to disk, and then assigns them to Sub-Agents. If a Sub-Agent needs to query the database, it should request the Team Lead via SendMessage to query and return the results on its behalf.

Q19: Log Aggregation & Reporting

Q: After parallel tasks end, how do you extract the heterogeneous runtime logs of all Sub-Agents and generate a human-readable complete project daily report?

A: By mounting specific archival hooks.

Configure a SessionEnd hook: Whenever a Sub-Agent's tmux process ends, the hook script serializes the Agent's execution steps and results, appending them to .agent_reports/daily_log.md in the project root. At the end of the day (or when the overall pipeline finishes), launch a dedicated Reporter Agent with a single task: "Read the summary file, output the execution outline, core technical debt discovered, and tomorrow's to-dos, and publish it in the project's PR."

Q20: [Mermaid Architecture] Map-Reduce Agent Array Design

Q: When facing full-repository translation or migration tasks spanning hundreds of files, how does the "Map-Reduce" patterned Agent Array work?

A: When a single-point router (Team Lead) encounters hundreds of fragmented tasks, it also becomes a bottleneck. We use a Map-Reduce architecture akin to distributed computing:

graph TD
    Master[Master Node: Team Lead]
    
    subgraph "Map Phase (Task Slicing)"
        Master -->|Slice 100 files| Q[(Task Queue DB/File)]
    end
    
    subgraph "Parallel Worker Array"
        W1[Agent Worker 1] --- Q
        W2[Agent Worker 2] --- Q
        W3[Agent Worker 3] --- Q
    end
    
    subgraph "Reduce Phase (Merge Validation)"
        W1 & W2 & W3 -->|Write transpiled files| R_Pool[Temporary Artifact Pool]
        Reviewer[QA/Merge Agent] --> R_Pool
        Reviewer -->|Passes all tests| Final((Final Git Commit))
    end
    
    style Master fill:#8b5cf6,color:#fff
    style W1 fill:#3b82f6,color:#fff
    style W2 fill:#3b82f6,color:#fff
    style W3 fill:#3b82f6,color:#fff
    style Reviewer fill:#10b981,color:#fff

In this pattern, Worker Agents do not need to be assigned names; they all use uniform rules. They continuously fetch the next file from the queue, perform the conversion, and upon completion, fetch the next one. The Reviewer Agent continuously patrols the compilation status of completed files. This represents the highest paradigm of AI code generation industrialization at the current stage.

With this, all 18 issues of the "Claude Code Teams Practical: Deep Guide to Multi-Agent Parallel Development" conclude. When you cross the limits of a monolithic AI and master multi-agent parallel scheduling, state synchronization, and automated error correction, you are no longer just a programmer waiting for code generation in front of a terminal, but an architect owning an entire code automation factory. Wishing you smooth sailing in industrial-grade refactoring!