catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
24aad6238ab61dfc4c314171b8f9b18a7ccc622e
Claude-Code-Workflow/README_CN.md
catlog22 24aad6238a feat: add dynamic output format for prompt-enhancer and update README 
- Redesign output format to be dynamic and task-adaptive
- Replace fixed template with core + optional fields structure
- Add simple and complex task examples
- Update workflow and enhancement guidelines
- Add Agent Skills section to README.md and README_CN.md
- Document Prompt Enhancer skill usage with -e/--enhance flags
- Provide skill creation best practices

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-18 23:00:08 +08:00

39 KiB
Raw Blame History

🚀 Claude Code Workflow (CCW)

Version License Platform MCP工具

语言: English | 中文

Claude Code Workflow (CCW) 将 AI 开发从简单提示词链接转变为强大的上下文优先编排系统。通过结构化规划、确定性执行和智能多模型编排，解决执行不确定性和误差累积问题。

🎉 最新版本: v4.6.0 - 概念澄清与智能体驱动分析。详见 CHANGELOG.md。

v4.6.0 版本新特性:

  • 🎯 概念澄清质量关卡: 任务生成前通过交互式问答解决歧义（Phase 3.5）
  • 🤖 智能体委托分析: Phase 3 现使用 cli-execution-agent 进行自主上下文发现
  • 🔄 双模式支持: concept-clarify 自动检测头脑风暴 vs 规划工作流
  • 📚 测试循环执行: 增强了动态测试修复迭代工作流的文档说明
  • ✨ 向后兼容: 所有增强功能保留现有工作流功能

📚 第一次使用 CCW？ 查看 快速上手指南 获取新手友好的 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):

Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content

Linux/macOS (Bash/Zsh):

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 安装脚本：

安装模式：

# 交互式安装（推荐）
.\Install-Claude.ps1

# 快速安装（自动备份）
.\Install-Claude.ps1 -Force -BackupAll

# 非交互式安装
.\Install-Claude.ps1 -NonInteractive -Force

安装选项：

模式 描述 安装位置
Global 系统级安装（默认） ~/.claude/、~/.codex/、~/.gemini/
Path 自定义目录 + 全局混合 本地：agents/、commands/
全局：workflows/、scripts/

备份行为：

  • 默认：自动备份启用（-BackupAll）
  • 禁用：使用 -NoBackup 标志（⚠️ 无备份覆盖）
  • 备份位置：安装目录中的 claude-backup-{timestamp}/

⚠️ 重要警告：

  • -Force -BackupAll：静默文件覆盖（带备份）
  • -NoBackup -Force：永久文件覆盖（无法恢复）
  • Global 模式会修改用户配置目录

✅ 验证安装

安装后，打开 Claude Code 并检查工作流命令是否可用，运行以下命令：

/workflow:session:list

此命令应在 Claude Code 界面中被识别。如果您能看到工作流 slash 命令（例如 /workflow:*、/cli:*），说明安装成功。

📝 安装说明：

  • 安装程序将自动安装/更新 .codex/ 和 .gemini/ 目录
  • 全局模式：安装到 ~/.codex 和 ~/.gemini
  • 路径模式：安装到指定目录（例如 project/.codex、project/.gemini）
  • 备份：默认自动备份现有文件到 claude-backup-{timestamp}/
  • 安全：首次安装建议使用交互式模式以审查更改

⚙️ 配置

工具控制系统

CCW 使用基于配置的工具控制系统，使外部 CLI 工具成为可选项而非必需项。这允许您：

  • ✅ 从纯 Claude 模式开始 - 无需安装额外工具即可立即开始工作
  • ✅ 渐进式增强 - 根据需要选择性地添加外部工具
  • ✅ 优雅降级 - 工具不可用时自动回退
  • ✅ 灵活配置 - 按项目控制工具可用性

配置文件: ~/.claude/workflows/tool-control.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) 免费配额，复杂项目的扩展上下文
Codex CLI AI 开发与实现 npm install -g @openai/codex (GitHub) 自主开发，数学推理
Qwen Code AI 架构与代码生成 npm install -g @qwen-code/qwen-code (文档) 大上下文窗口，架构分析

系统实用工具

工具 用途 安装方式
ripgrep (rg) 快速代码搜索 下载 或 brew install ripgrep (macOS), apt install ripgrep (Ubuntu)
jq JSON 处理 下载 或 brew install jq (macOS), apt install jq (Ubuntu)

快速安装（所有工具）：

# 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 以实现最佳集成：

// ~/.gemini/settings.json
{
  "contextFileName": ["CLAUDE.md", "GEMINI.md"]
}

