🚀 cc-devflow

Claude Code 一键需求开发流系统

基于 Claude Code 官方子代理、钩子和设置机制构建的完整开发工作流系统。通过单一命令将需求从规划转变为代码交付。

中文文档 | English

🎯 一句话介绍

通过 /flow-new "REQ-123|功能|URLs" 一键从 PRD 生成到代码交付的完整自动化工作流。

✨ 核心特性

• 🎯 一键启动流程 - 单命令完成 PRD → 代码 → 测试 → 发布全流程
• 🔄 阶段化命令 - 8个独立阶段命令，精细化控制每个开发环节
• 📋 文档驱动 - 自动化 PRD → UI原型 → EPIC → TASKS → 实现链条
• 📝 模板驱动 - 自执行模板（PRD_TEMPLATE, EPIC_TEMPLATE, TASKS_TEMPLATE）
• 🔄 智能恢复 - /flow-restart 自动检测重启点，继续中断的开发
• 🛡️ 质量闸 - 自动化 TypeScript 检查、测试、代码检查和安全扫描
• 🤖 子代理编排 - 12 个专业研究型代理负责不同开发阶段
• 🎨 UI原型生成 - 条件触发的HTML原型，融合艺术设计灵感
• 🔗 GitHub 集成 - 自动化 PR 创建、分支管理和规范化提交
• 📊 进度跟踪 - 实时状态监控和智能重启点
• 🔍 一致性验证 - 企业级一致性检查，智能冲突检测
• 🧪 TDD 强制执行 - 严格的测试驱动开发，TEST VERIFICATION CHECKPOINT
• 📜 Constitution - 10条宪法条款管控质量、安全和架构
• 🔄 自主开发 - Ralph × Manus 集成实现有记忆的持续迭代
• 🔌 多平台支持 - 通过 npm run adapt 编译工作流到 Codex、Cursor、Qwen、Antigravity

💡 核心概念

Hooks 系统

实时质量守护，PreToolUse 阻止不合规操作，PostToolUse 自动记录变更。

Hook 类型:

| Hook | 触发时机 | 功能 | |------|---------|------| | UserPromptSubmit | 用户输入提交时 | 智能推荐相关 Skills | | PreToolUse | 工具使用前 | 阻止不合规操作（TDD 违规等） | | PostToolUse | 工具使用后 | 自动记录文件变更 | | Stop | 会话停止时 | 提供错误处理提示 |

Guardrail 工作流程:

用户编辑文件 → PreToolUse Hook 触发
  ↓ 路径归一化
  ↓ 规则匹配
  ↓ 内容检查
  ↓ 违规？阻止操作 : 允许操作

跳过 Guardrail:

# 方式 1: 文件标记
echo "@skip-tdd-check" >> devflow/requirements/REQ-123/TASKS.md

# 方式 2: 环境变量
export SKIP_TDD_ENFORCER=1

📚 完整 Hooks 文档

Skills 系统

智能知识库激活，自动推荐相关领域知识。

可用 Skills:

| Skill | 类型 | 触发场景 | |-------|------|----------| | cc-devflow-orchestrator | domain | 需求管理、流程指导 | | devflow-tdd-enforcer | guardrail | 编辑 TASKS.md | | constitution-guardian | guardrail | 编辑 PRD/EPIC/TASKS | | devflow-file-standards | domain | 文件命名、目录结构 | | skill-developer | domain | Skill 开发、Hook 系统 |

触发机制:

1. 关键词触发 - 输入包含特定关键词
2. 意图匹配 - 正则匹配用户意图
3. 文件触发 - 编辑特定路径文件
4. 内容匹配 - 文件内容匹配特定模式

📚 完整 Skills 文档

Agent Orchestration

研究型代理（11个，只读分析）+ 主代理（执行）的双层执行模型。

执行模型:

• 研究型代理: 只读分析，生成 Markdown 计划和报告
• 主代理 (Claude): 执行所有代码操作，拥有完整上下文
• 工作流程: 代理研究 → 输出计划 → 主代理执行 → 迭代

工具分配:

• 研究型代理: Read, Grep, Glob（分析）
• 主代理: Edit, Write, Bash, Git（执行）

📚 执行模型详解

🚀 快速开始

安装

方式 1: 从 npm 安装（推荐）

# 全局安装
npm install -g cc-devflow
# 或
pnpm add -g cc-devflow

# 在项目中初始化
cc-devflow init

# 编译到特定平台（可选）
cc-devflow adapt --platform cursor
cc-devflow adapt --platform codex
cc-devflow adapt --platform antigravity
cc-devflow adapt --platform qwen

