Multi-Agent Collaboration with Claude Code and Codex: A Guide to Architecture Design and State Management

From Single Agent to Multi-Agent Collaboration

As AI programming tools mature, more and more developers are exploring the possibility of having multiple AI Agents collaborate on the same project. A content creator on Bilibili shared his real-world experience: he initially used Claude Code alone to develop an Agent project, but as data volume grew and code redundancy increased, the single Agent's processing capacity gradually hit its ceiling. To address this, he brought in Codex as a collaborator and designed a protocol for the two Agents to work together.

Technical Background: Multi-Agent Systems (MAS) are not a new concept — their theoretical foundations trace back to distributed artificial intelligence research in the 1980s. In traditional software engineering, microservice architecture improves maintainability by decomposing monolithic applications into independent services. Multi-Agent collaboration essentially migrates this philosophy to the AI execution layer — each Agent takes on specific responsibilities and coordinates through message passing and state sharing to complete complex tasks. Claude Code is Anthropic's terminal-native programming Agent, capable of directly reading/writing file systems and executing commands. OpenAI's Codex, on the other hand, excels at code generation and comprehension. Their different capability matrices create a natural complementary relationship, which is the technical premise of the practices described in this article.

However, the initial practice didn't go smoothly. Due to a lack of upfront planning, Claude Code and Codex frequently performed redundant work — both Agents tackled the same tasks independently, wasting computational resources and failing to leverage each other's strengths. This lesson leads to the article's central argument: the success or failure of multi-Agent collaboration largely depends on upfront architecture design.

Upfront Design: The Decisive Factor in Multi-Agent Collaboration

After learning the hard way, the author distilled a key takeaway: before a project begins, you must first assess the project's complexity, then design the overall architecture accordingly. The architecture should not only define the project structure but also establish clear specifications for each Agent — who is responsible for what, and how results are verified upon completion.

His approach was to have the primary controller read a pre-designed "collaboration contract" file, then use that file as a basis for discussing project complexity with the Agent and jointly determining the architectural direction. This contract is essentially a code of conduct for inter-Agent collaboration, defining the division of labor and execution workflow.

The Engineering Essence of Collaboration Contracts: The "collaboration contract" file the author describes corresponds to concepts like "Agent Communication Language" (ACL) or "Behavioral Specification" in academia. In engineering practice, such files typically use YAML, Markdown, or JSON formats to describe each Agent's responsibility boundaries, input/output formats, exception handling strategies, and acceptance criteria. At its core, this makes implicit collaboration assumptions explicit — eliminating ambiguity is the first principle of distributed system design. Analogous to API contracts (OpenAPI Specification) in microservices, Agent contracts ensure every participant reaches consensus on the definition of "done," thereby avoiding large-scale rework during the integration phase.

The author particularly emphasized: if you get all the data and planning organized upfront, the subsequent collaboration between the two Agents will be fast and smooth, while truly leveraging each one's strengths. Conversely, cutting corners upfront inevitably leads to a quagmire of redundant work and wasted resources.

Minimalist File Structure: A State-Driven Collaboration Mechanism

The author shared what he considers the simplest viable file structure, consisting of the following core components:

Overview and State Folders

• Overview folder: Global information accessible to both Agents
• State folder: Kept minimal — ideally a single sentence describing "what's been completed and what still needs to be done"

State management is the soul of the entire collaboration mechanism. After each Agent completes a task, it "checks a box." When the second Agent sees the checked state, it knows the previous step is ready and can proceed. This relay approach based on state markers fundamentally prevents information chaos and redundant work.

Distributed State Machine Principles: The "checkbox" state-marking mechanism described here is essentially a lightweight implementation of a Distributed State Machine. In classical distributed system design, task states are typically synchronized through message queues (like Kafka) or shared storage (like Redis) to handle concurrent read/write operations, network partitions, and similar challenges. The author's minimalist approach — using state files in the file system instead of complex middleware — reflects a "good enough" engineering philosophy. It's worth noting that atomic writes to the file system are not always guaranteed, which is precisely why the author later mentions the need for a "lock file" mechanism: Lock Files are a classic operating system primitive for preventing multiple processes or Agents from simultaneously modifying the same resource, widely used in package managers like npm and pip.

