cc-devflow 1.0.2 → 2.4.0

package/.claude/commands/flow-review.md

@@ -0,0 +1,257 @@
+---
+name: flow-review
+description: 'Two-Stage Code Review. Usage: /flow-review "REQ-123" or /flow-review'
+agents:
+  spec: .claude/agents/spec-reviewer.md
+  quality: .claude/agents/code-reviewer.md
+skills:
+  verification: .claude/skills/verification-before-completion/SKILL.md
+  receiving: .claude/skills/flow-receiving-review/SKILL.md
+---
+
+# Flow-Review - 两阶段代码审查
+
+## User Input
+
+```text
+$ARGUMENTS = "REQ_ID" 或 空 (自动检测当前分支)
+```
+
+**示例**:
+```
+/flow-review "REQ-123"
+/flow-review              # 自动从分支名提取 REQ-ID
+```
+
+---
+
+## 核心理念
+
+### Two-Stage Review
+
+```
+Stage 1: SPEC COMPLIANCE (先)
+┌─────────────────────────────────────────┐
+│ • 加载 PRD, EPIC, TASKS, BRAINSTORM    │
+│ • 创建需求清单                         │
+│ • 逐项验证（不信任实现者报告）         │
+│ • 检查超范围（scope creep）            │
+│ • 输出: SPEC_REVIEW.md                 │
+└─────────────────────────────────────────┘
+              ↓ Pass?
+Stage 2: CODE QUALITY (后)
+┌─────────────────────────────────────────┐
+│ • 代码清晰度、结构、命名               │
+│ • 测试质量和覆盖率                     │
+│ • Constitution 合规                    │
+│ • 性能和安全                           │
+│ • 输出: CODE_QUALITY_REVIEW.md         │
+└─────────────────────────────────────────┘
+```
+
+**关键**: Stage 2 只在 Stage 1 通过后执行。
+
+---
+
+## 执行流程
+
+### Stage 0: Entry Gate
+
+```yaml
+1. 解析 REQ_ID
+   → 从参数获取，或从分支名提取 (feature/REQ-123-xxx)
+
+2. 验证需求目录存在
+   → devflow/requirements/${REQ_ID}/
+
+3. 加载必需文档
+   → PRD.md, EPIC.md, TASKS.md, BRAINSTORM.md
+
+4. 检查实现状态
+   → TASKS.md 中所有任务标记为完成
+```
+
+---
+
+### Stage 1: Spec Compliance Review
+
+**调用**: `{AGENT:spec}` (spec-reviewer)
+
+```yaml
+执行:
+  1. 构建需求清单
+     → 从 PRD 提取验收标准
+     → 从 TASKS 提取预期结果
+
+  2. 代码验证 (不信任报告)
+     → 读取实际代码
+     → 逐项验证实现
+     → 标记: ✅ 实现 | ❌ 缺失 | ⚠️ 部分 | 🚫 超范围
+
+  3. Scope Creep 检测
+     → 扫描未在规格中的功能
+     → 每个额外功能 = 缺陷
+
+  4. BRAINSTORM 对齐检查
+     → 是否解决原始问题
+     → 是否遵循选定方案
+
+输出: devflow/requirements/${REQ_ID}/SPEC_REVIEW.md
+```
+
+**通过条件**:
+- 所有需求项标记为 ✅
+- 无 Scope Creep (🚫)
+- BRAINSTORM 对齐
+
+**失败处理**:
+```yaml
+如果 Stage 1 失败:
+  → 输出 SPEC_REVIEW.md 包含失败项
+  → 列出必需修复项
+  → 停止，不进入 Stage 2
+  → 返回给开发者修复
+```
+
+---
+
+### Stage 2: Code Quality Review
+
+**前置**: Stage 1 必须通过
+
+**调用**: `{AGENT:quality}` (code-reviewer)
+
+```yaml
+执行:
+  1. 代码清晰度
+     → 命名是否清晰
+     → 结构是否合理
+     → 注释是否必要且有用
+
+  2. 测试质量
+     → 覆盖率 ≥ 80%
+     → 测试是否有意义 (非 cheater tests)
+     → 边界情况是否覆盖
+
+  3. Constitution 合规
+     → Article I: 完整实现
+     → Article II: 无重复代码
+     → Article III: 无硬编码密钥
+     → Article IV: 无资源泄漏
+     → Article V: 无死代码
+     → Article VI: TDD 顺序
+
+  4. 性能和安全
+     → 无明显性能问题
+     → 无安全漏洞
+
+输出: devflow/requirements/${REQ_ID}/CODE_QUALITY_REVIEW.md
+```
+
+---
+
+### Stage 3: Exit Gate
+
+```yaml
+验证:
+  1. SPEC_REVIEW.md 状态 = PASS
+  2. CODE_QUALITY_REVIEW.md 状态 = PASS
+  3. 所有阻塞问题已解决
+
+输出:
+  → 更新 orchestration_status.json
+  → 记录到 EXECUTION_LOG.md
+```
+
+---
+
+## 输出产物
+
+```
+devflow/requirements/${REQ_ID}/
+├── SPEC_REVIEW.md           # Stage 1 输出
+├── CODE_QUALITY_REVIEW.md   # Stage 2 输出
+└── EXECUTION_LOG.md         # 更新
+```
+
+---
+
+## 收到审查反馈后
+
+当收到审查反馈时，使用 `{SKILL:receiving}` 原则：
+
+```yaml
+处理反馈:
+  1. 不盲目同意
+     → 反馈可能有误
+     → 技术上可疑？先验证
+
+  2. 不清楚？提问澄清
+     → "这个建议的具体原因是什么？"
+     → "能否提供示例？"
+
+  3. 验证后再实现
+     → 确认建议正确
+     → 然后实施修改
+```
+
+---
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "实现者说完成了" | 读代码验证。不信任报告。 |
+| "测试通过了" | 测试可能不覆盖所有需求。 |
+| "差不多就行" | 差不多 ≠ 正确。规格是契约。 |
+| "额外功能是好事" | 额外 = scope creep = 缺陷。 |
+| "Stage 1 太严格" | 严格是为了质量。不妥协。 |
+
+---
+
+## 错误处理
+
+### Stage 1 失败
+
+```yaml
+输出:
+  - SPEC_REVIEW.md (包含失败项)
+  - 必需修复清单
+
+下一步:
+  - 开发者修复缺失/超范围项
+  - 重新运行 /flow-review
+```
+
+### Stage 2 失败
+
+```yaml
+输出:
+  - CODE_QUALITY_REVIEW.md (包含问题)
+  - 改进建议
+
+下一步:
+  - 开发者修复质量问题
+  - 重新运行 /flow-review
+```
+
+---
+
+## Next Step
+
+```
+/flow-qa "${REQ_ID}"
+```
+
+进入 QA 测试阶段
+
+---
+
+**Related Documentation**:
+- [spec-reviewer.md](../.claude/agents/spec-reviewer.md) - Stage 1 Agent
+- [code-reviewer.md](../.claude/agents/code-reviewer.md) - Stage 2 Agent
+- [verification-before-completion](../.claude/skills/verification-before-completion/SKILL.md) - 验证技能
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/docs/templates/ATTEMPT_TEMPLATE.md