方式 2: 手动安装

pnpm dlx tiged Dimon94/cc-devflow/.claude .claude

更新指南 (Update)

更新到最新版本并同步本地项目：

# 全局更新
npm install -g cc-devflow@latest

# 更新本地项目文件（将覆盖冲突文件）
cc-devflow init

CLI 使用

# 在当前目录初始化
cc-devflow init

# 在指定目录初始化
cc-devflow init --dir /path/to/project

# 编译到特定平台
cc-devflow adapt --platform codex
cc-devflow adapt --cwd /path/to/project --platform cursor

验证安装

.claude/scripts/verify-setup.sh

第一个需求

/flow-new "REQ-001|用户认证|https://docs.example.com/auth"

交互式演示:

python3 .claude/scripts/demo.py

核心脚本:

# 环境检查
bash .claude/scripts/check-prerequisites.sh

# 查看任务状态
bash .claude/scripts/check-task-status.sh --verbose

# 标记任务完成
bash .claude/scripts/mark-task-complete.sh T001

# 生成状态报告
bash .claude/scripts/generate-status-report.sh --format markdown

运行测试:

# 运行所有测试
bash .claude/tests/run-all-tests.sh --scripts

# Constitution 测试
bash .claude/tests/constitution/run_all_constitution_tests.sh

📚 完整入门指南

📋 命令速查表

🏢 项目级命令（Project-Level）

用途: 项目整体规划和架构设计，通常在项目初期执行一次

| 命令 | 用途 | 快速示例 | 详细文档 | |------|------|----------|----------| | /core-roadmap | 🗺️ 生成产品路线图 | /core-roadmap | → | | /core-architecture | 🏗️ 生成系统架构 | /core-architecture | → | | /core-guidelines | 📘 生成项目规范 | /core-guidelines | → | | /core-style | 🎨 生成设计风格指南 | /core-style | → |

📦 需求级命令（Requirement-Level）

用途: 具体需求开发，每个需求（REQ-XXX）执行一次

| 命令 | 用途 | 快速示例 | 详细文档 | |------|------|----------|----------| | /flow-new | 🎯 启动新需求 | /flow-new "REQ-123\|功能" | → | | /flow-init | 📦 初始化需求 | /flow-init "REQ-123\|功能" | → | | /flow-clarify | 🔎 澄清歧义 | /flow-clarify "REQ-123" | → | | /flow-checklist | ✅ 需求质量检查 | /flow-checklist --type ux | → | | /flow-verify | 🔍 验证一致性 | /flow-verify "REQ-123" | → | | /flow-qa | 🧪 质量保证 | /flow-qa "REQ-123" | → | | /flow-release | 🚢 创建发布 | /flow-release "REQ-123" | → |

📚 完整命令参考

你的场景：
├─ 规划产品方向？ → /core-roadmap
├─ 设计系统架构？ → /core-architecture
├─ 建立编码规范？ → /core-guidelines
├─ 建立设计风格指南？ → /core-style
├─ 启动全新功能开发？ → /flow-new "REQ-123|功能|URLs"
├─ 仅创建需求目录？ → /flow-init "REQ-123|功能"
├─ 澄清模糊需求？ → /flow-clarify "REQ-123"
├─ 验证需求质量？ → /flow-checklist --type ux,api,security
├─ 开发中断需要继续？ → /flow-restart "REQ-123"
├─ 检查开发进度？ → /flow-status REQ-123
├─ 发现文档不一致？ → /flow-verify "REQ-123"
├─ 开发完成需要测试？ → /flow-qa "REQ-123"
├─ 修复生产 Bug？ → /flow-fix "BUG-001|描述"
└─ 准备发布？ → /flow-release "REQ-123"

🔄 工作流程图

以下 Mermaid 流程图展示了完整的 cc-devflow 工作流，包括项目级和需求级两个层面的流程：

