mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-06 01:54:11 +08:00
8dc7abf707
Added eye-catching links to the beginner-friendly Getting Started guides at the top of both README files, right after the version announcement. This helps new users quickly discover the 5-minute tutorial. Changes: - README.md: Added link to GETTING_STARTED.md - README_CN.md: Added link to GETTING_STARTED_CN.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1010 lines
36 KiB
Markdown
1010 lines
36 KiB
Markdown
# 🚀 Claude Code Workflow (CCW)
|
||
|
||
<div align="center">
|
||
|
||
[](https://github.com/catlog22/Claude-Code-Workflow/releases)
|
||
[](LICENSE)
|
||
[]()
|
||
[](https://github.com/modelcontextprotocol)
|
||
|
||
**语言:** [English](README.md) | [中文](README_CN.md)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
**Claude Code Workflow (CCW)** 将 AI 开发从简单提示词链接转变为强大的上下文优先编排系统。通过结构化规划、确定性执行和智能多模型编排，解决执行不确定性和误差累积问题。
|
||
|
||
> **🎉 最新版本: v4.4.0** - UI 设计工作流 V3 布局/样式分离架构。详见 [CHANGELOG.md](CHANGELOG.md)。
|
||
>
|
||
> **v4.4.0 版本新特性**:
|
||
> - 🏗️ **布局/样式分离**: 新的 `layout-extract` 命令将结构与视觉令牌分离
|
||
> - 📦 **纯汇编器**: `generate` 命令现在纯粹组合预提取的布局 + 样式
|
||
> - 🎯 **更好的多样性**: 布局探索生成结构上不同的设计
|
||
> - ✅ **单一职责**: 每个阶段（样式、布局、汇编）都有明确的目的
|
||
|
||
---
|
||
|
||
> 📚 **第一次使用 CCW？** 查看 [**快速上手指南**](GETTING_STARTED_CN.md) 获取新手友好的 5 分钟教程！
|
||
|
||
---
|
||
|
||
## ✨ 核心差异化特性
|
||
|
||
#### **1. 上下文优先架构** 🎯
|
||
通过 `context-package.json` 和 `flow_control.pre_analysis` 预定义上下文收集，消除执行不确定性。智能体在实现**前**加载正确上下文，解决"1到N"开发漂移问题。
|
||
|
||
#### **2. JSON 优先状态管理** 📋
|
||
任务状态存于 `.task/IMPL-*.json`（单一事实来源），Markdown 为只读视图。数据与表现分离，实现程序化编排无状态漂移。
|
||
|
||
#### **3. 自主多阶段编排** 🔄
|
||
`/workflow:plan` 等命令链接专用子命令（会话 → 上下文 → 分析 → 任务），零用户干预。`flow_control` 机制创建带步骤依赖的可执行"程序"。
|
||
|
||
#### **4. 多模型战略编排** 🧠
|
||
- **Gemini/Qwen**：分析、探索、文档（大上下文）
|
||
- **Codex**：实现、自主执行（`resume --last` 保持上下文）
|
||
- **结果**：比单模型方法任务处理提升 5-10 倍
|
||
|
||
#### **5. 分层内存系统** 🧬
|
||
4 层文档（根 → 领域 → 模块 → 子模块）在适当抽象级别提供上下文，防止信息过载并保持精确性。
|
||
|
||
#### **6. 专用基于角色的智能体** 🤖
|
||
专用智能体镜像真实软件团队：`@action-planning-agent`、`@code-developer`、`@test-fix-agent`、`@ui-design-agent`。包含 TDD 工作流（Red-Green-Refactor）、UI 设计（布局/样式分离）和自动 QA。
|
||
|
||
---
|
||
|
||
### **其他特性**
|
||
|
||
- **✅ 执行前验证**：质量关卡（`/workflow:concept-clarify`、`/workflow:action-plan-verify`）
|
||
- **🔧 统一 CLI**：`/cli:*` 命令支持多工具（`--tool gemini|qwen|codex`）
|
||
- **📦 智能上下文包**：链接任务到相关代码和外部示例
|
||
- **🎨 UI 设计工作流**：Claude 原生样式/布局提取，零依赖
|
||
- **🔄 渐进式增强**：可选工具扩展能力，纯 Claude 模式开箱即用
|
||
|
||
---
|
||
|
||
## ⚙️ 安装
|
||
|
||
### **🚀 一键快速安装**
|
||
|
||
**Windows (PowerShell):**
|
||
```powershell
|
||
Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content
|
||
```
|
||
|
||
**Linux/macOS (Bash/Zsh):**
|
||
```bash
|
||
bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
|
||
```
|
||
|
||
### **📋 交互式版本选择**
|
||
|
||
运行安装命令后，您将看到包含实时版本信息的交互式菜单：
|
||
|
||
```
|
||
正在检测最新版本和提交...
|
||
最新稳定版: v3.2.0 (2025-10-02 04:27 UTC)
|
||
最新提交: cdea58f (2025-10-02 08:15 UTC)
|
||
|
||
====================================================
|
||
版本选择菜单
|
||
====================================================
|
||
|
||
1) 最新稳定版（推荐）
|
||
|-- 版本: v3.2.0
|
||
|-- 发布时间: 2025-10-02 04:27 UTC
|
||
\-- 生产就绪
|
||
|
||
2) 最新开发版
|
||
|-- 分支: main
|
||
|-- 提交: cdea58f
|
||
|-- 更新时间: 2025-10-02 08:15 UTC
|
||
|-- 最新功能
|
||
\-- 可能包含实验性更改
|
||
|
||
3) 指定版本
|
||
|-- 安装特定标签版本
|
||
\-- 最近版本: v3.2.0, v3.1.0, v3.0.1
|
||
|
||
====================================================
|
||
|
||
选择要安装的版本 (1-3, 默认: 1):
|
||
```
|
||
|
||
**版本选项：**
|
||
- **选项 1（推荐）**：经过验证的最新稳定版本，生产环境可用
|
||
- **选项 2**：来自 main 分支的最新开发版本，包含最新功能
|
||
- **选项 3**：指定版本标签，用于受控部署
|
||
|
||
> 💡 **提示**：安装程序会自动从 GitHub 检测并显示最新的版本号和发布日期。只需按 Enter 键即可选择推荐的稳定版本。
|
||
|
||
### **📦 本地安装 (Install-Claude.ps1)**
|
||
|
||
无需网络访问时，使用内置的 PowerShell 安装脚本：
|
||
|
||
**安装模式：**
|
||
```powershell
|
||
# 交互式安装（推荐）
|
||
.\Install-Claude.ps1
|
||
|
||
# 快速安装（自动备份）
|
||
.\Install-Claude.ps1 -Force -BackupAll
|
||
|
||
# 非交互式安装
|
||
.\Install-Claude.ps1 -NonInteractive -Force
|
||
```
|
||
|
||
**安装选项：**
|
||
|
||
| 模式 | 描述 | 安装位置 |
|
||
|------|------|----------|
|
||
| **Global** | 系统级安装（默认） | `~/.claude/`、`~/.codex/`、`~/.gemini/` |
|
||
| **Path** | 自定义目录 + 全局混合 | 本地：`agents/`、`commands/`<br>全局：`workflows/`、`scripts/` |
|
||
|
||
**备份行为：**
|
||
- **默认**：自动备份启用（`-BackupAll`）
|
||
- **禁用**：使用 `-NoBackup` 标志（⚠️ 无备份覆盖）
|
||
- **备份位置**：安装目录中的 `claude-backup-{timestamp}/`
|
||
|
||
**⚠️ 重要警告：**
|
||
- `-Force -BackupAll`：静默文件覆盖（带备份）
|
||
- `-NoBackup -Force`：永久文件覆盖（无法恢复）
|
||
- Global 模式会修改用户配置目录
|
||
|
||
### **✅ 验证安装**
|
||
安装后，运行以下命令以确保 CCW 正常工作：
|
||
```bash
|
||
/workflow:session:list
|
||
```
|
||
|
||
> **📝 安装说明：**
|
||
> - 安装程序将自动安装/更新 `.codex/` 和 `.gemini/` 目录
|
||
> - **全局模式**：安装到 `~/.codex` 和 `~/.gemini`
|
||
> - **路径模式**：安装到指定目录（例如 `project/.codex`、`project/.gemini`）
|
||
> - **备份**：默认自动备份现有文件到 `claude-backup-{timestamp}/`
|
||
> - **安全**：首次安装建议使用交互式模式以审查更改
|
||
|
||
---
|
||
|
||
## ⚙️ 配置
|
||
|
||
### **工具控制系统**
|
||
|
||
CCW 使用**基于配置的工具控制系统**，使外部 CLI 工具成为**可选项**而非必需项。这允许您：
|
||
|
||
- ✅ **从纯 Claude 模式开始** - 无需安装额外工具即可立即开始工作
|
||
- ✅ **渐进式增强** - 根据需要选择性地添加外部工具
|
||
- ✅ **优雅降级** - 工具不可用时自动回退
|
||
- ✅ **灵活配置** - 按项目控制工具可用性
|
||
|
||
**配置文件**: `~/.claude/workflows/tool-control.yaml`
|
||
|
||
```yaml
|
||
tools:
|
||
gemini:
|
||
enabled: false # 可选：AI 分析与文档生成
|
||
qwen:
|
||
enabled: true # 可选：AI 架构与代码生成
|
||
codex:
|
||
enabled: true # 可选：AI 开发与实现
|
||
```
|
||
|
||
**行为**:
|
||
- **禁用时**: CCW 自动回退到其他已启用工具或 Claude 的原生能力
|
||
- **启用时**: 使用专用工具发挥各自优势
|
||
- **默认**: 所有工具禁用 - 纯 Claude 模式开箱即用
|
||
|
||
### **可选 CLI 工具** *(增强功能)*
|
||
|
||
虽然 CCW 仅使用 Claude 即可工作，但安装这些工具可提供增强的分析和扩展上下文：
|
||
|
||
#### **外部 CLI 工具**
|
||
|
||
| 工具 | 用途 | 安装方式 | 优势 |
|
||
|------|------|----------|------|
|
||
| **Gemini CLI** | AI 分析与文档生成 | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) | 免费配额，复杂项目的扩展上下文 |
|
||
| **Codex CLI** | AI 开发与实现 | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) | 自主开发，数学推理 |
|
||
| **Qwen Code** | AI 架构与代码生成 | `npm install -g @qwen-code/qwen-code` ([文档](https://github.com/QwenLM/qwen-code)) | 大上下文窗口，架构分析 |
|
||
|
||
#### **系统实用工具**
|
||
|
||
| 工具 | 用途 | 安装方式 |
|
||
|------|------|----------|
|
||
| **ripgrep (rg)** | 快速代码搜索 | [下载](https://github.com/BurntSushi/ripgrep/releases) 或 `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) |
|
||
| **jq** | JSON 处理 | [下载](https://jqlang.github.io/jq/download/) 或 `brew install jq` (macOS), `apt install jq` (Ubuntu) |
|
||
|
||
**快速安装（所有工具）：**
|
||
|
||
```bash
|
||
# macOS
|
||
brew install ripgrep jq
|
||
npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
|
||
|
||
# Ubuntu/Debian
|
||
sudo apt install ripgrep jq
|
||
npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
|
||
|
||
# Windows (Chocolatey)
|
||
choco install ripgrep jq
|
||
npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
|
||
```
|
||
|
||
### **必需: Gemini CLI 设置**
|
||
|
||
配置 Gemini CLI 以实现最佳集成：
|
||
|
||
```json
|
||
// ~/.gemini/settings.json
|
||
{
|
||
"contextFileName": ["CLAUDE.md", "GEMINI.md"]
|
||
}
|
||
```
|
||
|
||
### **推荐: .geminiignore**
|
||
|
||
通过排除不必要的文件来优化性能：
|
||
|
||
```bash
|
||
# .geminiignore (在项目根目录)
|
||
/dist/
|
||
/build/
|
||
/node_modules/
|
||
/.next/
|
||
*.tmp
|
||
*.log
|
||
/temp/
|
||
|
||
# 包含重要文档
|
||
!README.md
|
||
!**/CLAUDE.md
|
||
```
|
||
|
||
### **推荐: MCP 工具** *(增强分析)*
|
||
|
||
MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装** - 虽然 CCW 具有回退机制，但不安装 MCP 工具可能会导致某些工作流出现意外行为或性能下降。
|
||
|
||
#### 可用的 MCP 服务器
|
||
|
||
| MCP 服务器 | 用途 | 安装指南 |
|
||
|------------|------|---------|
|
||
| **Exa MCP** | 外部 API 模式和最佳实践 | [安装指南](https://smithery.ai/server/exa) |
|
||
| **Code Index MCP** | 高级内部代码搜索 | [安装指南](https://github.com/johnhuang316/code-index-mcp) |
|
||
|
||
#### 启用后的好处
|
||
- 📊 **更快分析**: 直接代码库索引 vs 手动搜索
|
||
- 🌐 **外部上下文**: 真实世界的 API 模式和示例
|
||
- 🔍 **高级搜索**: 模式匹配和相似性检测
|
||
- ⚡ **更好的可靠性**: 某些工作流的主要工具
|
||
|
||
⚠️ **注意**: 某些工作流期望 MCP 工具可用。如果没有安装，您可能会遇到：
|
||
- 代码分析和搜索操作速度较慢
|
||
- 某些场景下上下文质量降低
|
||
- 回退到效率较低的传统工具
|
||
- 高级工作流中可能出现意外行为
|
||
|
||
---
|
||
|
||
## 🚀 快速入门
|
||
|
||
### 完整开发工作流
|
||
|
||
**阶段 1：头脑风暴与概念规划**
|
||
```bash
|
||
# 多视角头脑风暴，使用基于角色的智能体
|
||
/workflow:brainstorm:auto-parallel "构建用户认证系统"
|
||
|
||
# 审查和优化特定方面（可选）
|
||
/workflow:brainstorm:ui-designer "认证流程"
|
||
/workflow:brainstorm:synthesis # 生成综合规范
|
||
```
|
||
|
||
**阶段 1.5：概念验证** *(可选质量关卡)*
|
||
```bash
|
||
# 识别并解决头脑风暴产物中的歧义
|
||
/workflow:concept-clarify
|
||
|
||
# 或显式指定会话
|
||
/workflow:concept-clarify --session WFS-auth
|
||
```
|
||
- 在 `/workflow:brainstorm:synthesis` 之后、`/workflow:plan` 之前运行
|
||
- 通过交互式问答澄清未明确的需求、架构决策或风险
|
||
- 每次会话最多 5 个问题，支持多选或简答格式
|
||
- 增量更新 `synthesis-specification.md` 以记录澄清内容
|
||
- 确保概念基础明确后再进行详细规划
|
||
- 生成覆盖度摘要，建议继续或解决未决项
|
||
|
||
**阶段 2：UI 设计精炼** *(UI 密集型项目可选)*
|
||
|
||
**🎯 选择您的工作流：**
|
||
|
||
**场景 1：从想法或概念开始** → 使用 `explore-auto`
|
||
```bash
|
||
# 生成多个风格和布局选项来探索不同方向
|
||
/workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2
|
||
# 创建一个 3×2 矩阵：3种视觉风格 × 2种布局 = 6个原型供选择
|
||
```
|
||
|
||
**场景 2：复制现有设计** → 使用 `imitate-auto`
|
||
```bash
|
||
# 快速、高保真复制参考设计
|
||
/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
|
||
# 或从 URL 自动截图（需要 Playwright/Chrome DevTools MCP）
|
||
/workflow:ui-design:imitate-auto --url "https://linear.app" --pages "home,features"
|
||
```
|
||
|
||
**场景 3：从现有设计系统批量创建** → 使用 `batch-generate`
|
||
```bash
|
||
# 已有设计系统？快速生成多个页面
|
||
/workflow:ui-design:batch-generate --prompt "创建个人资料和设置页面" --layout-variants 2
|
||
```
|
||
|
||
**高级：手动分步控制** (v4.4.0+)
|
||
```bash
|
||
# 1. 提取视觉样式（颜色、排版、间距）
|
||
/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
|
||
|
||
# 2. 整合为可用于生产的设计令牌
|
||
/workflow:ui-design:consolidate --variants "variant-1,variant-3"
|
||
|
||
# 3. 提取布局结构（DOM、CSS 布局规则）
|
||
/workflow:ui-design:layout-extract --targets "dashboard,auth" --mode explore --variants 2 --device-type responsive
|
||
|
||
# 4. 组合样式 + 布局 → HTML/CSS 原型
|
||
/workflow:ui-design:generate --style-variants 1 --layout-variants 2
|
||
|
||
# 5. 预览并选择
|
||
cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||
# 访问 http://localhost:8080/compare.html 进行并排比较
|
||
|
||
# 6. 将选定的设计集成到项目中
|
||
/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
|
||
```
|
||
|
||
**阶段 3：行动规划**
|
||
```bash
|
||
# 创建可执行的实现计划
|
||
/workflow:plan "实现基于 JWT 的认证系统"
|
||
|
||
# 或使用 TDD 方法
|
||
/workflow:tdd-plan "使用测试优先开发实现认证"
|
||
```
|
||
|
||
**阶段 3.5：行动计划验证** *(可选执行前检查)*
|
||
```bash
|
||
# 验证计划一致性和完整性
|
||
/workflow:action-plan-verify
|
||
|
||
# 或显式指定会话
|
||
/workflow:action-plan-verify --session WFS-auth
|
||
```
|
||
- 在 `/workflow:plan` 或 `/workflow:tdd-plan` 之后、`/workflow:execute` 之前运行
|
||
- 对 `IMPL_PLAN.md` 和任务 JSON 文件进行只读分析，并与 `synthesis-specification.md` 对照
|
||
- 验证需求覆盖率、依赖完整性和综合对齐性
|
||
- 识别不一致、重复、歧义和未充分说明的项目
|
||
- 生成详细验证报告，包含严重性评级的发现（CRITICAL/HIGH/MEDIUM/LOW）
|
||
- 建议是否 PROCEED、PROCEED_WITH_FIXES 或 BLOCK_EXECUTION
|
||
- 提供针对检测到的问题的可操作修复建议
|
||
|
||
**阶段 4：执行**
|
||
```bash
|
||
# 使用 AI 智能体执行任务
|
||
/workflow:execute
|
||
|
||
# 监控进度
|
||
/workflow:status
|
||
```
|
||
|
||
**阶段 5：测试与质量保证**
|
||
```bash
|
||
# 生成独立测试修复工作流（v3.2.2+）
|
||
/workflow:test-gen WFS-auth # 创建 WFS-test-auth 会话
|
||
/workflow:execute # 运行测试验证
|
||
|
||
# 或验证 TDD 合规性（TDD 工作流）
|
||
/workflow:tdd-verify
|
||
```
|
||
|
||
### 简单任务快速入门
|
||
|
||
**功能开发：**
|
||
```bash
|
||
/workflow:session:start "添加密码重置功能"
|
||
/workflow:plan "基于邮件的密码重置，带令牌过期"
|
||
/workflow:execute
|
||
```
|
||
|
||
**Bug 修复：**
|
||
```bash
|
||
# 使用 CLI 工具进行交互式分析
|
||
/cli:mode:bug-index --tool gemini "移动设备上登录超时"
|
||
|
||
# 执行建议的修复
|
||
/workflow:execute
|
||
```
|
||
|
||
> **💡 何时使用哪种方式？**
|
||
>
|
||
> **使用 `/workflow:plan` + `/workflow:execute` 适用于：**
|
||
> - 需要多个模块的复杂功能（>3 个模块）
|
||
> - 包含多个子任务的任务（>5 个子任务）
|
||
> - 影响架构的横切变更
|
||
> - 需要组件间协调的功能
|
||
> - 需要结构化规划和进度跟踪时
|
||
>
|
||
> **直接使用 Claude Code 适用于：**
|
||
> - 简单、聚焦的变更（单个文件或模块）
|
||
> - 解决方案明确的快速 bug 修复
|
||
> - 文档更新
|
||
> - 单个组件内的代码重构
|
||
> - 简单直接的功能添加
|
||
|
||
**代码分析：**
|
||
```bash
|
||
# 深度代码库分析
|
||
/cli:mode:code-analysis --tool qwen "分析认证模块架构"
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ 命令参考
|
||
|
||
### **统一 CLI 命令 (`/cli:*)**
|
||
*使用 `--tool <gemini|qwen|codex>` 标志选择所需工具。默认为 `gemini`。*
|
||
|
||
| 命令 | 描述 |
|
||
|---|---|
|
||
| `/cli:analyze` | 深度代码库分析。 |
|
||
| `/cli:chat` | 与工具进行直接的交互式聊天。 |
|
||
| `/cli:execute` | 以完全权限执行任务。 |
|
||
| `/cli:cli-init`| 为工作区初始化CLI工具配置。 |
|
||
| `/cli:mode:bug-index` | 分析错误并提出修复建议。 |
|
||
| `/cli:mode:code-analysis` | 执行深度代码分析和调试。 |
|
||
| `/cli:mode:plan` | 项目规划和架构分析。 |
|
||
|
||
### **工作流命令 (`/workflow:*)**
|
||
|
||
| 命令 | 描述 |
|
||
|---|---|
|
||
| `/workflow:session:*` | 管理开发会话（`start`, `resume`, `list`, `complete`）。 |
|
||
| `/workflow:brainstorm:*` | 使用基于角色的智能体进行多视角规划。 |
|
||
| `/workflow:concept-clarify` | **可选** 质量关卡 - 在规划之前识别并解决头脑风暴产物中的歧义（在综合后、规划前运行）。 |
|
||
| `/workflow:ui-design:explore-auto` | **v4.4.0** 矩阵探索模式 - 通过布局/样式分离生成多个风格×布局变体。 |
|
||
| `/workflow:ui-design:imitate-auto` | **v4.4.0** 快速模仿模式 - 通过自动截图、布局提取和汇编实现快速 UI 复制。 |
|
||
| `/workflow:ui-design:style-extract` | **v4.4.0** 使用 Claude 原生分析从图像/文本提取视觉样式（颜色、排版、间距）。 |
|
||
| `/workflow:ui-design:layout-extract` | **v4.4.0** 通过设备感知模板提取结构布局（DOM、CSS 布局规则）。 |
|
||
| `/workflow:ui-design:consolidate` | **v4.4.0** 使用 Claude 合成将风格变体整合为经过验证的设计令牌。 |
|
||
| `/workflow:ui-design:generate` | **v4.4.0** 纯汇编器 - 组合布局模板 + 设计令牌 → HTML/CSS 原型。 |
|
||
| `/workflow:ui-design:update` | **v4.4.0** 将最终确定的设计系统集成到头脑风暴产物中。 |
|
||
| `/workflow:plan` | 从描述创建详细、可执行的计划。 |
|
||
| `/workflow:tdd-plan` | 创建 TDD 工作流（6 阶段），包含测试覆盖分析和 Red-Green-Refactor 循环。 |
|
||
| `/workflow:action-plan-verify` | **可选** 执行前检查 - 验证 IMPL_PLAN.md 和任务 JSON 的一致性和完整性（在规划后、执行前运行）。 |
|
||
| `/workflow:execute` | 自主执行当前的工作流计划。 |
|
||
| `/workflow:status` | 显示工作流的当前状态。 |
|
||
| `/workflow:test-gen [--use-codex] <session>` | 为已完成实现创建独立测试生成工作流，支持自动诊断和修复。 |
|
||
| `/workflow:tdd-verify` | 验证 TDD 合规性并生成质量报告。 |
|
||
| `/workflow:review` | **可选** 手动审查（仅在明确需要时使用，测试通过即代表代码已批准）。 |
|
||
| `/workflow:tools:test-context-gather` | 分析测试覆盖率，识别缺失的测试文件。 |
|
||
| `/workflow:tools:test-concept-enhanced` | 使用 Gemini 生成测试策略和需求分析。 |
|
||
| `/workflow:tools:test-task-generate` | 生成测试任务 JSON，包含 test-fix-cycle 规范。 |
|
||
|
||
### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v4.4.0)*
|
||
|
||
设计工作流系统提供完整的 UI 设计精炼，具备**布局/样式分离架构**、**纯 Claude 执行**、**智能目标推断**和**零外部依赖**。
|
||
|
||
#### 📐 架构概述
|
||
|
||
UI 工作流遵循**关注点分离**哲学：
|
||
- **样式（视觉令牌）**：颜色、排版、间距、边框 → `design-tokens.json`
|
||
- **布局（结构）**：DOM 层次结构、CSS 布局规则 → `layout-templates.json`
|
||
- **汇编**：纯粹组合样式 + 布局 → HTML/CSS 原型
|
||
|
||
**命令分类：**
|
||
|
||
| 类别 | 命令 | 目的 |
|
||
|----------|----------|---------|
|
||
| **高级编排器** | `explore-auto`, `imitate-auto`, `batch-generate` | 完整工作流（推荐） |
|
||
| **输入/捕获** | `capture`, `explore-layers` | 截图获取 |
|
||
| **分析/提取** | `style-extract`, `layout-extract` | 视觉样式和结构布局提取 |
|
||
| **处理/生成** | `consolidate`, `generate` | 令牌验证和原型汇编 |
|
||
| **集成** | `update` | 设计系统集成到项目 |
|
||
|
||
#### 🧭 决策树：应该使用哪个命令？
|
||
|
||
```
|
||
┌─ 有想法或文本描述？
|
||
│ └─→ /workflow:ui-design:explore-auto
|
||
│ （探索多个风格 × 布局选项）
|
||
│
|
||
┌─ 想复制现有设计？
|
||
│ └─→ /workflow:ui-design:imitate-auto
|
||
│ （高保真单一设计复制）
|
||
│
|
||
┌─ 已有设计系统？
|
||
│ └─→ /workflow:ui-design:batch-generate
|
||
│ （批量创建多个页面/组件）
|
||
│
|
||
└─ 需要细粒度控制？
|
||
└─→ 按顺序使用单独命令：
|
||
1. style-extract → 提取颜色、字体、间距
|
||
2. consolidate → 验证并合并令牌
|
||
3. layout-extract → 提取 DOM 结构
|
||
4. generate → 组合为原型
|
||
5. update → 集成到项目
|
||
```
|
||
|
||
#### 🔄 工作流程图
|
||
|
||
**探索工作流**（想法 → 多个设计）：
|
||
```
|
||
提示词/图像 → style-extract（探索模式）
|
||
↓
|
||
consolidate（N 个变体）
|
||
↓
|
||
layout-extract（探索模式）
|
||
↓
|
||
generate（N 个样式 × M 个布局）
|
||
↓
|
||
update（选定的设计）
|
||
```
|
||
|
||
**模仿工作流**（参考 → 单一设计）：
|
||
```
|
||
URL/图像 → capture/explore-layers
|
||
↓
|
||
style-extract（模仿模式）
|
||
↓
|
||
layout-extract（模仿模式）
|
||
↓
|
||
consolidate（单一变体）
|
||
↓
|
||
generate（1 个样式 × 1 个布局）
|
||
↓
|
||
update（最终设计）
|
||
```
|
||
|
||
#### 核心命令
|
||
|
||
**`/workflow:ui-design:explore-auto`** - 矩阵探索模式
|
||
```bash
|
||
# 全面探索 - 多个风格×布局变体
|
||
/workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2
|
||
|
||
# 与图像和会话集成
|
||
/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
|
||
|
||
# 纯文本模式，带页面推断
|
||
/workflow:ui-design:explore-auto --prompt "电商：首页，产品，购物车" --style-variants 2 --layout-variants 2
|
||
```
|
||
- **🎯 矩阵模式**: 生成所有风格×布局组合
|
||
- **📊 全面探索**: 比较多个设计方向
|
||
- **🔍 交互式对比**: 带视口控制的并排比较
|
||
- **✅ 跨页面验证**: 多页面设计的自动一致性检查
|
||
- **⚡ 批量选择**: 按风格或布局快速选择
|
||
|
||
**`/workflow:ui-design:imitate-auto`** - 快速模仿模式
|
||
```bash
|
||
# 快速单一设计复制
|
||
/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
|
||
|
||
# 与会话集成
|
||
/workflow:ui-design:imitate-auto --session WFS-auth --images "refs/ui.png" --pages "home,product"
|
||
|
||
# 从 URL 自动截图（需要 Playwright）
|
||
/workflow:ui-design:imitate-auto --url "https://example.com" --pages "landing"
|
||
```
|
||
- **⚡ 速度优化**: 比 explore-auto 快 5-10 倍
|
||
- **📸 自动截图**: 使用 Playwright/Chrome 自动捕获 URL 截图
|
||
- **🎯 直接提取**: 跳过变体选择，直接进入实现
|
||
- **🔧 单一设计聚焦**: 最适合快速复制现有设计
|
||
|
||
**`/workflow:ui-design:style-extract`** - 视觉样式提取（v4.4.0）
|
||
```bash
|
||
# 纯文本提示
|
||
/workflow:ui-design:style-extract --prompt "现代极简，深色主题" --mode explore --variants 3
|
||
|
||
# 纯图像
|
||
/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
|
||
|
||
# 混合（文本指导图像分析）
|
||
/workflow:ui-design:style-extract --images "refs/*.png" --prompt "Linear.app 风格" --mode imitate
|
||
|
||
# 高保真单一风格
|
||
/workflow:ui-design:style-extract --images "design.png" --mode imitate
|
||
```
|
||
- **🎨 仅视觉令牌**：颜色、排版、间距（无布局结构）
|
||
- **🔄 双模式**：模仿（单一变体）/ 探索（多个变体）
|
||
- **Claude 原生**：单次分析，无外部工具
|
||
- **输出**：包含嵌入式 `proposed_tokens` 的 `style-cards.json`
|
||
|
||
**`/workflow:ui-design:layout-extract`** - 结构布局提取（v4.4.0）
|
||
```bash
|
||
# 探索模式 - 多个布局变体
|
||
/workflow:ui-design:layout-extract --targets "home,dashboard" --mode explore --variants 3 --device-type responsive
|
||
|
||
# 模仿模式 - 单一布局复制
|
||
/workflow:ui-design:layout-extract --images "refs/*.png" --targets "dashboard" --mode imitate --device-type desktop
|
||
|
||
# 使用 MCP 研究（探索模式）
|
||
/workflow:ui-design:layout-extract --prompt "电商结账" --targets "cart,checkout" --mode explore --variants 2
|
||
```
|
||
- **🏗️ 仅结构**：DOM 层次结构、CSS 布局规则（无视觉样式）
|
||
- **📱 设备感知**：桌面、移动、平板、响应式优化
|
||
- **🧠 智能体驱动**：使用 ui-design-agent 进行结构分析
|
||
- **🔍 MCP 研究**：布局模式灵感（探索模式）
|
||
- **输出**：包含基于令牌的 CSS 的 `layout-templates.json`
|
||
|
||
**`/workflow:ui-design:consolidate`** - 验证和合并令牌
|
||
```bash
|
||
# 整合选定的风格变体
|
||
/workflow:ui-design:consolidate --session WFS-auth --variants "variant-1,variant-3"
|
||
```
|
||
- **Claude 合成**：单次生成所有设计系统文件
|
||
- **功能**：WCAG AA 验证、OKLCH 颜色、W3C 令牌格式
|
||
- **输出**：`design-tokens.json`、`style-guide.md`、`tailwind.config.js`、`validation-report.json`
|
||
|
||
**`/workflow:ui-design:generate`** - 纯汇编器（v4.4.0）
|
||
```bash
|
||
# 组合布局模板 + 设计令牌
|
||
/workflow:ui-design:generate --style-variants 1 --layout-variants 2
|
||
|
||
# 多个样式与多个布局
|
||
/workflow:ui-design:generate --style-variants 2 --layout-variants 3
|
||
```
|
||
- **📦 纯汇编**：组合预提取的 layout-templates.json + design-tokens.json
|
||
- **❌ 无设计逻辑**：所有布局/样式决策在之前阶段完成
|
||
- **✅ 令牌解析**：用实际令牌值替换 var() 占位符
|
||
- **🎯 矩阵输出**：生成样式 × 布局 × 目标原型
|
||
- **🔍 交互式预览**：`compare.html` 并排比较
|
||
|
||
**`/workflow:ui-design:update`** - 集成设计系统
|
||
```bash
|
||
# 使用设计系统更新头脑风暴产物
|
||
/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
|
||
```
|
||
- **更新**: `synthesis-specification.md`、`ui-designer/style-guide.md`
|
||
- **使设计令牌可用于任务生成**
|
||
|
||
#### 预览系统
|
||
|
||
运行 `ui-generate` 后，您将获得交互式预览工具，**无需启动服务器即可直接在浏览器中使用**：
|
||
|
||
**直接浏览器预览**（推荐 - 无需服务器）:
|
||
```bash
|
||
# 导航到原型目录
|
||
cd .workflow/WFS-auth/.design/prototypes
|
||
|
||
# 在浏览器中打开（双击文件或使用命令）:
|
||
open index.html # macOS
|
||
start index.html # Windows
|
||
xdg-open index.html # Linux
|
||
|
||
# index.html 和 compare.html 都可以直接打开，无需服务器
|
||
open compare.html # 直接打开对比视图
|
||
```
|
||
|
||
**可选：本地服务器**（用于高级功能）:
|
||
```bash
|
||
cd .workflow/WFS-auth/.design/prototypes
|
||
# 如果需要服务器端功能，可选择一个:
|
||
python -m http.server 8080 # Python
|
||
npx http-server -p 8080 # Node.js
|
||
php -S localhost:8080 # PHP
|
||
# 访问: http://localhost:8080
|
||
```
|
||
|
||
**预览功能**:
|
||
- `index.html`: 包含所有原型的主导航（离线可用）
|
||
- `compare.html`: 带视口控制的并排对比（离线可用）
|
||
- 同步滚动用于布局对比
|
||
- 动态页面切换
|
||
- 实时响应式测试
|
||
- **无需服务器** - 所有功能都可通过直接在浏览器中打开文件来使用
|
||
|
||
#### 📦 输出结构
|
||
|
||
所有 UI 工作流输出都组织在会话内的 `.design` 目录中：
|
||
|
||
```
|
||
.workflow/WFS-<session-id>/.design/
|
||
├── design-run-YYYYMMDD-HHMMSS/ # 带时间戳的设计运行
|
||
│ ├── screenshots/ # 📸 捕获的截图
|
||
│ │ ├── home.png
|
||
│ │ └── dashboard.png
|
||
│ │
|
||
│ ├── style-extraction/ # 🎨 样式分析阶段
|
||
│ │ ├── style-cards.json # AI 提议的风格变体
|
||
│ │ └── design-space-analysis.json # （探索模式）多样性分析
|
||
│ │
|
||
│ ├── layout-extraction/ # 🏗️ 布局分析阶段
|
||
│ │ └── layout-templates.json # 包含基于令牌的 CSS 的结构模板
|
||
│ │
|
||
│ ├── style-consolidation/ # ✅ 生产设计系统
|
||
│ │ ├── style-1/
|
||
│ │ │ ├── design-tokens.json # W3C 设计令牌
|
||
│ │ │ ├── style-guide.md # 视觉设计文档
|
||
│ │ │ ├── tailwind.config.js # Tailwind 配置
|
||
│ │ │ └── validation-report.json # WCAG AA 验证结果
|
||
│ │ └── style-2/
|
||
│ │ └── ...
|
||
│ │
|
||
│ └── prototypes/ # 🎯 最终 HTML/CSS 原型
|
||
│ ├── home-style-1-layout-1.html # 矩阵生成的原型
|
||
│ ├── home-style-1-layout-1.css
|
||
│ ├── home-style-1-layout-2.html
|
||
│ ├── dashboard-style-2-layout-1.html
|
||
│ ├── index.html # 主导航页面
|
||
│ └── compare.html # 并排比较工具
|
||
│
|
||
└── latest -> design-run-YYYYMMDD-HHMMSS # 指向最新运行的符号链接
|
||
```
|
||
|
||
**关键文件：**
|
||
|
||
| 文件 | 目的 | 生成命令 |
|
||
|------|---------|--------------|
|
||
| `style-cards.json` | AI 提议的视觉样式及嵌入的令牌 | `style-extract` |
|
||
| `layout-templates.json` | 包含基于令牌的 CSS 的结构模板 | `layout-extract` |
|
||
| `design-tokens.json` | 可用于生产的 W3C 设计令牌 | `consolidate` |
|
||
| `style-guide.md` | 视觉设计系统文档 | `consolidate` |
|
||
| `compare.html` | 交互式原型比较矩阵 | `generate` |
|
||
|
||
**最佳实践：**
|
||
|
||
1. **会话管理**：会话内的所有运行累积在 `.design/design-run-*/`
|
||
2. **版本控制**：每次运行都有时间戳，便于回滚
|
||
3. **集成**：使用 `update` 命令将最终令牌链接到项目产物
|
||
4. **清理**：旧运行可以安全删除；`latest` 符号链接始终指向最新的
|
||
|
||
---
|
||
|
||
### **任务与内存命令**
|
||
|
||
| 命令 | 描述 |
|
||
|---|---|
|
||
| `/task:*` | 管理单个任务（`create`, `breakdown`, `execute`, `replan`）。 |
|
||
| `/update-memory-full` | 重新索引整个项目文档。 |
|
||
| `/update-memory-related` | 更新与最近更改相关的文档。 |
|
||
| `/version` | 显示版本信息并检查 GitHub 更新。 |
|
||
|
||
---
|
||
|
||
## 🧠 内存管理：上下文质量基础
|
||
|
||
分层内存系统实现精确上下文收集和防止执行漂移。定期更新是高质量 AI 输出的关键。
|
||
|
||
#### **内存层次**
|
||
|
||
```
|
||
CLAUDE.md（根）→ domain/CLAUDE.md（领域）→ module/CLAUDE.md（模块）→ submodule/CLAUDE.md（子模块）
|
||
```
|
||
|
||
#### **更新时机**
|
||
|
||
| 触发条件 | 命令 | 目的 |
|
||
|---------|---------|---------|
|
||
| 主要功能实现后 | `/update-memory-related` | 更新受影响模块/依赖 |
|
||
| 架构变更后 | `/update-memory-full` | 重新索引整个项目 |
|
||
| 复杂规划前 | `/update-memory-related` | 确保 context-package.json 最新模式 |
|
||
| 重构后 | `/update-memory-related` | 更新实现模式/API |
|
||
| 每周维护 | `/update-memory-full` | 保持文档同步 |
|
||
|
||
#### **质量影响**
|
||
|
||
**无更新：** ❌ 过时模式、弃用 API、错误上下文、架构漂移
|
||
**有更新：** ✅ 当前模式、最新 API、准确上下文、架构对齐
|
||
|
||
#### **最佳实践**
|
||
|
||
1. 重大变更后立即更新
|
||
2. 频繁使用 `/update-memory-related`（更快、有针对性）
|
||
3. 每周安排 `/update-memory-full`（捕获漂移）
|
||
4. 审查生成的 CLAUDE.md 文件
|
||
5. 集成到 CI/CD 流水线
|
||
|
||
> 💡 内存质量决定 context-package.json 质量和执行准确性。视为关键维护，非可选文档。
|
||
|
||
#### **工具集成**
|
||
|
||
```bash
|
||
/update-memory-full --tool gemini # 全面分析（默认）
|
||
/update-memory-full --tool qwen # 架构聚焦
|
||
/update-memory-full --tool codex # 实现细节
|
||
```
|
||
|
||
---
|
||
|
||
## 🏗️ 技术架构
|
||
|
||
完整的自文档化系统，用专业软件工程实践编排 AI 智能体。
|
||
|
||
### **项目组织**
|
||
|
||
```
|
||
.claude/
|
||
├── agents/ # 专用 AI 智能体（action-planning、code-developer、test-fix）
|
||
├── commands/ # 面向用户和内部命令（workflow:*、cli:*、task:*）
|
||
├── workflows/ # 战略框架（架构、策略、模式、模板）
|
||
├── scripts/ # 实用工具自动化（模块分析、文件监控）
|
||
└── prompt-templates/# 标准化 AI 提示词
|
||
```
|
||
|
||
**原则：** 关注点分离（agents/commands/workflows）、层次化命令、自文档化、可扩展模板
|
||
|
||
### **执行模型**
|
||
|
||
```
|
||
用户命令 → 编排器 → 阶段 1-4（上下文 → 分析 → 规划 → 执行）
|
||
↓
|
||
专用智能体（pre_analysis → 实现 → 验证）
|
||
```
|
||
|
||
**示例：** `/workflow:plan "构建认证"` → session:start → context-gather → concept-enhanced → task-generate
|
||
|
||
---
|
||
|
||
## 🧩 工作原理：设计理念
|
||
|
||
### 核心问题
|
||
|
||
传统的 AI 编码工作流面临一个根本性挑战：**执行不确定性导致误差累积**。
|
||
|
||
**示例：**
|
||
```bash
|
||
# 提示词1："开发XX功能"
|
||
# 提示词2："查看XX文件中架构设计，开发XX功能"
|
||
```
|
||
|
||
虽然提示词1对简单任务可能成功，但在复杂工作流中：
|
||
- AI 每次可能检查不同的文件
|
||
- 小偏差在多个步骤中累积
|
||
- 最终输出偏离预期目标
|
||
|
||
> **CCW 的使命**：解决"1到N"的问题 — 精确地在现有代码库基础上开发，而不仅仅是"0到1"的全新项目开发。
|
||
|
||
---
|
||
|
||
### CCW 解决方案：上下文优先架构
|
||
|
||
#### 1. **预定义上下文收集**
|
||
|
||
CCW 使用结构化上下文包，而不是让智能体随机探索：
|
||
|
||
**规划阶段创建的 `context-package.json`**：
|
||
```json
|
||
{
|
||
"metadata": {
|
||
"task_description": "...",
|
||
"tech_stack": {"frontend": [...], "backend": [...]},
|
||
"complexity": "high"
|
||
},
|
||
"assets": [
|
||
{
|
||
"path": "synthesis-specification.md",
|
||
"priority": "critical",
|
||
"sections": ["后端模块结构"]
|
||
}
|
||
],
|
||
"implementation_guidance": {
|
||
"start_with": ["步骤1", "步骤2"],
|
||
"critical_security_items": [...]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2. **JSON 优先任务模型**
|
||
|
||
每个任务包含 `flow_control.pre_analysis` 部分：
|
||
|
||
```json
|
||
{
|
||
"id": "IMPL-1",
|
||
"flow_control": {
|
||
"pre_analysis": [
|
||
{
|
||
"step": "load_architecture",
|
||
"commands": ["Read(architecture.md)", "grep 'auth' src/"],
|
||
"output_to": "arch_context",
|
||
"on_error": "fail"
|
||
}
|
||
],
|
||
"implementation_approach": {
|
||
"modification_points": ["..."],
|
||
"logic_flow": ["..."]
|
||
},
|
||
"target_files": ["src/auth/index.ts"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**核心创新**：`pre_analysis` 步骤在实现**之前执行**，确保智能体始终拥有正确的上下文。
|
||
|
||
#### 3. **多阶段编排**
|
||
|
||
CCW 工作流是协调斜杠命令的编排器：
|
||
|
||
**规划阶段** (`/workflow:plan`)：
|
||
```
|
||
阶段1: session:start → 创建会话
|
||
阶段2: context-gather → 构建 context-package.json
|
||
阶段3: concept-enhanced → CLI 分析（Gemini/Qwen）
|
||
阶段4: task-generate → 生成带 pre_analysis 的任务 JSON
|
||
```
|
||
|
||
**执行阶段** (`/workflow:execute`)：
|
||
```
|
||
对于每个任务：
|
||
1. 执行 pre_analysis 步骤 → 加载上下文
|
||
2. 应用 implementation_approach → 进行更改
|
||
3. 验证验收标准 → 验证成功
|
||
4. 生成摘要 → 跟踪进度
|
||
```
|
||
|
||
#### 4. **多模型编排**
|
||
|
||
每个 AI 模型发挥各自优势：
|
||
|
||
| 模型 | 角色 | 使用场景 |
|
||
|------|------|----------|
|
||
| **Gemini** | 分析与理解 | 长上下文分析、架构审查、bug 调查 |
|
||
| **Qwen** | 架构与设计 | 系统设计、代码生成、架构规划 |
|
||
| **Codex** | 实现 | 功能开发、测试、自主执行 |
|
||
|
||
**示例：**
|
||
```bash
|
||
# Gemini 分析问题空间
|
||
/cli:mode:code-analysis --tool gemini "分析认证模块"
|
||
|
||
# Qwen 设计解决方案
|
||
/cli:analyze --tool qwen "设计可扩展的认证架构"
|
||
|
||
# Codex 实现代码
|
||
/workflow:execute # 使用带 Codex 的 @code-developer
|
||
```
|
||
|
||
---
|
||
|
||
### 0到1 vs 1到N 开发
|
||
|
||
| 场景 | 传统工作流 | CCW 方法 |
|
||
|------|-----------|----------|
|
||
| **全新项目（0→1）** | ✅ 效果良好 | ✅ 增加结构化规划 |
|
||
| **功能添加（1→2）** | ⚠️ 上下文不确定 | ✅ context-package 链接现有代码 |
|
||
| **Bug 修复（N→N+1）** | ⚠️ 可能遗漏相关代码 | ✅ pre_analysis 查找依赖 |
|
||
| **重构** | ⚠️ 范围不可预测 | ✅ CLI 分析 + 结构化任务 |
|
||
|
||
---
|
||
|
||
### 核心工作流
|
||
|
||
#### **完整开发（头脑风暴 → 部署）**
|
||
```
|
||
头脑风暴（8个角色）→ 综合 → 规划（4阶段）→ 执行 → 测试 → 审查
|
||
```
|
||
|
||
#### **快速功能开发**
|
||
```
|
||
session:start → plan → execute → test-gen → execute
|
||
```
|
||
|
||
#### **TDD 工作流**
|
||
```
|
||
tdd-plan (TEST→IMPL→REFACTOR 链) → execute → tdd-verify
|
||
```
|
||
|
||
#### **Bug 修复**
|
||
```
|
||
cli:mode:bug-index（分析）→ execute（修复）→ test-gen（验证）
|
||
```
|
||
|
||
---
|
||
|
||
## 🤝 贡献与支持
|
||
|
||
- **仓库**: [GitHub - Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)
|
||
- **问题**: 在 [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues) 上报告错误或请求功能。
|
||
- **讨论**: 加入 [社区论坛](https://github.com/catlog22/Claude-Code-Workflow/discussions)。
|
||
|
||
## 📄 许可证
|
||
|
||
此项目根据 **MIT 许可证** 授权。详见 [LICENSE](LICENSE) 文件。
|