From 1fdae40660a1ef6cead77cb42f7346e2b51ac317 Mon Sep 17 00:00:00 2001
From: Alex <hanweng9@gmail.com>
Date: Tue, 21 Apr 2026 12:23:44 -0400
Subject: [PATCH] docs: add git worktree guidance for multi-agent workflow
 (#535)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

- This repo is worked on by multiple coding agents (Claude, Codex,
Devin,
etc.) in parallel. Switching branches inside a single shared working
tree
drags unrelated WIP from whoever else is active into your build,
surfaces
Swift's "input file ... was modified during the build" errors, and makes
  it easy to accidentally sweep other agents' files into a commit.
- Document \`git worktree\` as the convention: shared \`.git\`, isolated
  working tree and \`.build/\`, one tree per active task.

## Test plan

- [x] This PR branch was itself created via \`git worktree add\` to
dogfood
      the pattern — zero interference with the concurrent CosyVoice3 WIP
      in the primary checkout.
- [ ] Reviewer: confirm the command snippet matches your preferred
naming
      convention for the worktree directory.
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/fluidinference/fluidaudio/pull/535"
target="_blank">
  <picture>
<source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
<img
src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1"
alt="Open in Devin Review">
  </picture>
</a>
<!-- devin-review-badge-end -->
---
 CLAUDE.md | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1c71a10a..7b51947c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -50,9 +50,24 @@ FluidAudio is a Swift framework for local, low-latency audio processing on Apple
 3. **Git Operations**: Never run `git push` unless explicitly requested.
    - **No Co-Author Tags**: Do not add `Co-Authored-By` lines for Claude, Copilot, or any AI assistant in commit messages.
    - **No GitHub comments**: Never post comments, reviews, or reactions on issues or PRs via `gh`. Reading issues, PRs, and comments is fine. Creating PRs and editing PR titles/bodies is fine.
-4. **Code Formatting**: All code must pass swift-format checks before merge
-5. **Avoid Deprecated Code**: Do not add support for deprecated models or features unless explicitly requested
-6. **Performance**: Keep RTFx > 1.0x for real-time capability
+4. **Multi-Agent Workflow**: This repo is worked on by multiple coding agents
+   in parallel. Switching branches in a shared working tree drags unrelated
+   WIP changes (and their build artifacts) into your compile and surfaces
+   "file was modified during the build" errors. Use `git worktree` instead
+   — shared `.git`, isolated working tree + `.build/`, no collisions.
+
+   ```bash
+   # From the primary checkout, create an isolated tree for your branch
+   git worktree add ../FluidAudio-<task> -b <branch> origin/main
+   cd ../FluidAudio-<task>
+   # Independent working tree, independent .build/, shared .git
+   ```
+
+   One worktree per active task. Remove with `git worktree remove <path>` when
+   done. List active worktrees with `git worktree list`.
+5. **Code Formatting**: All code must pass swift-format checks before merge
+6. **Avoid Deprecated Code**: Do not add support for deprecated models or features unless explicitly requested
+7. **Performance**: Keep RTFx > 1.0x for real-time capability
 
 ## Code Style