Workspaces and Handoff Files: Private and Public Zones

The author divides the workspace into two categories: private zones and public zones:

• Private zone: Independent workspaces for Claude Code and Codex respectively, with no interference between them
• Public zone: A shared area for exchanging data and documents between both parties

When Codex finishes collecting data or completing a task, it places the results in the public zone. Claude Code then reads this handoff data and performs secondary verification on any questionable "gaps." The "public zone handoff + secondary verification" mechanism ensures transparent data flow while improving output quality through cross-validation.

Blackboard Systems and the Information Hiding Principle: The author's design of dividing workspaces into private and public zones closely aligns with the "Information Hiding" principle and the "Shared Memory" model in software engineering. Private zones ensure that each Agent's intermediate states are not exposed to other participants, reducing coupling. The public zone functions as a "Blackboard System" — a multi-Agent collaboration architecture pattern first introduced by the HEARSAY speech understanding system in the 1970s. The core idea is that all Agents read from and write to a shared "blackboard," each contributing solutions in their area of expertise. The secondary verification mechanism corresponds to "Defensive Programming" in software quality assurance, using cross-checks to reduce single-point error propagation.

Structure Evolves with Complexity

The author repeatedly emphasizes a pragmatic point: no single fixed structure can handle every scenario.

The minimalist structure described above is only suitable for relatively simple projects. As project complexity increases, additional mechanisms need to be introduced — for example, adding lock files to avoid concurrency conflicts, or adding other control files to manage more complex collaboration relationships. The more complex the project, the more details need to be considered, and the structure naturally evolves accordingly.

This reflects engineering pragmatism: architecture should serve actual needs rather than chase some "standard answer." Developers need to continuously analyze and adjust based on the project's real situation, letting the structure grow alongside the project.

From Controlling a Single Agent to Directing an AI Team

The most illuminating insight in this article comes at the end: the author positions himself as the primary controller, responsible for setting direction and assigning tasks for the entire Agent team.

Notably, Claude Code has subagent capabilities, and Codex can similarly invoke sub-Agents — meaning developers are no longer controlling just one or two tools, but are effectively directing an entire AI team.

Technical Evolution of Hierarchical Agent Architecture: Claude Code's subagent capabilities and Codex's ability to invoke sub-Agents represent a significant evolutionary direction in current AI Agent architecture — from "flat single-Agent" to "hierarchical Agent tree." This follows the same logic as the evolution of enterprise organizational structures: as business scale expands and a single decision-maker can no longer handle all details, middle management layers inevitably emerge. In technical implementation, this type of hierarchical architecture is typically called the "Orchestrator-Executor pattern": the top-level Orchestrator handles task decomposition and scheduling, while bottom-level Executor Agents handle specific execution. Open-source projects like OpenAI's Swarm framework, LangGraph, and Microsoft's AutoGen are all actively exploring standardized implementations of this pattern. As the "Agent as a Tool" paradigm gains popularity, every specialized Agent may become a callable tool node for higher-level Agents, thereby building powerful nested Agent networks.

The author further envisions that future collaborators won't be limited to Codex and Claude Code — Harmony and various open-source Agents can also be brought in. Whichever Agent is stronger in a particular domain gets incorporated into the team.

"You're not really controlling a set of tools — you're controlling a team that works for you."

This statement precisely captures the fundamental shift in multi-Agent collaboration: the developer's role is evolving from "tool user" to "team manager." And the core skills needed to manage an AI team — clear architecture design, well-defined division of labor, effective state management — are remarkably consistent with those needed to manage a human team.

Conclusion

The takeaway from this practice is highly practical: multi-Agent collaboration isn't simply putting two AIs together — it's a systems engineering challenge. It requires thorough upfront planning, a state-driven collaboration mechanism, clear private/public zone separation, and structural design that flexibly evolves with complexity.

As AI programming Agents continue to grow more capable, "directing AI teams" is gradually becoming one of developers' core competitive advantages. Those who can design efficient multi-Agent collaboration protocols will gain a head start in the next wave of AI productivity.