graph TB
    Start([项目启动]) --> ProjectLevel{项目级初始化}
    
    ProjectLevel --> CoreRoadmap["/core-roadmap<br/>ROADMAP.md & BACKLOG.md"]
    ProjectLevel --> CoreArch["/core-architecture<br/>ARCHITECTURE.md"]
    ProjectLevel --> CoreGuidelines["/core-guidelines<br/>前端/后端规范"]
    ProjectLevel --> CoreStyle["/core-style<br/>STYLE.md"]
    
    CoreRoadmap --> ReqLevel
    CoreArch --> ReqLevel
    CoreGuidelines --> ReqLevel
    CoreStyle --> ReqLevel
    
    ReqLevel([需求级开发流程]) --> FlowInit["/flow-init<br/>research.md & tasks.json"]
    
    FlowInit --> FlowClarify["/flow-clarify<br/>clarifications/*.md<br/>可选"]
    FlowClarify --> FlowPRD["/flow-prd<br/>PRD.md"]
    FlowInit -.->|跳过澄清| FlowPRD
    FlowPRD --> FlowChecklist["/flow-checklist<br/>checklists/*.md<br/>80%门禁"]
    FlowPRD --> FlowTech["/flow-tech<br/>TECH_DESIGN.md & 数据模型"]
    FlowPRD --> FlowUI["/flow-ui<br/>UI_PROTOTYPE.html<br/>可选"]

    FlowChecklist --> FlowEpic
    FlowTech --> FlowEpic["/flow-epic<br/>EPIC.md & TASKS.md"]
    FlowUI --> FlowEpic
    
    FlowEpic --> FlowDev["/flow-dev<br/>TASKS.md 执行<br/>TDD 强制"]
    
    FlowDev --> FlowQA["/flow-qa<br/>QA 报告 & 安全审查"]
    
    FlowQA --> FlowRelease["/flow-release<br/>PR 创建 & 部署"]
    
    FlowRelease --> FlowVerify["/flow-verify<br/>一致性检查"]
    
    FlowVerify --> End([发布完成])
    
    FlowVerify -.->|可在任意阶段调用| ReqLevel
    
    style ProjectLevel fill:#e1f5ff
    style ReqLevel fill:#fff4e1
    style FlowInit fill:#e8f5e9
    style FlowClarify fill:#fff9c4
    style FlowPRD fill:#e8f5e9
    style FlowChecklist fill:#ffe0b2
    style FlowTech fill:#e8f5e9
    style FlowUI fill:#fff9c4
    style FlowEpic fill:#e8f5e9
    style FlowDev fill:#f3e5f5
    style FlowQA fill:#fce4ec
    style FlowRelease fill:#e0f2f1
    style FlowVerify fill:#e3f2fd

流程说明:

• 项目级命令（浅蓝色）：项目初始化时执行一次，建立全局标准（SSOT）
• 需求级命令（浅橙色）：每个需求（REQ-XXX）执行一次
• 可选步骤（黄色）：/flow-clarify 和 /flow-ui 为可选步骤
• 质量门禁（橙色）：/flow-checklist 在 /flow-epic 前验证需求质量，80% 完成度阈值
• 质量闸门：每个阶段都有入口/出口闸门，确保文档质量和 Constitution 合规性
• TDD 强制执行：/flow-dev 严格强制执行测试驱动开发顺序
• 一致性检查：/flow-verify 可在任意阶段调用，确保文档一致性

🏗️ 系统架构

执行模型: 研究型代理（11个，只读）+ 主代理（执行） 文档结构: 单轨架构，一个需求目录包含所有产物 质量保证: Constitution v2.0.0 + TDD 强制执行 + 实时 Guardrail

子代理工作流

clarify-analyst     → 澄清问题（11 维度歧义扫描）
prd-writer          → PRD 生成（必须使用 PRD_TEMPLATE）
checklist-agent     → 需求质量验证（5 维度，6 类型）⭐ 新增
ui-designer         → UI 原型（条件触发）
tech-architect      → 技术设计（Anti-Tech-Creep 强制执行）
planner             → EPIC & TASKS（必须使用 EPIC_TEMPLATE, TASKS_TEMPLATE）
dev-implementer     → 实现计划（仅研究）
qa-tester           → 测试计划 + 测试报告
security-reviewer   → 安全计划 + 安全报告
release-manager     → 发布计划

单轨架构

devflow/
├── ROADMAP.md               # 产品路线图
├── ARCHITECTURE.md          # 系统架构设计
├── BACKLOG.md               # 需求待办列表
└── requirements/REQ-123/
    ├── PRD.md
    ├── EPIC.md
    ├── TASKS.md
    ├── EXECUTION_LOG.md
    ├── checklists/          # 需求质量检查清单
    │   ├── ux.md
    │   ├── api.md
    │   └── security.md
    ├── TEST_PLAN.md
    ├── TEST_REPORT.md
    ├── SECURITY_PLAN.md
    ├── SECURITY_REPORT.md
    └── RELEASE_PLAN.md

质量闸

• Pre-push Guard（TypeScript、测试、代码检查、安全、构建）
• Checklist Gate（/flow-checklist 80% 完成度阈值，在 /flow-epic 前执行）
• Constitution Compliance（每个阶段强制执行）
• TDD Checkpoint（TEST VERIFICATION CHECKPOINT）
• Guardrail Hooks（PreToolUse 实时阻止不合规操作）

