Claude Code 多项目管理方案

目录

• 1. 核心理念与架构设计
• Claude Code 在多项目场景下面临三个核心挑战：
• 2. 目录结构规划
• 2.1 推荐的工作区目录结构
• 2.2 每个项目内部结构
• 3. CLAUDE.md 分层配置体系
• 3.1 全局 CLAUDE.md（~/.claude/CLAUDE.md）
• 3.2 项目级 CLAUDE.md
• 3.3 子目录 CLAUDE.md
• 4. 跨项目工作区管理
• 4.1 使用 –add-dir 同时处理多个项目
• 4.2 会话中动态添加目录
• 4.3 多项目快速切换脚本
• 5. 任务系统与持久化追踪
• 5.1 Claude Code 原生任务系统
• 5.2 跨会话共享任务列表
• 5.3 ROADMAP.md 进度追踪
• 6. 并行多 Agent 工作流
• 6.1 Git Worktree 并行开发
• 6.2 多 Agent 分工配置模板
• 6.3 自动化并行任务脚本
• 7. 项目状态与进度管理
• 7.1 上下文持久化文件体系
• 7.2 会话启动 Prompt 模板
• 7.3 每日/每周进度报告
• 8. 实战：完整的多项目工作流
• 8.1 初始化多项目工作区
• 8.2 典型工作日流程
• 8.3 发布前多项目检查清单
• 9. 常见问题与最佳实践
• Q1：多个项目的 CLAUDE.md 内容有大量重复，如何复用？
• Q2：并行 Agent 同时修改了同一个文件怎么办？
• Q3：如何防止 Claude 修改不该动的文件？
• Q4：如何在团队中共享 Claude 配置？
• Q5：上下文窗口满了怎么办？
• 附录：配置文件速查

上下文丢失：不同项目在不同会话中，AI 无法记住跨项目的约定和状态。

协作协调：多个 Claude 实例并行工作时，如何避免冲突，如何共享进度。

规范统一：不同项目有各自的技术栈、编码规范，需要自动化地让 Claude 遵守。

解决思路是建立一套"上下文持久化 + 分层配置 + 任务广播"的三层架构：

全局配置层（~/.claude/）
    ↓ 继承 + 覆盖
项目配置层（./CLAUDE.md + .claude/settings.json）
    ↓ 继承 + 覆盖
子模块配置层（src/CLAUDE.md）

~/workspace/
├── projects/
│   ├── active/              # 活跃项目
│   │   ├── project-a/
│   │   ├── project-b/
│   │   └── project-c/
│   └── archive/             # 已归档项目
├── shared/
│   ├── libraries/           # 共享库/组件
│   └── templates/           # 项目模板
├── scripts/
│   ├── automation/          # 自动化脚本
│   └── sync/                # 同步脚本
└── reports/
    ├── daily/
    └── weekly/

project-a/
├── CLAUDE.md                # 项目级 Claude 配置（必须）
├── ROADMAP.md               # 项目路线图（推荐）
├── .claude/
│   ├── settings.json        # 项目级权限配置
│   ├── context/             # 持久化上下文文件
│   │   ├── architecture.md
│   │   ├── decisions.md
│   │   └── progress.md
│   └── commands/            # 自定义斜线命令
│       └── deploy.md
└── src/
    ├── CLAUDE.md            # 子目录配置（可选）
    └── ...

这是所有项目共享的基础规范，放在用户主目录的 .claude/ 文件夹中。

# 全局 Claude 配置

## 行为准则
- 修改代码前先理解整体架构
- 不要在没有确认的情况下进行大规模重构
- 每次修改后运行相关测试

## 代码风格
- 优先使用函数式编程
- 变量命名使用 camelCase（JS/TS），snake_case（Python）
- 注释使用中文，代码使用英文

## 多项目工作规范
- 在开始任何任务前，先读取项目根目录的 CLAUDE.md
- 读取 .claude/context/ 下的上下文文件以了解项目历史
- 更新 ROADMAP.md 的任务状态（[ ] → [-] → [x]）

每个项目都应该有自己的 CLAUDE.md，覆盖或补充全局配置。

# Project A：电商平台后端

