全局配置層（~/.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        # 項目級權(quán)限配置
│   ├── context/             # 持久化上下文文件
│   │   ├── architecture.md
│   │   ├── decisions.md
│   │   └── progress.md
│   └── commands/            # 自定義斜線命令
│       └── deploy.md
└── src/
    ├── CLAUDE.md            # 子目錄配置（可選）
    └── ...

# 全局 Claude 配置

## 行為準則
- 修改代碼前先理解整體架構(gòu)
- 不要在沒有確認的情況下進行大規(guī)模重構(gòu)
- 每次修改后運行相關(guān)測試

## 代碼風(fēng)格
- 優(yōu)先使用函數(shù)式編程
- 變量命名使用 camelCase（JS/TS），snake_case（Python）
- 注釋使用中文，代碼使用英文

## 多項目工作規(guī)范
- 在開始任何任務(wù)前，先讀取項目根目錄的 CLAUDE.md
- 讀取 .claude/context/ 下的上下文文件以了解項目歷史
- 更新 ROADMAP.md 的任務(wù)狀態(tài)（[ ] → [-] → [x]）

# Project A：電商平臺后端

## 項目概述
- 技術(shù)棧：Node.js + TypeScript + PostgreSQL + Redis
- 部署環(huán)境：AWS ECS
- 團隊規(guī)模：5 人

## 架構(gòu)約定
- 使用 Repository 模式隔離數(shù)據(jù)訪問層
- 所有 API 路由放在 src/routes/，業(yè)務(wù)邏輯放在 src/services/
- 數(shù)據(jù)庫遷移文件在 db/migrations/，禁止手動修改數(shù)據(jù)庫

## 權(quán)限邊界
- **禁止**：直接修改 src/auth/ 目錄（安全敏感）
- **禁止**：修改 docker-compose.prod.yml
- **需確認**：修改數(shù)據(jù)庫 Schema
- **自由操作**：src/utils/、src/routes/、tests/

## 當(dāng)前迭代目標
參見 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
# 場景：全棧聯(lián)調(diào)
claude --add-dir ../backend-api --add-dir ../shared-types
# 結(jié)合 print 模式用于腳本化
claude --add-dir ../backend -p "檢查當(dāng)前目錄的 API 調(diào)用是否與 ../backend 中定義的端點匹配"

# 在已有會話中擴展工作區(qū)
/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'

# 全棧聯(lián)調(diào)模式
alias cc-fullstack='cd ~/workspace/projects/active/project-a && claude --add-dir ../project-b'

## 任務(wù)管理規(guī)范

開始新任務(wù)時：
1. 用 TaskCreate 創(chuàng)建主任務(wù)，設(shè)置 description 詳述驗收標準
2. 將主任務(wù)拆解為子任務(wù)，用 addBlockedBy 設(shè)置依賴關(guān)系
3. 開始某個子任務(wù)時更新狀態(tài)為 in_progress
4. 完成后更新為 completed 并同步 ROADMAP.md

任務(wù)狀態(tài)：pending → in_progress → completed

# 在 .env 或 shell 配置中設(shè)置
export CLAUDE_CODE_TASK_LIST_ID=project-a-sprint-3

# 這樣不同終端窗口的 Claude 實例都會讀寫同一個任務(wù)列表
# Session A（前端）完成任務(wù)后，Session B（后端）立即能看到更新

# Project A 路線圖

## 進度標記約定
- `[ ]` = 待開始
- `[-]` = 進行中 ???
- `[x]` = 已完成 ?

## 當(dāng)前迭代（Sprint 3 - 2026/02/20 ~ 03/05）

### 高優(yōu)先級
- [-] **用戶認證重構(gòu)** - 遷移至 JWT + Refresh Token 方案 ??? 2026/02/24
- [ ] **支付接口對接** - 接入支付寶/微信支付
- [ ] **性能優(yōu)化** - 優(yōu)化數(shù)據(jù)庫查詢，目標響應(yīng)時間 < 100ms

### 中優(yōu)先級
- [ ] **日志系統(tǒng)升級** - 接入 ELK Stack
- [ ] **API 文檔完善** - 補全 OpenAPI 規(guī)范

## 最近完成
- [x] **數(shù)據(jù)庫遷移腳本** - 完成 v2 Schema 遷移 ? 2026/02/22
- [x] **CI/CD 流水線** - GitHub Actions 配置完成 ? 2026/02/20

## ROADMAP 維護規(guī)范
- 開始任務(wù)時：將 [ ] 改為 [-]，添加 ??? YYYY/MM/DD 時間戳
- 完成任務(wù)時：將 [-] 改為 [x]，將 ??? 改為 ? YYYY/MM/DD
- 使用 `date "+%Y/%m/%d"` 獲取當(dāng)前日期
- 新增任務(wù)時放入合適的優(yōu)先級區(qū)間