推荐: .geminiignore

通过排除不必要的文件来优化性能：

# .geminiignore (在项目根目录)
/dist/
/build/
/node_modules/
/.next/
*.tmp
*.log
/temp/

# 包含重要文档
!README.md
!**/CLAUDE.md

推荐: MCP 工具 (增强分析)

MCP (模型上下文协议) 工具提供高级代码库分析。推荐安装 - 虽然 CCW 具有回退机制，但不安装 MCP 工具可能会导致某些工作流出现意外行为或性能下降。

可用的 MCP 服务器

MCP 服务器 用途 安装指南
Exa MCP 外部 API 模式和最佳实践 安装指南
Code Index MCP 高级内部代码搜索 安装指南
Chrome DevTools MCP ⚠️ UI 工作流必需 - URL 模式设计提取 安装指南

启用后的好处

  • 📊 更快分析: 直接代码库索引 vs 手动搜索
  • 🌐 外部上下文: 真实世界的 API 模式和示例
  • 🔍 高级搜索: 模式匹配和相似性检测
  • ⚡ 更好的可靠性: 某些工作流的主要工具
  • 🎨 UI 工作流: Chrome DevTools 实现从在线 URL 进行像素级精确设计提取

⚠️ 注意: 某些工作流期望 MCP 工具可用。如果没有安装，您可能会遇到：

  • 代码分析和搜索操作速度较慢
  • 某些场景下上下文质量降低
  • 回退到效率较低的传统工具
  • 高级工作流中可能出现意外行为

🎯 智能体技能 (Agent Skills)

智能体技能 通过模块化、可复用的专业知识包扩展 Claude 的能力。技能会根据上下文自动发现和触发。

可用技能

提示词增强器 (Prompt Enhancer)

将模糊提示转换为结构化、可执行的规范。

使用方式：在任何请求中添加 -e 或 --enhance 标志

# 示例
修复认证问题 -e
优化数据库查询 --enhance

功能说明:

  • 分析会话上下文和技术栈
  • 将意图结构化为 INTENT → ACTION 格式
  • 添加相关上下文、约束和指标
  • 输出可立即执行的规范

输出：根据任务类型动态调整的结构化提示（简单任务使用最少字段，复杂任务使用全面规范）

创建自定义技能

技能存储在 .claude/skills/（项目）或 ~/.claude/skills/（个人）：

# 创建新技能
mkdir -p .claude/skills/my-skill

SKILL.md 结构:

---
name: 我的技能名称
description: 功能说明和使用时机。使用时机：[触发条件]。
allowed-tools: Read, Grep, Glob  # 可选工具限制
---

# 我的技能名称

## 指令
[Claude 的分步指导]

## 示例
[具体使用示例]

最佳实践:

  • 编写具体的描述，包含明确的触发条件
  • 同时说明功能和使用时机
  • 保持技能专注于单一能力
  • 通过匹配描述的问题进行测试

完整文档请参阅 skills.md。

🚀 快速入门

完整开发工作流

阶段 1：头脑风暴与概念规划

# 多视角头脑风暴，使用基于角色的智能体
/workflow:brainstorm:auto-parallel "构建用户认证系统"

# 审查和优化特定方面（可选）
/workflow:brainstorm:ui-designer "认证流程"
/workflow:brainstorm:synthesis  # 生成综合规范

阶段 1.5：概念验证 (可选质量关卡)

# 识别并解决头脑风暴产物中的歧义
/workflow:concept-clarify

# 或显式指定会话
/workflow:concept-clarify --session WFS-auth
  • 在 /workflow:brainstorm:synthesis 之后、/workflow:plan 之前运行
  • 通过交互式问答澄清未明确的需求、架构决策或风险
  • 每次会话最多 5 个问题，支持多选或简答格式
  • 增量更新 synthesis-specification.md 以记录澄清内容
  • 确保概念基础明确后再进行详细规划
  • 生成覆盖度摘要，建议继续或解决未决项

阶段 2：UI 设计精炼 (UI 密集型项目可选)

🎯 选择您的工作流：

场景 1：从想法或概念开始 → 使用 explore-auto

# 生成多个风格和布局选项来探索不同方向
/workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2
# 创建一个 3×2 矩阵：3种视觉风格 × 2种布局 = 6个原型供选择

场景 2：复制现有设计 → 使用 imitate-auto

# 快速、高保真复制参考设计
/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

# 已有设计系统？快速生成多个页面
/workflow:ui-design:batch-generate --prompt "创建个人资料和设置页面" --layout-variants 2

高级：手动分步控制 (v4.4.0+)

# 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：行动规划