📚 完整架构文档

⚙️ 配置

最小配置 (.claude/settings.json):

{
  "permissions": {
    "allowGitOperations": true,
    "allowNetworkRequests": true,
    "allowSubprocesses": true
  }
}

Hooks 配置

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{"type": "command", "command": "..."}]
    }]
  }
}

环境变量

# 流程行为
export FLOW_AUTO_APPROVE=false
export MIN_TEST_COVERAGE=80
export STRICT_TYPE_CHECKING=true

# Guardrail 跳过
export SKIP_TDD_ENFORCER=1
export SKIP_CONSTITUTION_CHECK=1

📚 完整配置指南

🧪 测试覆盖

脚本测试: 8/8 通过 ✅ (100%) Constitution 测试: 38/38 通过 ✅ (100%)

# 运行所有测试
bash .claude/tests/run-all-tests.sh --scripts

测试套件

| 测试套件 | 测试用例数 | 状态 | |----------|-----------|------| | test_check_prerequisites | 18 | ✅ 100% | | test_check_task_status | 18 | ✅ 100% | | test_common | 15 | ✅ 100% | | test_mark_task_complete | 15 | ✅ 100% | | test_setup_epic | 13 | ✅ 100% | | test_validate_constitution | 4 | ✅ 100% |

📚 测试框架详解

📝 版本历史

v2.3.0 (2026-01-08) - 最新版本

🛡️ 纪律系统：铁律 + 合理化防御 + 压力测试

v2.3.0 将 Constitution 从"文档"升级为"可执行纪律系统"，借鉴 superpowers 项目最佳实践：

• 铁律 + 合理化表格 - 预先阻止 AI Agent 合理化尝试

  • 10 条 Constitution 条款现在都有铁律（绝对禁止）
  • 合理化表格采用 | 借口 | 现实 | 格式
  • 红旗标志用于 AI 自检触发
  • 集中式 rationalization-library.md 存储所有合理化

• 两阶段代码审查 - /flow-review 命令（新增）

  • 阶段 1：规格合规性（不信任实现者报告，直接读代码）
  • 阶段 2：代码质量（仅在阶段 1 通过后运行）
  • spec-reviewer.md 和 code-quality-reviewer.md 代理

• 完成前验证 - 断言前先有证据

  • verification-before-completion 技能
  • verify-gate.sh 脚本用于所有流程出口闸门
  • 没有新鲜验证证据不得声称完成

• 系统化调试 - /flow-fix 增强 4 阶段调试

  • 阶段 1：根因调查（尚未修复）
  • 阶段 2：模式分析
  • 阶段 3：假设和测试
  • 阶段 4：TDD 实现
  • flow-debugging 和 flow-tdd 技能

• 头脑风暴集成 - /flow-init 现在包含头脑风暴

  • BRAINSTORM.md 作为需求"北极星"
  • /flow-prd 需要 BRAINSTORM 对齐检查
  • flow-brainstorming 技能

• 压力测试框架 - 技能的 TDD

  • tests/pressure-scenarios/ 包含 4 个场景
  • 测试 AI 在时间/沉没成本/权威/疲劳压力下的行为
  • run-pressure-tests.sh 运行器

• 技能融合 - Superpowers 技能迁移到本地

  • flow-tdd、flow-debugging、flow-receiving-review、flow-finishing-branch
  • 所有 superpowers:xxx 引用替换为本地技能

• Ralph × Manus 集成 - 有记忆的自主开发（新增）

  • 合并入 /flow-dev (默认自主模式)
  • flow-attention-refresh 技能提供 4 个刷新协议
  • ERROR_LOG.md 结构化错误追踪
  • research/attempts/ 失败痕迹记录
  • Stop Hook 实现自引用循环
  • /flow-init Stage 2.5 融入 Manus 研究方法
  • 目标：无人工干预任务完成率 ≥85%

📋 Constitution v2.1.0:

• 所有 10 条条款现在都有铁律 + 合理化防御 + 红旗标志
• 交叉引用到 rationalization-library.md

📁 新增文件:

