Claude Code 多项目管理方案

全局配置层（~/.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 配置

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

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

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

# 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 --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

# 快速进入项目并启动 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'

## 任务管理规范

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

任务状态：pending → in_progress → completed

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

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

# 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

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

# 为并行任务创建工作树
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-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[@]} 个并行任务"

# 架构决策记录

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

# 当前进度状态

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

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

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

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

# 技术决策记录

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

## 每次会话开始时

请按以下顺序读取上下文：
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

# 克隆所有项目
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/context/progress.md 了解昨天的进度

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

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

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

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

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

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

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

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

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