## 项目概述
- 技术栈：Node.js + TypeScript + PostgreSQL + Redis
- 部署环境：AWS ECS
- 团队规模：5 人

## 架构约定
- 使用 Repository 模式隔离数据访问层
- 所有 API 路由放在 src/routes/，业务逻辑放在 src/services/
- 数据库迁移文件在 db/migrations/，禁止手动修改数据库

## 权限边界
- **禁止**：直接修改 src/auth/ 目录（安全敏感）
- **禁止**：修改 docker-compose.prod.yml
- **需确认**：修改数据库 Schema
- **自由操作**：src/utils/、src/routes/、tests/

## 当前迭代目标
参见 ROADMAP.md 的 "High Priority" 部分

## 测试要求
- 所有新功能必须附带单元测试
- 运行：`npm test` 验证，`npm run test:e2e` 做集成测试

对于复杂项目，可以在特定子目录下添加更细粒度的配置：

# src/payments/ 子模块配置

## 特别注意
这是支付核心模块，所有修改必须：
1. 添加完整的错误处理
2. 记录审计日志
3. 通过 src/payments/__tests__/ 下的全量测试
4. 修改前在 .claude/context/decisions.md 记录变更原因

Claude Code 支持在一个会话中引入多个目录，无需切换上下文：

# 启动时同时引入前端和后端项目
claude --add-dir ../frontend-project
# 场景：全栈联调
claude --add-dir ../backend-api --add-dir ../shared-types
# 结合 print 模式用于脚本化
claude --add-dir ../backend -p "检查当前目录的 API 调用是否与 ../backend 中定义的端点匹配"

# 在已有会话中扩展工作区
/add-dir ../backend-api
# 同时添加多个
/add-dir ~/shared/libraries /add-dir ../analytics-service

注意：通过 –add-dir 添加的目录，其中的 CLAUDE.md 不会被自动读取，需要手动告知 Claude 查阅。

在 ~/.bashrc 或 ~/.zshrc 中配置项目别名：

# 快速进入项目并启动 Claude Code
alias cc-projecta='cd ~/workspace/projects/active/project-a && claude'
alias cc-projectb='cd ~/workspace/projects/active/project-b && claude'

# 全栈联调模式
alias cc-fullstack='cd ~/workspace/projects/active/project-a && claude --add-dir ../project-b'

Claude Code 内置了持久化任务管理（2025年1月升级），任务存储在 ~/.claude/tasks/ 下，跨会话不丢失。

在 CLAUDE.md 中配置任务工作流：

## 任务管理规范

开始新任务时：
1. 用 TaskCreate 创建主任务，设置 description 详述验收标准
2. 将主任务拆解为子任务，用 addBlockedBy 设置依赖关系
3. 开始某个子任务时更新状态为 in_progress
4. 完成后更新为 completed 并同步 ROADMAP.md

任务状态：pending → in_progress → completed

通过环境变量让多个 Claude 会话共享同一个任务列表：

# 在 .env 或 shell 配置中设置
export CLAUDE_CODE_TASK_LIST_ID=project-a-sprint-3

# 这样不同终端窗口的 Claude 实例都会读写同一个任务列表
# Session A（前端）完成任务后，Session B（后端）立即能看到更新

在每个项目根目录维护一个 ROADMAP.md，作为人类可读的进度面板：

# Project A 路线图

## 进度标记约定
- `[ ]` = 待开始
- `[-]` = 进行中 🏗️
- `[x]` = 已完成 ✅

## 当前迭代（Sprint 3 - 2026/02/20 ~ 03/05）

### 高优先级
- [-] **用户认证重构** - 迁移至 JWT + Refresh Token 方案 🏗️ 2026/02/24
- [ ] **支付接口对接** - 接入支付宝/微信支付
- [ ] **性能优化** - 优化数据库查询，目标响应时间 < 100ms

### 中优先级
- [ ] **日志系统升级** - 接入 ELK Stack
- [ ] **API 文档完善** - 补全 OpenAPI 规范

## 最近完成
- [x] **数据库迁移脚本** - 完成 v2 Schema 迁移 ✅ 2026/02/22
- [x] **CI/CD 流水线** - GitHub Actions 配置完成 ✅ 2026/02/20