# 為并行任務(wù)創(chuàng)建工作樹
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（主協(xié)調(diào)者）
- 負責(zé)：架構(gòu)決策、代碼審查、合并沖突處理
- 工作目錄：主分支 main

### Agent B（功能開發(fā)）
- 負責(zé)：新功能實現(xiàn)，在 feature/* 分支工作
- 完成后：更新 .claude/context/progress.md，等待 Agent A 審查

### Agent C（測試與質(zhì)量）
- 負責(zé)：編寫測試、性能測試、文檔更新
- 依賴：Agent B 完成功能后再介入

## 協(xié)調(diào)規(guī)則
1. 不要在 main 分支直接推送代碼
2. 修改共享類型定義前，在 progress.md 中聲明
3. 發(fā)現(xiàn)跨 Agent 沖突時，寫入 .claude/context/decisions.md

#!/bin/bash
# scripts/automation/parallel-sprint.sh
# 并行啟動多個 Agent 處理 Sprint 任務(wù)
FEATURE_LIST=("auth-refactor" "payment-integration" "perf-optimization")
for feature in "${FEATURE_LIST[@]}"; do
    BRANCH="feature/$feature"
    WORKTREE="../project-a-$feature"
    # 創(chuàng)建 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[@]} 個并行任務(wù)"

# 架構(gòu)決策記錄

## 2026/02/20 - 選擇 JWT + Refresh Token 認證方案
- 背景：原 Session 方案在多實例環(huán)境下有狀態(tài)同步問題
- 決策：使用無狀態(tài) JWT，Refresh Token 存 Redis
- 影響文件：src/auth/、src/middleware/auth.ts

# 當(dāng)前進度狀態(tài)

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

### 進行中
- auth-refactor：JWT 基礎(chǔ)實現(xiàn)完成，Refresh Token 邏輯 50%

### 阻塞點
- 支付接口：等待第三方 API 密鑰（聯(lián)系人：產(chǎn)品經(jīng)理 @xiaoming）

### 下一步
- 完成 Refresh Token 邏輯
- 編寫 auth 模塊的集成測試

# 技術(shù)決策記錄

| 日期 | 決策 | 原因 | 影響范圍 |
|------|------|------|---------|
| 02/22 | 不使用 ORM，直接 SQL | 性能要求高，需要精細控制 | db/ 全部 |
| 02/24 | 錯誤碼統(tǒng)一用枚舉 | 避免硬編碼字符串散落各處 | src/errors/ |

## 每次會話開始時

請按以下順序讀取上下文：
1. 本 CLAUDE.md（已讀）
2. ROADMAP.md - 了解當(dāng)前迭代目標
3. .claude/context/progress.md - 了解上次進度和阻塞點
4. .claude/context/decisions.md - 了解已做的重要決策

讀取完成后，簡要總結(jié)當(dāng)前狀態(tài)，然后詢問本次會話的具體目標。

# .claude/commands/report.md
---
description: 生成項目進度報告
---

請分析以下內(nèi)容并生成一份簡潔的進度報告：
1. ROADMAP.md 中各任務(wù)的完成狀態(tài)
2. .claude/context/progress.md 中的阻塞項
3. 本次會話完成的工作

報告格式：
- 本周完成：（列表）
- 進行中：（列表，含完成百分比估算）
- 阻塞項：（列表，含負責(zé)人）
- 下周計劃：（列表）

生成后保存到 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  # 同上
# 創(chuàng)建上下文目錄
mkdir -p .claude/context

cd ~/workspace/projects/active/backend
claude  # 啟動后 Claude 會讀取 CLAUDE.md，自動加載項目上下文

今天繼續(xù)認證模塊的開發(fā)，請先讀取 .claude/context/progress.md 了解昨天的進度

# 需要參考前端的 API 調(diào)用方式時
/add-dir ../frontend

檢查 ../frontend/src/api/ 下對 /auth/login 接口的調(diào)用，確認后端的響應(yīng)格式是否匹配

請更新 .claude/context/progress.md，記錄今天完成的內(nèi)容和明天的待續(xù)工作，
同時更新 ROADMAP.md 中相關(guān)任務(wù)的狀態(tài)

---
description: 發(fā)布前多項目聯(lián)合檢查
---

執(zhí)行以下檢查并報告結(jié)果：

1. **后端**：運行 `npm test` 和 `npm run test:e2e`，確認全部通過
2. **API 兼容性**：比對 CHANGELOG.md，標出所有 Breaking Changes
3. **依賴更新**：檢查 package.json 是否有需要同步到前端的版本變更
4. **環(huán)境變量**：對比 .env.example，列出新增的必要環(huán)境變量

請用表格匯總檢查結(jié)果，標注 ?/?/?? 狀態(tài)

# Project B 配置
# 全局規(guī)范見 ~/.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)"
    ]
  }
}