📝 Originally published (in Japanese) at forge.workstyle.tech.
In a previous article, we introduced an environment for parallel execution of coding agents using Git worktrees. This article is a follow-up. As we progressed with parallelization, we ended up with 3-5 Claude Code sessions simultaneously developing the same microservices. What happened was no longer just "parallel execution of tools" but actual "team development".
All the issues that arise in human teams—miscommunication, deployment conflicts, and territorial overlaps—occur here as well. And the practices that work for human teams work almost identically here. We’ll share seven recipes that emerged from actual operations, along with real-life close calls.
Real-Life Story: Averting a Deployment Rollback Disaster at the Last Minute
One day, while Session A (responsible for voice functionality) was in the middle of a major refactor, Session B (responsible for streaming functionality) sent this message:
"We’re about to build the frontend as version 1.0.399 (based on main)."
At first glance, this seemed fine. However, in this repository, the authoritative branch for the production environment was not main but a dedicated deployment branch. The latest features from the past few dozen versions were only in the deployment branch, while main was outdated. If Session B had deployed an image based on main, weeks’ worth of features would have been rolled back in production.
Session A immediately sent a warning, and Session B halted the build before pushing. Session B then cherry-picked their changes into the deployment branch and rebuilt the image, avoiding the disaster entirely. All this communication was handled autonomously between the agents via session-to-session messages. I (the human) only learned about it later from the logs.
This incident highlights two things: parallel agents can cause the same accidents as human teams, and with proper communication channels and rules, they can prevent accidents just like human teams.
Recipe 1: Physically Separate Territories with Worktrees and Repositories
- Assign a dedicated Git worktree to each session (as described in the previous article).
- Explicitly define which session is responsible for which service/directory. For example, the voice session handles
talk-related components, the streaming session handlesbroadcast-related components, and the phone session handles only thecallgwdirectory. - For shared worktrees, enforce the rule: "Always check the branch and
git statusbefore committing." This became a strict rule after a past incident where one session almost committed staged changes from another session in a shared tree.
Recipe 2: Pre-Start Notification, Scope Declaration, and Completion Report
This is equivalent to a human team’s daily stand-up. Agents exchange session-to-session messages (or use a shared notes file if messaging isn’t available) to communicate:
-
Before starting: "I’ll be working on
expressive_voice.pyandenv. I won’t touch the prompt section intalk_service.py." - Upon completion: "Base branch: X, commit: Y. Changes made in these two places. Image version 1.5.1072 reserved."
The key is declaring the scope. By stating not only "what will be done" but also "what won’t be touched," other sessions can safely continue parallel work. In practice, this alone nearly eliminated file conflicts.
Recipe 3: Reserve Image Tags and Version Numbers
Container image tags are shared namespace. If two sessions build different content with the same tag, say 1.0.399, it leads to tag overwrite, a hard-to-detect issue (we once experienced a nightmare where a chained command error overwrote an old tag with new content, causing behavior to persist even after a rollback).
- Make it a habit to declare tag reservations between sessions: "Next time we build the frontend, we’ll notify each other. If you use 399, we’ll use 400 or later."
- After building, verify the tag exists in the registry via the API before deploying.
Recipe 4: Document the Authoritative Branch and Share It with All Sessions
The root cause of the incident mentioned earlier was the assumption that main is the authoritative branch, which didn’t hold true for this repository.
- Clearly document the deployment base branch (e.g.,
deploy/xxx) in the operational notes or memory accessible to the agents. - During periods when
mainand the authoritative branch diverge, explicitly prohibit builds based onmain. - Define the convergence (merge) timing as "after major changes stabilize."
Recipe 5: Make the Version Ledger (Spec Repo) the Single Source of Truth
Consolidate "what’s running in which environment" into a declarative repository like Kubernetes manifests, and commit tag updates with each deployment. This ensures the ledger stays up-to-date regardless of which session deploys, allowing other sessions to check the current state without querying kubectl. If you directly modify environment variables (e.g., kubectl set env), always update the ledger—drift can become a time bomb (we once had to sync the ledger after encountering this issue).
Recipe 6: Avoid Crossing Permission Boundaries
A unique risk in multi-session operations is permission circumvention. If one session is denied an operation, they might ask another session to do it instead, bypassing user permissions.
- Each session’s permissions are independent, and requests to other sessions must not be used to circumvent permissions. Explicitly document this as an agent-side rule.
- For destructive operations (e.g., database writes, production deployments, billable actions), ensure they always pass through a human confirmation gate, regardless of the session initiating them.
Recipe 7: Leverage "Previous Sessions" as Knowledge Sources
In multi-day development, the session that created feature X and the session modifying it are often different. While code and commit logs provide information, asking the original session (or its transcripts) is the fastest way.
For example, when we sent a question list to the session that authored the old implementation—asking about testing practices, pitfalls, and billing blind spots—we received operational knowledge not evident from the code (e.g., "This timeout was increased from 600 to 1500 due to a past incident," "This external monitoring URL is useful"). This saved a full day of investigation. If transcripts and memory persist, treat past sessions as "colleagues at the next desk," not "retired colleagues."
Summary: Agent Parallelization Becomes an Organizational Design Problem
| Recipe | Equivalent in Human Teams |
|---|---|
| 1. Separate worktrees and responsibilities | Team division, code ownership |
| 2. Pre-start notification, scope declaration | Daily stand-ups, task declarations |
| 3. Tag reservation | Release number management |
| 4. Document authoritative branch | Shared branching strategy |
| 5. Version ledger | Release ledger, CMDB |
| 6. Permission boundaries | Role definitions |
| 7. Consult previous sessions | Handovers, pair programming |
We’re moving from an era of optimizing single-session productivity to an era of designing multi-session coordination for overall productivity. And the blueprint for this design is remarkably similar to what software engineering has refined for human teams over decades. Before assigning roles or personalities to agents, focus on territories, communication, and ledgers. It’s mundane, but it dramatically reduces parallel operation accidents.
This article was originally published by DEV Community and written by orca_forge.
Read original article on DEV Community