# 创建可执行的实现计划
/workflow:plan "实现基于 JWT 的认证系统"

# 或使用 TDD 方法
/workflow:tdd-plan "使用测试优先开发实现认证"

阶段 3.5：行动计划验证 (可选执行前检查)

# 验证计划一致性和完整性
/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：执行

# 使用 AI 智能体执行任务
/workflow:execute

# 监控进度
/workflow:status

阶段 5：测试与质量保证

# 生成独立测试修复工作流（v3.2.2+）
/workflow:test-gen WFS-auth          # 创建 WFS-test-auth 会话
/workflow:test-cycle-execute         # 执行测试修复循环，包含动态迭代

# 恢复中断的测试会话
/workflow:test-cycle-execute --resume-session="WFS-test-auth"

# 或验证 TDD 合规性（TDD 工作流）
/workflow:tdd-verify

什么是 /workflow:test-cycle-execute？

  • 动态任务生成：基于测试失败在执行过程中创建中间修复任务
  • 迭代测试：自动运行测试修复循环，直到所有测试通过或达到最大迭代次数
  • CLI 驱动分析：使用 Gemini/Qwen 分析失败并生成修复策略
  • 智能体协调：将测试执行和修复委托给 @test-fix-agent
  • 自主完成：持续直到成功，无需用户干预

简单任务快速入门

功能开发：

/workflow:session:start "添加密码重置功能"
/workflow:plan "基于邮件的密码重置，带令牌过期"
/workflow:execute

Bug 修复：

# 使用 CLI 工具进行交互式分析
/cli:mode:bug-index --tool gemini "移动设备上登录超时"

# 执行建议的修复
/workflow:execute

💡 何时使用哪种方式？

使用 /workflow:plan + /workflow:execute 适用于：

  • 需要多个模块的复杂功能（>3 个模块）
  • 包含多个子任务的任务（>5 个子任务）
  • 影响架构的横切变更
  • 需要组件间协调的功能
  • 需要结构化规划和进度跟踪时

直接使用 Claude Code 适用于：

  • 简单、聚焦的变更（单个文件或模块）
  • 解决方案明确的快速 bug 修复
  • 文档更新
  • 单个组件内的代码重构
  • 简单直接的功能添加

代码分析：

# 深度代码库分析
/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:test-cycle-execute v4.5.0 执行测试修复工作流，包含动态任务生成和迭代修复循环。运行测试 → 使用 CLI 分析失败 → 生成修复任务 → 重新测试直至成功。
/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)

⚠️ 基于 URL 的设计提取: 安装 Chrome DevTools MCP 以启用从在线 URL 自动提取计算样式和 DOM 结构。如果不可用，将回退到视觉分析。

设计工作流系统提供完整的 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 - 矩阵探索模式

# 全面探索 - 多个风格×布局变体
/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 - 快速模仿模式

# 快速单一设计复制
/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）

# 纯文本提示
/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）

# 探索模式 - 多个布局变体
/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 - 验证和合并令牌

# 整合选定的风格变体
/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）

# 组合布局模板 + 设计令牌
/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 - 集成设计系统

# 使用设计系统更新头脑风暴产物
/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
  • 更新: synthesis-specification.md、ui-designer/style-guide.md
  • 使设计令牌可用于任务生成

预览系统

运行 ui-generate 后，您将获得交互式预览工具，无需启动服务器即可直接在浏览器中使用：

直接浏览器预览（推荐 - 无需服务器）:

# 导航到原型目录
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  # 直接打开对比视图

可选：本地服务器（用于高级功能）:

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 质量和执行准确性。视为关键维护，非可选文档。

工具集成

/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 编码工作流面临一个根本性挑战：执行不确定性导致误差累积。

示例：

# 提示词1："开发XX功能"
# 提示词2："查看XX文件中架构设计，开发XX功能"

虽然提示词1对简单任务可能成功，但在复杂工作流中：

  • AI 每次可能检查不同的文件
  • 小偏差在多个步骤中累积
  • 最终输出偏离预期目标

CCW 的使命：解决"1到N"的问题 — 精确地在现有代码库基础上开发，而不仅仅是"0到1"的全新项目开发。

CCW 解决方案：上下文优先架构

1. 预定义上下文收集

CCW 使用结构化上下文包，而不是让智能体随机探索：

规划阶段创建的 context-package.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 部分：

{
  "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 实现 功能开发、测试、自主执行

示例：

# 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（验证）

🤝 贡献与支持

📄 许可证

此项目根据 MIT 许可证 授权。详见 LICENSE 文件。

Reference in New Issue View Git Blame Copy Permalink