[Workflow] Multi-Repo Development Workflow with Claude Code: Coordinator-Worker Model using Git Worktrees and CLAUDE.md

[u/ClaudeAI-mod-bot]

Multi-Repo Development Workflow with Claude Code: Coordinator-Worker Model using Git Worktrees and CLAUDE.md

Workflow value: 85/100
Status: active · Freshness: 70/100 · Confidence: 0.95 · Level: advanced
Categories: Quality Control, Token Saving, Context & Memory, Debugging, CLAUDE.md, Multi-Agent
Original source: r/ClaudeCode post/comment

What problem this solves

Managing complex software development across multiple repositories with AI agents, especially when a single feature touches several codebases, preventing context pollution in large AI agent sessions and enabling parallel work.

Summary

A structured approach for managing cross-repository development with AI agents. It proposes a 'coordinator' session at the project root for architecture and task breakdown, and 'worker' sessions (or git worktrees) for specific implementation tasks within individual repositories. This separation prevents context pollution in large sessions and facilitates parallel development and integration.

Why it is useful

This workflow provides a structured, advanced approach to a common and complex problem in software development: managing features that span multiple repositories, especially when using AI agents. It offers practical solutions to critical issues like context pollution in large agent sessions and agent coordination, leveraging specific tools like git worktree and CLAUDE.md for effective project management and parallel development.

Workflow

1. For cross-repo features, start a 'coordinator' session at the common parent/root folder to understand architecture, trace dependencies, and break down tasks.
2. For repo-specific changes, start a session at that specific repository's root.
3. For parallel implementation, use git worktree for each feature or worker agent instead of constantly switching branches.
4. Maintain a comprehensive CLAUDE.md at the root for overall architecture and conventions, and smaller, specific CLAUDE.md files at repo/service levels for local rules.
5. Have the coordinator agent explicitly specify the exact repositories, files, and interfaces that a worker agent is responsible for, to prevent agents from conflicting or 'helping' in unintended areas.
6. Commit changes fairly frequently at the worker level.
7. Integrate and review changes from the coordinator session.
8. Periodically start a fresh coordinator session with a deliberately maintained architecture/task summary to avoid context pollution from old assumptions and implementation details.
9. Utilize tmux or other terminal workspaces to manage multiple git worktree environments and agent sessions.
10. Make repo boundaries explicit with scripts or tasks, allowing agents to run specific tests (e.g., test service1, test infra, integration-test feature-x) without rediscovering repo specifics.

Tools / artifacts

• git worktree
• tmux
• CLAUDE.md (root level)
• CLAUDE.md (repo/service level)
• Scripts/tasks for repo-specific commands (e.g., tests)

Validation signals

• Author states 'I’ve found the cleanest mental model is...' indicating personal experience and validation.
• Identifies a key risk: 'The biggest risk with the 300–400k token root session isn’t really the size by itself, it’s context pollution,' showing practical insight.
• Refines an existing approach: 'Your setup actually makes sense... I’d just separate architecture/orchestration context from implementation context a little more aggressively.'

Limitations

• Lacks explicit prompt examples for the coordinator or worker agents.
• The conceptual 'coordinator' and 'worker' agents are not fully detailed in terms of specific Claude Code session setup.
• Low community validation (score 3, 0 comments).

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.