@@ -0,0 +1,156 @@
+# Research Attempt Template
+
+> 本模板用于记录研究阶段的失败尝试。失败是学习数据，记录下来避免重复错误。
+
+---
+
+## 文件命名规范
+
+```
+research/attempts/NNN-descriptive-name.md
+```
+
+**示例**:
+- `001-graphql-approach.md` - 尝试 GraphQL，因性能问题放弃
+- `002-rest-pagination.md` - 尝试偏移分页，改用游标分页
+- `003-redis-cache.md` - 尝试 Redis 缓存，因成本放弃
+
+---
+
+## 模板内容
+
+```markdown
+# Attempt: [方案名]
+
+**Date**: YYYY-MM-DD
+**Context**: 解决 [什么问题]
+
+## Approach
+
+[描述尝试的方案]
+
+## Result
+
+❌ 失败 / ⚠️ 部分成功 / 🔄 放弃
+
+## Reason
+
+[为什么不行]
+
+## Learning
+
+[下次应该注意什么]
+
+## References
+
+- [相关文档链接]
+- [相关代码片段]
+```
+
+---
+
+## 示例 1: 放弃 GraphQL
+
+```markdown
+# Attempt: GraphQL API Architecture
+
+**Date**: 2026-01-08
+**Context**: 解决前后端 API 通信，考虑使用 GraphQL 代替 REST
+
+## Approach
+
+使用 Apollo Server + GraphQL Schema 定义 API：
+- 单一端点 /graphql
+- 客户端按需查询字段
+- 减少 over-fetching 和 under-fetching
+
+## Result
+
+🔄 放弃
+
+## Reason
+
+1. **学习曲线**: 团队对 GraphQL 不熟悉，估计学习时间 2 周
+2. **工具链复杂**: 需要 Apollo Client, Codegen, Schema Stitching
+3. **Overkill**: 当前需求只有 5 个简单 CRUD 端点，REST 足够
+4. **成本**: GraphQL 服务器性能优化成本高（N+1 查询问题）
+
+## Learning
+
+- **YAGNI**: GraphQL 解决的问题（灵活查询、版本管理）当前不存在
+- **下次应该**: 先用 REST，等到真正需要灵活查询时再迁移
+- **决策原则**: 技术选型看当前需求，不为未来需求过度设计
+
+## References
+
+- [Apollo Server 官方文档](https://www.apollographql.com/docs/apollo-server/)
+- [GraphQL N+1 问题分析](https://example.com/graphql-n-plus-1)
+```
+
+---
+
+## 示例 2: 偏移分页改用游标分页
+
+```markdown
+# Attempt: Offset-based Pagination
+
+**Date**: 2026-01-08
+**Context**: 实现用户列表分页，最初选择偏移分页（offset/limit）
+
+## Approach
+
+使用 SQL OFFSET/LIMIT:
+```sql
+SELECT * FROM users
+ORDER BY created_at DESC
+LIMIT 20 OFFSET 40
+```
+
+## Result
+
+⚠️ 部分成功（实现了但性能差）
+
+## Reason
+
+1. **性能问题**: OFFSET 40000 时查询时间 >2 秒（需扫描前 40000 行）
+2. **数据不一致**: 翻页时有新数据插入，导致重复或遗漏
+3. **数据库负载**: 大 OFFSET 导致 CPU 使用率飙升
+
+## Learning
+
+- **游标分页更适合**: 使用 `WHERE id > last_id` 替代 OFFSET
+- **性能对比**: 游标分页查询时间稳定在 50ms，与页数无关
+- **决策**: 对于大数据集，始终用游标分页
+
+## References
+
+- [PostgreSQL OFFSET Performance](https://example.com/postgres-offset)
+- [Cursor-based Pagination Best Practices](https://example.com/cursor-pagination)
+```
+
+---
+
+## 何时记录尝试
+
+| 情况 | 是否记录 |
+|------|---------|
+| 方案调研后决定不采用 | ✅ 记录 |
+| 实现了但发现性能问题，放弃 | ✅ 记录 |
+| 简单方案 A vs B 对比，选 A | ❌ 不记录（在 research.md Decisions 记录即可） |
+| 重大架构决策放弃 | ✅ 记录 |
+| 技术选型放弃 | ✅ 记录 |
+
+---
+
+## 与 ERROR_LOG.md 的区别
+
+| | research/attempts/ | ERROR_LOG.md |
+|--|-------------------|--------------|
+| 阶段 | 研究阶段（Phase 0） | 执行阶段（flow-dev, flow-qa） |
+| 内容 | 方案尝试与放弃 | 代码错误与修复 |
+| 格式 | Markdown 文件 | 结构化错误日志 |
+| 目的 | 避免重复研究 | 避免重复错误 |
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/docs/templates/BRAINSTORM_TEMPLATE.md

@@ -0,0 +1,148 @@
+---
+req_id: "{REQ_ID}"
+title: "{TITLE}"
+created_at: "{ISO8601_TIMESTAMP}"
+brainstorm_version: "1.0"
+status: "draft"
+---
+
+# {REQ_ID} Brainstorm Record
+
+> **[PROTOCOL]**: 后续所有开发必须与本文档保持一致。如有偏离，需更新本文档并说明原因。
+
+## 原始需求（用户原话）
+
+> {用户的原始描述，一字不改，保留所有细节}
+
+## 核心问题定义
+
+### 解决什么问题？
+
+{一句话定义核心问题，例如："用户无法在移动端完成支付"}
+
+### 为谁解决？
+
+{用户画像，例如："日均活跃用户 10,000+，年龄 25-45，移动端为主"}
+
+### 现状痛点
+
+- {痛点1：具体描述，包含数据或用户反馈}
+- {痛点2}
+- {痛点3}
+
+## 成功标准
+
+### 如何判断需求完成？（验收标准）
+
+- [ ] {可度量的标准1，例如："支付成功率 ≥ 95%"}
+- [ ] {可度量的标准2}
+- [ ] {可度量的标准3}
+
+### 如何判断需求成功？（业务指标）
+
+- {业务指标1，例如："订单转化率提升 10%"}
+- {业务指标2}
+
+## 约束条件
+
+| 类型 | 约束 | 原因 |
+|------|------|------|
+| 技术 | {约束，例如："必须兼容 iOS 12+"} | {原因} |
+| 时间 | {约束，例如："2 周内上线"} | {原因} |
+| 资源 | {约束，例如："1 前端 + 1 后端"} | {原因} |
+| 安全 | {约束，例如："敏感数据需加密"} | {原因} |
+| 法规 | {约束，例如："符合 GDPR"} | {原因} |
+
+## 方案探索
+
+### 方案 A: {名称} ⭐ 推荐
+
+**描述**:
+{方案概述，100-200 字}
+
+**优势**:
+- {优势1}
+- {优势2}
+
+**劣势**:
+- {劣势1}
+- {劣势2}
+
+**适用场景**:
+{何时选择这个方案}
+
+**实现要点**:
+1. {关键步骤1}
+2. {关键步骤2}
+
+---
+
+### 方案 B: {名称}
+
+**描述**:
+{方案概述}
+
+**优势**:
+- {优势1}
+
+**劣势**:
+- {劣势1}
+
+**适用场景**:
+{何时选择这个方案}
+
+---
+
+### 方案 C: {名称}
+
+**描述**:
+{方案概述}
+
+**优势**:
+- {优势1}
+
+**劣势**:
+- {劣势1}
+
+**适用场景**:
+{何时选择这个方案}
+
+## 最终决策
+
+**选定方案**: 方案 {X}
+
+**选择理由**:
+{为什么选这个方案，而非其他方案}
+
+**否决理由**:
+- 方案 {Y}: {为什么不选}
+- 方案 {Z}: {为什么不选}
+
+## 关键决策记录
+
+| 决策点 | 决策 | 理由 | 日期 |
+|--------|------|------|------|
+| {问题1} | {选择} | {为什么} | {YYYY-MM-DD} |
+| {问题2} | {选择} | {为什么} | {YYYY-MM-DD} |
+
+## 风险识别
+
+| 风险 | 概率 | 影响 | 缓解策略 |
+|------|------|------|----------|
+| {风险1} | 高/中/低 | 高/中/低 | {应对措施} |
+| {风险2} | 高/中/低 | 高/中/低 | {应对措施} |
+
+## 变更历史
+
+| 版本 | 日期 | 变更内容 | 变更原因 |
+|------|------|----------|----------|
+| 1.0 | {YYYY-MM-DD} | 初始版本 | 头脑风暴完成 |
+
+---
+
+**⚠️ 追溯声明**:
+本文档是 {REQ_ID} 的「北极星」。后续 PRD、EPIC、TASKS、实现都必须与本文档保持一致。
+如发现偏离，必须：
+1. 确认偏离原因
+2. 更新本文档
+3. 记录变更历史

package/.claude/docs/templates/ERROR_LOG_TEMPLATE.md

@@ -0,0 +1,80 @@
+# Error Log: ${REQ_ID}
+
+> 本文件记录需求开发过程中遇到的所有错误及解决方案。
+> **[PROTOCOL]**: 遇到错误时立即追加，不要等到最后。
+
+---
+
+## 错误记录格式
+
+每条错误记录遵循以下结构：
+
+```markdown
+## [TIMESTAMP] E###: TITLE
+
+**Phase**: flow-dev / T### 或 flow-qa / 测试名
+**Error Type**: Test Failure | Build Error | Runtime Error | Type Error | Lint Error
+**Error Message**:
+\`\`\`
+完整错误信息
+\`\`\`
+
+**Root Cause**: 根因分析（解决后填写）
+**Resolution**: 解决方案（解决后填写）
+**Prevention**: 预防措施（可选，防止再犯）
+```
+
+---
+
+## 示例记录
+
+## [2026-01-08T10:30:00] E001: Test Failure - Email Validation
+
+**Phase**: flow-dev / T003
+**Error Type**: Test Failure
+**Error Message**:
+```
+FAIL src/auth/login.test.ts
+  × should validate email format
+    Expected: true
+    Received: false
+
+    at Object.<anonymous> (src/auth/login.test.ts:25:20)
+```
+
+**Root Cause**: 正则表达式未处理 + 号邮箱（如 user+tag@example.com）
+**Resolution**: 更新正则为 `/^[^\s@]+@[^\s@]+\.[^\s@]+$/`
+**Prevention**: 添加 + 号邮箱到测试用例，扩充边界测试
+
+---
+
+## [2026-01-08T11:15:00] E002: Build Error - Missing Import
+
+**Phase**: flow-dev / T005
+**Error Type**: Build Error
+**Error Message**:
+```
+ERROR in src/components/UserProfile.tsx
+Module not found: Can't resolve '@/utils/formatDate'
+```
+
+**Root Cause**: formatDate 函数移动到 @/utils/date 但未更新 import
+**Resolution**: 更新 import 路径为 `@/utils/date`
+**Prevention**: 使用 IDE 重构功能移动文件，自动更新引用
+
+---
+
+## 统计信息
+
+| 指标 | 值 |
+|------|-----|
+| 总错误数 | 0 |
+| 已解决 | 0 |
+| 待解决 | 0 |
+| 最常见类型 | - |
+
+> 注：此统计在开发结束时手动更新
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/docs/templates/INIT_FLOW_TEMPLATE.md

@@ -36,6 +36,9 @@ scripts:
 ```bash
 # 1. 解析参数
 REQ_ID|TITLE|PLAN_URLS → 验证 REQ_ID 格式: ^(REQ|BUG)-[0-9]+$
+→ 若 TITLE 含中文/非ASCII，使用模型意译生成 BRANCH_TITLE_EN（英文语义翻译，禁止拼音/音译）
+→ BRANCH_TITLE_EN 仅用于分支名，文档标题仍使用原始 TITLE
+→ 若意译不确定或未生成 ASCII 结果，向用户确认英文分支标题
 
 # 2. 前置条件检查
 bash {SCRIPT:prereq} --json --paths-only
@@ -47,6 +50,19 @@ bash {SCRIPT:prereq} --json --paths-only
 
 ---
 
+## Stage 1.2: Git Branch Creation
+
+```bash
+# 创建功能分支
+Requirements: feature/${REQ_ID}-${slug(BRANCH_TITLE_EN)}
+Bug Fixes:    bugfix/${BUG_ID}-${slug(BRANCH_TITLE_EN)}
+
+# BRANCH_TITLE_EN = TITLE 的英文意译 (语义为准，非拼音，使用模型意译)
+# slug() = lowercase, replace spaces/special chars with hyphens
+```
+
+---
+
 ## Stage 1.5: Context Loading (路线图与架构)
 
 **目标**: 理解需求在项目中的位置
@@ -63,7 +79,9 @@ bash {SCRIPT:prereq} --json --paths-only
 
 ```bash
 # 创建需求目录
-bash {SCRIPT:create} "${REQ_ID}" --title "${TITLE}" --json
+bash {SCRIPT:create} "${REQ_ID}" --title "${TITLE}" --branch-title "${BRANCH_TITLE_EN}" --json
+
+→ 若未生成 BRANCH_TITLE_EN，则省略 --branch-title
 
 # 生成文件
 devflow/requirements/${REQ_ID}/
@@ -127,19 +145,9 @@ orchestration_status.json.phase0_complete = true
 
 ---
 
-## Stage 3: Git Branch Creation
-
-```bash
-# 创建功能分支
-Requirements: feature/${REQ_ID}-${slug(title)}
-Bug Fixes:    bugfix/${BUG_ID}-${slug(title)}
-
-# slug() = lowercase, replace spaces/special chars with hyphens
-```
 
----
 
-## Stage 4: README Generation
+## Stage 3: README Generation
 
 ```bash
 # 生成工作流指南
@@ -149,7 +157,7 @@ Bug Fixes:    bugfix/${BUG_ID}-${slug(title)}
 
 ---
 
-## Stage 5: Exit Gate (5-Level Quality Check)
+## Stage 4: Exit Gate (5-Level Quality Check)
 
 ### Level 1: File Existence Check
 ```bash
@@ -204,7 +212,7 @@ devflow/requirements/${REQ_ID}/
 ```
 
 **Git**:
-- Branch: `feature/${REQ_ID}-${slug(title)}`
+- Branch: `feature/${REQ_ID}-${slug(BRANCH_TITLE_EN)}`
 - Status: orchestration_status.json.status = "initialized"
 - Phase: orchestration_status.json.phase = "planning"