• .claude/commands/cancel-ralph.md - 取消 Ralph 循环命令
• .claude/skills/flow-attention-refresh/SKILL.md - 4 个注意力刷新协议
• .claude/hooks/ralph-stop-hook.sh - 自引用循环 Stop Hook
• .claude/hooks/hooks.json - Hook 注册配置
• .claude/scripts/setup-ralph-loop.sh - Ralph 状态初始化脚本
• .claude/docs/templates/ERROR_LOG_TEMPLATE.md - 执行错误日志格式
• .claude/docs/templates/ATTEMPT_TEMPLATE.md - 研究尝试日志格式
• .claude/agents/spec-reviewer.md - 阶段 1 规格合规性审查员
• .claude/agents/code-quality-reviewer.md - 阶段 2 代码质量审查员
• .claude/commands/flow-review.md - 两阶段审查命令
• .claude/rules/rationalization-library.md - 集中式合理化防御
• .claude/scripts/verify-gate.sh - 出口闸门验证脚本
• .claude/skills/flow-brainstorming/ - 头脑风暴技能
• .claude/skills/flow-debugging/ - 系统化调试技能
• .claude/skills/flow-tdd/ - TDD 强制执行技能
• .claude/skills/flow-receiving-review/ - 审查反馈处理技能
• .claude/skills/flow-finishing-branch/ - 分支完成决策技能
• .claude/skills/verification-before-completion/ - 完成验证技能
• tests/ - 压力测试框架

v2.2.0 (2025-12-19)

🔌 多平台适配：Agent 适配器架构 + 命令编译器

v2.2.0 引入全面的多平台支持，让 cc-devflow 工作流能在多个 AI 编码助手上运行：

• Agent 适配器架构 (REQ-004) - 平台差异的可插拔适配层

  • 统一的 Agent Adapter 抽象（环境探测、命令执行、能力声明）
  • Adapter Registry 支持自动检测和显式覆盖
  • 内置适配器：Claude Code（默认）、Codex CLI、Cursor、Qwen、Antigravity
  • 安全优先设计：能力白名单，高风险操作默认禁用
  • 结构化日志便于调试和审计

• 命令编译器 (REQ-005) - 单一真相源编译

  • .claude/ 作为 SSOT，编译为平台原生格式
  • npm run adapt CLI 多平台编译
  • 支持平台：Codex (.codex/)、Cursor (.cursor/)、Qwen (.qwen/)、Antigravity (.agent/)
  • 占位符展开：{SCRIPT:*}、{TEMPLATE:*}、{GUIDE:*}、{AGENT_SCRIPT}、$ARGUMENTS
  • 模板/指南内联，自动嵌入引用内容
  • 资源复制与路径重写（脚本、模板、指南 → 平台目录）
  • 基于 Manifest 的增量编译和漂移检测

• 适配器编译器 (REQ-006) - 多平台规则入口文件生成

  • 4 个平台专用规则 Emitters（Cursor MDC、Codex SKILL.md、Qwen TOML、Antigravity 12K 智能分块）
  • 技能注册表编译（合并 skill-rules.json + skill.md 元数据）
  • Manifest v2.0 扩展，支持 skills 和 rulesEntry 追踪
  • --rules 和 --skills CLI 选项实现选择性编译
  • Bug 修复：默认关闭模板内联（保持路径引用而非内联展开）
  • 173 个测试，新模块覆盖率 87%

📦 新 CLI 工具:

npm run adapt                        # 编译到所有平台
npm run adapt -- --platform codex    # 编译到指定平台
npm run adapt -- --check             # 检查漂移（不编译）
npm run adapt -- --verbose           # 显示详细输出

v2.1.0 (2025-11-07)

🏢 核心突破：引入项目级命令（Project-Level Commands）

v2.1.0 的核心突破是引入了项目级命令，与之前的需求级命令形成两层体系：

• 项目级命令 - 项目整体规划和架构设计（项目初期执行一次）

  • /core-roadmap - 交互式产品路线图生成（6阶段对话）
  • /core-architecture - 4种架构图生成（Mermaid格式）
  • /core-guidelines - 项目规范生成（前端/后端分离）
  • /core-style - 项目设计风格指南生成（视觉一致性SSOT）

• 需求级命令增强 - Stage 1.5 路线图与架构上下文加载（flow-init）

  • 初始化需求时自动加载项目级上下文
  • 需求与路线图自动映射（RM-ID, Milestone, Quarter）
  • 架构上下文自动关联（Feature Layer, Tech Stack, Module）

📚 文档改进:

• README 完全重构（完整目录 + 折叠 + 外部文档链接）
• 新增 25+ 个详细文档

📋 完整变更日志

🤝 贡献 & 支持

贡献: 贡献指南 问题: GitHub Issues 文档: 完整文档

📄 许可证

MIT License - 查看 LICENSE 文件

🌟 如果 cc-devflow 帮助简化了您的开发工作流，请为此仓库点星！