在 CLAUDE.md 中让 Claude 自动维护这个文件：

## ROADMAP 维护规范
- 开始任务时：将 [ ] 改为 [-]，添加 🏗️ YYYY/MM/DD 时间戳
- 完成任务时：将 [-] 改为 [x]，将 🏗️ 改为 ✅ YYYY/MM/DD
- 使用 `date "+%Y/%m/%d"` 获取当前日期
- 新增任务时放入合适的优先级区间

Git Worktree 是多 Agent 并行工作的基础，每个 Agent 在独立的工作树中工作，互不干扰：

# 为并行任务创建工作树
git worktree add ../project-a-feature-auth feature/auth-refactor
git worktree add ../project-a-feature-payment feature/payment-integration
# 在不同终端分别启动 Claude
# 终端 1：
cd ../project-a-feature-auth && claude
# 终端 2：
cd ../project-a-feature-payment && claude

在 .claude/context/ 下创建 Agent 分工说明：

# .claude/context/agent-roles.md

## Agent 分工说明

### Agent A（主协调者）
- 负责：架构决策、代码审查、合并冲突处理
- 工作目录：主分支 main

### Agent B（功能开发）
- 负责：新功能实现，在 feature/* 分支工作
- 完成后：更新 .claude/context/progress.md，等待 Agent A 审查

### Agent C（测试与质量）
- 负责：编写测试、性能测试、文档更新
- 依赖：Agent B 完成功能后再介入

## 协调规则
1. 不要在 main 分支直接推送代码
2. 修改共享类型定义前，在 progress.md 中声明
3. 发现跨 Agent 冲突时，写入 .claude/context/decisions.md

#!/bin/bash
# scripts/automation/parallel-sprint.sh
# 并行启动多个 Agent 处理 Sprint 任务
FEATURE_LIST=("auth-refactor" "payment-integration" "perf-optimization")
for feature in "${FEATURE_LIST[@]}"; do
    BRANCH="feature/$feature"
    WORKTREE="../project-a-$feature"
    # 创建 worktree
    git worktree add "$WORKTREE" -b "$BRANCH" 2>/dev/null || true
    # 在新终端启动 Claude（macOS 示例）
    osascript -e "tell app "Terminal" to do script "cd $WORKTREE && claude""
    echo "✅ 已启动 Agent 处理: $feature"
done
echo "🚀 所有 Agent 已启动，共 ${#FEATURE_LIST[@]} 个并行任务"

在 .claude/context/ 中维护以下文件，帮助 Claude 在每次会话开始时快速恢复上下文：

architecture.md：记录关键架构决策

# 架构决策记录

## 2026/02/20 - 选择 JWT + Refresh Token 认证方案
- 背景：原 Session 方案在多实例环境下有状态同步问题
- 决策：使用无状态 JWT，Refresh Token 存 Redis
- 影响文件：src/auth/、src/middleware/auth.ts

progress.md：记录当前工作状态

# 当前进度状态

## 最后更新：2026/02/26

### 进行中
- auth-refactor：JWT 基础实现完成，Refresh Token 逻辑 50%

### 阻塞点
- 支付接口：等待第三方 API 密钥（联系人：产品经理 @xiaoming）

### 下一步
- 完成 Refresh Token 逻辑
- 编写 auth 模块的集成测试

decisions.md：记录重要技术决策

# 技术决策记录

| 日期 | 决策 | 原因 | 影响范围 |
|------|------|------|---------|
| 02/22 | 不使用 ORM，直接 SQL | 性能要求高，需要精细控制 | db/ 全部 |
| 02/24 | 错误码统一用枚举 | 避免硬编码字符串散落各处 | src/errors/ |

在 CLAUDE.md 中加入会话启动规范：

## 每次会话开始时

请按以下顺序读取上下文：
1. 本 CLAUDE.md（已读）
2. ROADMAP.md - 了解当前迭代目标
3. .claude/context/progress.md - 了解上次进度和阻塞点
4. .claude/context/decisions.md - 了解已做的重要决策

读取完成后，简要总结当前状态，然后询问本次会话的具体目标。

创建自动生成报告的自定义命令：

# .claude/commands/report.md
---
description: 生成项目进度报告
---

请分析以下内容并生成一份简洁的进度报告：
1. ROADMAP.md 中各任务的完成状态
2. .claude/context/progress.md 中的阻塞项
3. 本次会话完成的工作

报告格式：
- 本周完成：（列表）
- 进行中：（列表，含完成百分比估算）
- 阻塞项：（列表，含负责人）
- 下周计划：（列表）

生成后保存到 reports/weekly/YYYY-MM-DD.md

使用方式：在 Claude Code 中输入 /report

以"前后端分离项目 + 共享类型库"三库联动为例：

# 克隆所有项目
git clone https://github.com/org/frontend ~/workspace/projects/active/frontend
git clone https://github.com/org/backend ~/workspace/projects/active/backend
git clone https://github.com/org/shared-types ~/workspace/shared/types
# 为每个项目初始化 Claude 配置
cd ~/workspace/projects/active/frontend
claude  # 输入 /init 生成初始 CLAUDE.md，然后按需编辑
cd ~/workspace/projects/active/backend
claude  # 同上
# 创建上下文目录
mkdir -p .claude/context

早上：启动上下文

cd ~/workspace/projects/active/backend
claude  # 启动后 Claude 会读取 CLAUDE.md，自动加载项目上下文

在 Claude 中输入：

今天继续认证模块的开发，请先读取 .claude/context/progress.md 了解昨天的进度

开发中：跨项目联调

# 需要参考前端的 API 调用方式时
/add-dir ../frontend

然后对 Claude 说：

检查 ../frontend/src/api/ 下对 /auth/login 接口的调用，确认后端的响应格式是否匹配

下班前：保存状态

请更新 .claude/context/progress.md，记录今天完成的内容和明天的待续工作，
同时更新 ROADMAP.md 中相关任务的状态

创建 .claude/commands/pre-release.md：

---
description: 发布前多项目联合检查
---

执行以下检查并报告结果：

1. **后端**：运行 `npm test` 和 `npm run test:e2e`，确认全部通过
2. **API 兼容性**：比对 CHANGELOG.md，标出所有 Breaking Changes
3. **依赖更新**：检查 package.json 是否有需要同步到前端的版本变更
4. **环境变量**：对比 .env.example，列出新增的必要环境变量

请用表格汇总检查结果，标注 ✅/❌/⚠️ 状态

将通用规范放入全局 ~/.claude/CLAUDE.md，各项目的 CLAUDE.md 只写差异化内容。在项目 CLAUDE.md 开头加一行：

# Project B 配置
# 全局规范见 ~/.claude/CLAUDE.md，以下为项目特有配置

最佳实践是在任务分配时就规划好文件边界：

• Agent A 负责 src/auth/，Agent B 负责 src/payment/
• 共享的类型定义（如 src/types/）在 decisions.md 中声明谁在修改
• 使用 Git Worktree 确保各 Agent 在独立分支，合并时统一处理冲突

在 .claude/settings.json 中配置权限规则：

{
  "permissions": {
    "deny": [
      "Write(src/auth/**)",
      "Write(docker-compose.prod.yml)",
      "Bash(git push --force*)"
    ],
    "allow": [
      "Write(src/utils/**)",
      "Write(tests/**)",
      "Bash(npm test)"
    ]
  }
}

将项目根目录的 CLAUDE.md 和 .claude/settings.json 提交到 Git 仓库中，团队所有成员自动共享同一套规范。~/.claude/ 下的个人配置则保留在本地，不提交。

将长期积累的信息沉淀到文件中（.claude/context/），每次会话开始时只读取摘要，需要时再读详情。同时定期清理 decisions.md，将过时的决策标记为 [已废弃]。

文件路径	作用	是否提交 Git
~/.claude/CLAUDE.md	全局规范	否（个人）
~/.claude/settings.json	全局权限配置	否（个人）
./CLAUDE.md	项目规范	是
./.claude/settings.json	项目权限配置	是
./.claude/context/*.md	上下文持久化	视情况
./.claude/commands/*.md	自定义命令	是
./ROADMAP.md	进度追踪	是

到此这篇关于Claude Code 多项目管理方案的文章就介绍到这了,更多相关Claude Code 多项目管理内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！