Skip to content

Record how parallel agent work is isolated, split, and merged - #116

Open
sudoshi wants to merge 1 commit into
mainfrom
docs/parallel-agents-rule
Open

sudoshi wants to merge 1 commit into
mainfrom
docs/parallel-agents-rule

Conversation

@sudoshi

@sudoshi sudoshi commented Jul 27, 2026

Copy link
Copy Markdown
Owner

Adds .claude/rules/parallel-agents.md and points CLAUDE.md at it as binding on
any change bigger than a single-file edit.

The rule separates two problems that are easy to conflate: worktrees give
isolation, and isolation does nothing for coordination.
Layer 2 (decomposition
by domain boundary, the single-writer file list, freezing contracts before
fanning out) and Layer 3 (sequential rebase-and-merge, the green gate, never
letting an agent auto-resolve another agent's conflict) are where the expensive
failures actually happen.

This session produced the evidence. Two efforts independently claimed
net.acumenus.nightingale — #101 renaming the patient app in place, #92
building a new foundation tree. Both were internally correct, neither could see
the other, and git merge-tree reported zero conflicts while producing two
applications competing for one App Store record. It was caught by reading diffs
by hand, after one had already shipped to TestFlight.

Two of the rule's specifics were also violated during this session, which is
part of why it is worth writing down:

  • .github/workflows/ci.yml and docs/hummingbird/api-contract/** are
    single-writer files. Both were edited directly rather than proposed.
  • "Merge one branch at a time" — five PRs ended up open simultaneously.

Related: #111 adds verify-app-identity-uniqueness.sh, the CI guard that turns
the identity half of this rule into something enforced rather than remembered.

Adds .claude/rules/parallel-agents.md and points CLAUDE.md at it as binding on
any change bigger than a single-file edit.

The rule separates two problems that are easy to conflate: worktrees give
isolation, and isolation does nothing for coordination. Layer 2 (decomposition
by domain boundary, the single-writer file list, freezing contracts before
fanning out) and Layer 3 (sequential rebase-and-merge, the green gate, never
letting an agent auto-resolve another agent's conflict) are where the expensive
failures actually happen.

This session produced the evidence for it. Two efforts independently claimed
net.acumenus.nightingale — one renaming the patient app in place, one building
a new foundation tree. Both were internally correct, neither could see the
other, and the merge reported zero conflicts while producing two applications
competing for one App Store record. It was caught by reading diffs by hand,
after one had already shipped to TestFlight.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@sudoshi
sudoshi enabled auto-merge (squash) July 28, 2026 00:50

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant