Claude 代码规范工作流

⚠️ 重要通知： 开发重点已转移至该工作流系统的 MCP（模型上下文协议）版本。MCP 版本提供了增强功能、实时仪表板以及更广泛的 AI 工具兼容性。

🚀 查看新的规范工作流 MCP →

此 Claude 代码专用版本仍供现有用户使用，但更新将有限。

针对 Claude 代码的自动化工作流，具备智能任务执行能力。

通过结构化的工作流彻底变革您的开发流程：针对新功能采用 需求 → 设计 → 任务 → 实现 流程；针对 Bug 修复则采用简化的 报告 → 分析 → 修复 → 验证 流程。

☕ 支持本项目

📦 安装

1. 全局安装工作流工具

npm i -g @pimzino/claude-code-spec-workflow

2. 在您的项目目录中运行设置命令

claude-code-spec-workflow

这样就完成了，您可以开始使用了！

✨ 您将获得的内容

• 📁 完整的 .claude/ 目录结构 - 所有文件和子目录
• 📝 10 条斜杠命令 - 5 条用于规范工作流，5 条用于 Bug 修复工作流
• 🎯 智能任务执行 - 自动化实现
• 🤖 4 个专用代理 - 增强自动化能力
• 📊 实时仪表板 - 可视化监控进度
• 🔧 自动生成的命令 - 每项任务对应一条命令
• 📋 文档模板 - 专业规范文档
• ⚙️ 项目指导 - 持久的上下文与标准
• ⚡ 智能优化 - 智能上下文共享与缓存

🔄 工作流概览

📊 规范工作流（新功能）

只需一条命令即可完成自动化：

/spec-create feature-name "Description"

具体流程：

1. 需求 → 用户故事 + 接受准则
2. 设计 → 技术架构 + 图表
3. 任务 → 细粒度、适合代理执行的任务分解
4. 命令 → 自动生成的任务命令（可选）

执行任务：

# 手动控制
/spec-execute 1 feature-name
/feature-name-task-1        # 自动生成

🐛 Bug 修复工作流（快速修复）

/bug-create issue-name "Description"  # 记录 Bug
/bug-analyze                          # 查找根本原因
/bug-fix                             # 实施解决方案
/bug-verify                          # 确认修复结果

🎯 项目指导设置（项目上下文）

/spec-steering-setup  # 创建 product.md、tech.md、structure.md

🛠️ 命令参考

🎯 核心特性

🤖 智能任务执行

• 简化的任务实施流程
• 上下文感知的执行，拥有完整的规范上下文
• 基于代理的任务执行，由 spec-task-executor 完成

🧠 专用代理（可选）

4 个 AI 代理用于增强自动化能力：

核心工作流： spec-task-executor、spec-requirements-validator、spec-design-validator、spec-task-validator

注意： 代理是可选的——所有功能均可在内置回退机制下正常运行。

⚡ 全面的上下文优化（全新！）

• 通用上下文共享 - 指导文档、规范文档及模板文档均经过优化
• 减少 60-80% 的 token 数量 - 消除了所有文档类型之间重复获取内容的问题
• 三重优化命令 - get-steering-context、get-spec-context 和 get-template-context
• 智能文档处理 - Bug 文档直接读取（无冗余），模板文档批量加载（高冗余）
• 性能提升 - 缓存上下文后，所有工作流中的代理执行速度更快
• 自动回退 - 当优化不可用时，仍可通过单独的 get-content 保持可靠性
• 会话级缓存 - 智能检测文件变化并失效缓存

📊 实时仪表板

npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard

• 实时进度跟踪
• WebSocket 更新
• Git 集成
• 使用 Tailwind CSS 构建的现代化 UI

🔗 仪表板隧道（全新！）

通过临时 HTTPS URL，您可以安全地与外部利益相关者共享仪表板：

# 启动带隧道的仪表板
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard --tunnel

# 带密码保护
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard --tunnel --tunnel-password mySecret123

# 选择特定提供商
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard --tunnel --tunnel-provider cloudflare

隧道特点：

• 🔒 安全的 HTTPS URL - 可与经理、客户或远程团队成员共享仪表板
• 👁️ 只读访问权限 - 外部查看者无法修改任何项目数据
• 🔑 可选密码 - 可通过密码认证保护访问权限
• 🌐 多种提供商 - 自动在 Cloudflare 和 ngrok 之间切换
• 📊 使用情况分析 - 跟踪谁在何时访问了您的仪表板
• ⏰ 自动过期 - 当您停止仪表板时，隧道会自动关闭
• 🚀 无需配置 - 内置提供商即可开箱即用

📊 命令行选项

设置命令

# 在当前目录设置
npx @pimzino/claude-code-spec-workflow

# 在指定目录设置
npx @pimzino/claude-code-spec-workflow --project /path/to/project

# 强制覆盖现有文件
npx @pimzino/claude-code-spec-workflow --force

# 跳过确认提示
npx @pimzino/claude-code-spec-workflow --yes

# 测试设置
npx @pimzino/claude-code-spec-workflow test

仪表板命令

# 基本仪表板
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard

# 带隧道的仪表板（可对外共享）
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard --tunnel

# 完整隧道配置
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard \
  --tunnel \
  --tunnel-password mySecret123 \
  --tunnel-provider cloudflare \
  --port 3000 \
  --open

🎯 指导文档（新！）

指导文档提供了持久的项目上下文，用于指导所有规范的开发：

产品文档 (product.md)

• 产品愿景和目的
• 目标用户及其需求
• 关键功能和目标
• 成功指标

技术文档 (tech.md)

• 技术栈和框架
• 开发工具和实践
• 技术约束和要求
• 第三方集成

结构文档 (structure.md)

• 文件组织模式
• 命名规范
• 导入模式
• 代码组织原则

运行 /spec-steering-setup 来创建这些文档。Claude 将分析你的项目并帮助你定义这些标准。

🎨 功能

✅ 零配置

• 适用于任何项目，开箱即用
• 自动检测项目类型（Node.js、Python、Java 等）
• 验证 Claude Code 是否已安装

✅ 交互式设置

• 美观的 CLI 界面，带有进度指示器
• 安全确认提示
• 有用的错误信息和指导

✅ 智能文件管理

• 每个命令文件中都包含完整的流程说明
• 创建全面的目录结构
• 包含所有必要的模板和配置文件

✅ 专业品质

• 完全使用 TypeScript 实现，具有严格的类型检查
• 前端已转换为 TypeScript，以增强仪表盘开发
• 95% 以上的类型覆盖率，无隐式 any 类型
• 现代构建管道，支持 esbuild 打包和源映射
• 全面的错误处理
• 遵循 npm 最佳实践

✅ 指导文档集成

• 在所有规范中保持持久的项目上下文
• 自动与项目标准对齐
• 一致的代码生成
• 减少重复解释的需求

✅ TypeScript 仪表盘前端

• 类型安全的前端代码，具有全面的接口
• 实时 WebSocket 通信，支持类型化的消息处理
• Petite-vue 集成，带有自定义类型定义
• 构建管道，支持开发和生产版本打包
• 严格的空值检查 和现代 TypeScript 模式
• JSDoc 文档，为所有导出函数提供说明

🏗️ 设置后的项目结构

your-project/
├── .claude/
│   ├── commands/           # 14 个斜杠命令 + 自动生成
│   ├── steering/          # product.md、tech.md、structure.md
│   ├── templates/         # 文档模板
│   ├── specs/            # 生成的规范
│   ├── bugs/             # 错误修复流程
│   └── agents/           # AI 代理（默认启用）

🧪 测试

该包包含一个内置的测试命令：

# 在临时目录中测试设置
npx @pimzino/claude-code-spec-workflow test

📋 要求

• Node.js 16.0.0 或更高版本
• 已安装并配置好 Claude Code
• 任意项目目录

🔧 故障排除

常见问题

❓ 使用 NPX 后找不到命令

# 确保使用正确的包名称
npx @pimzino/claude-code-spec-workflow

❓ 设置失败并出现权限错误

# 尝试使用不同的目录权限
npx @pimzino/claude-code-spec-workflow --project ~/my-project

❓ 未检测到 Claude Code

# 首先安装 Claude Code
npm install -g @anthropic-ai/claude-code

调试信息

# 显示详细输出
DEBUG=* npx @pimzino/claude-code-spec-workflow

# 检查包版本
npx @pimzino/claude-code-spec-workflow --version

🌟 示例

基本用法

cd my-awesome-project
npx @pimzino/claude-code-spec-workflow
claude
# 输入：/spec-create user-dashboard "用户资料管理"

进阶用法

# 设置多个项目
for dir in project1 project2 project3; do
  npx @pimzino/claude-code-spec-workflow --project $dir --yes
done

🔧 TypeScript 开发

前端仪表盘开发

仪表盘前端完全使用 TypeScript 实现，以增强类型安全性和开发者体验：

类型定义

// 核心仪表盘类型
interface Project {
  path: string;
  name: string;
  level: number;
  hasActiveSession: boolean;
  specs: Spec[];
  bugs: Bug[];
  steeringStatus?: SteeringStatus;
}

// 带有区分联合类型的 WebSocket 消息类型
type WebSocketMessage = 
  | { type: 'initial'; data: InitialData }
  | { type: 'update'; data: UpdateData }
  | { type: 'error'; data: ErrorData }
  | { type: 'tunnel-status'; data: TunnelStatusData };

构建命令

# TypeScript 编译和打包
npm run build:frontend:dev   # 构建开发版前端
npm run build:frontend:prod  # 构建生产版前端（压缩版）
npm run watch:frontend       # 监视模式，自动重新构建
npm run typecheck:frontend   # 仅进行类型检查（不输出）
npm run typecheck           # 检查后端和前端的类型

# 开发工作流  
npm run dev:dashboard       # 启动仪表盘，支持热重载（前端 + 后端）
npm run dev:dashboard:backend-only  # 仅启动后端（用于前端调试）

# 完整构建流程
npm run build              # 完整构建：TypeScript + 前端 + 静态文件
npm run lint               # 使用自动修复功能检查 TypeScript 文件
npm run format             # 使用 Prettier 格式化代码

类型安全特性

• 严格 TypeScript 配置，包含空值检查
• 运行时类型验证，通过类型保护实现
• WebSocket 消息类型定义，用于实时更新
• 状态管理类型，适用于响应式 UI 组件
• 错误处理类型，采用 Result 模式
• Petite-vue 集成，提供自定义类型定义

类型使用示例

// 导入仪表板类型
import type { Project, WebSocketMessage, AppState } from './dashboard.types';

// 类型安全的项目处理
function selectProject(project: Project): void {
  console.log(`选择的项目：${project.name} (${project.specs.length} 个规格)`);
  
  // 安全的可选链属性访问
  const steeringCount = project.steeringStatus?.totalDocs ?? 0;
  if (steeringCount > 0) {
    console.log(`转向文档数：${steeringCount}`);
  }
}

// 使用区分联合类型的 WebSocket 消息处理
function handleMessage(message: WebSocketMessage): void {
  switch (message.type) {
    case 'initial':
      // TypeScript 知道 data 是 InitialData 类型
      console.log(`加载了 ${message.data.projects.length} 个项目`);
      break;
    case 'update':
      // TypeScript 知道 data 是 UpdateData 类型
      console.log(`更新了项目：${message.data.projectPath}`);
      break;
    case 'error':
      // TypeScript 知道 data 是 ErrorData 类型
      console.error(`错误：${message.data.message}`);
      break;
  }
}

// 运行时验证的类型保护函数
function isValidProject(obj: unknown): obj is Project {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    'path' in obj &&
    'name' in obj &&
    'specs' in obj &&
    Array.isArray((obj as Project).specs)
  );
}

// 用于错误处理的 Result 类型
type Result<T, E = Error> = 
  | { success: true; data: T }
  | { success: false; error: E };

function parseProjectData(data: unknown): Result<Project> {
  if (isValidProject(data)) {
    return { success: true, data };
  }
  return { success: false, error: new Error('无效的项目数据') };
}

开发指南

• 对所有导出函数进行 JSDoc 文档注释
• 维持 95% 以上的类型覆盖率（无隐式 any 类型）
• 使用 现代 TypeScript 模式（可选链、空值合并等）
• 优先使用 类型保护 而不是类型断言
• 使用 接口定义对象结构，用联合类型表示区分联合
• 采用 Result 模式 处理错误
• 对外部数据进行 运行时类型验证

📚 文档

• 完整文档 https://github.com/pimzino/claude-code-spec-workflow#readme
• 隧道功能指南 ./docs/tunnel-feature.md - 隧道功能的全面文档
• 隧道示例 ./examples/tunnel/ - 可直接使用的隧道脚本
• Claude Code 文档 https://docs.anthropic.com/claude-code
• TypeScript API 参考 ./docs/typescript-api.md - 根据 JSDoc 注释生成

🤝 贡献

欢迎贡献！请参阅我们的 贡献指南。

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE。

🏷️ 更改记录

版本历史请查看 CHANGELOG.md。

🚦 何时使用什么

🚀 安装与设置

安装

# 全局安装（推荐）
npm install -g @pimzino/claude-code-spec-workflow

# 验证安装
claude-code-spec-workflow --version

设置选项

# 基本设置
claude-code-spec-workflow

# 高级选项
claude-code-spec-workflow --project /path --force --yes

在设置过程中，您可以选择：

• ✅ 启用代理？ 增强自动化功能 vs 更简单的设置
• ✅ 项目分析 自动检测框架和模式

📚 示例

建议：使用 Claude Opus 4 生成规范文档 '/spec-create'，然后使用 Claude Sonnet 4 进行实现，即 '/spec-execute' 或 '/{spec-name}-task-'。

# 1. 全局安装（一次）
npm install -g @pimzino/claude-code-spec-workflow

# 2. 设置项目（一次）
cd my-project
claude-code-spec-workflow

# 3. 创建指导文档（推荐）
claude
/spec-steering-setup

# 4. 创建功能规范
/spec-create user-authentication "安全登录系统"

# 5. 执行任务
/spec-execute 1 user-authentication

# 6. 监控进度
/spec-status user-authentication

/bug-create login-timeout "用户登录后过快被登出"
/bug-analyze
/bug-fix
/bug-verify

⚡ 上下文优化命令

该包包含针对各类文档高效加载的优化命令：

get-steering-context

一次性加载所有指导文档以共享上下文：

claude-code-spec-workflow get-steering-context

输出：格式化的 Markdown，包含所有指导文档（product.md、tech.md、structure.md）

get-spec-context

一次性加载所有规范文档以共享上下文：

claude-code-spec-workflow get-spec-context feature-name

输出：格式化的 Markdown，包含所有规范文档（requirements.md、design.md、tasks.md）

get-template-context

按类别加载模板以共享上下文：

# 加载所有模板
claude-code-spec-workflow get-template-context

# 加载特定类别的模板
claude-code-spec-workflow get-template-context spec    # 规范模板
claude-code-spec-workflow get-template-context bug     # Bug 模板
claude-code-spec-workflow get-template-context steering # 指导模板

输出：格式化的 Markdown，包含请求的模板

智能文档处理

• 高冗余文档（指导文档、规范、模板）：使用优化的批量加载
• 低冗余文档（Bug 报告）：直接读取文件以简化操作
• 选择性委派：主代理加载完整上下文，但只将相关部分传递给子代理
• 单个文件：对于特殊情况，继续使用 get-content 命令

优势

• 与单独加载文件相比，减少60%-80%的令牌使用量
• 在所有工作流中利用缓存上下文实现更快的执行速度
• 在需要时自动回退到单独的 get-content 操作
• 基于会话的缓存机制，并具备智能的文件变更检测功能

层次化上下文管理

系统采用了一种层次化的上下文管理策略，以实现最高效率：

主代理（如 /spec-execute、/spec-create 等命令）：

• 在开始时通过优化后的命令一次性加载全部上下文
• 存储完整的上下文，用于任务协调和决策制定
• 向子代理分发选择性上下文，无需重复加载

子代理（如 spec-task-executor 等代理）：

• 优先级1：使用任务指令中提供的上下文（指导信息、规格说明、任务详情）
• 优先级2：若未提供上述内容，则回退至加载上下文
• 绝不重复加载已由主代理提供的上下文

上下文分发模式：

主代理加载：指导信息 + 完整规格 + 任务详情
↓ 分配给子代理的内容：
├── 完整的指导信息上下文
├── 选择性的规格上下文（仅包含需求和设计部分）
├── 具体的任务详情
└── 明确指示：“请勿再次加载上下文”

这种方法消除了冗余加载，同时确保每个代理都拥有其所需的精确上下文。

🛟 故障排除

# 首先全局安装
npm install -g @pimzino/claude-code-spec-workflow

# 然后使用该命令
claude-code-spec-workflow

npm install -g @anthropic-ai/claude-code

claude-code-spec-workflow --project ~/my-project

📋 系统要求

• Node.js 16.0.0及以上版本
• 已安装 Claude Code
• 任意项目目录

🔗 链接

• 完整文档
• Claude Code 文档
• 提交问题

📄 许可证与致谢

MIT 许可证 - LICENSE

由 Pimzino 用心打造

特别感谢：

• @pimzino - 初始搭建
• @boundless-oss - 指导文档
• @mquinnv - 仪表盘功能

技术支持： Claude Code • Mermaid • TypeScript

claude-code-spec-workflow 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 版本 16.0.0 或更高。
• Claude Code: 必须已安装并配置好全局命令。

  npm install -g @anthropic-ai/claude-code
  

• 项目目录: 准备好一个需要开发的现有项目文件夹。

💡 国内加速提示：如果 npm 下载缓慢，建议临时切换至国内镜像源（如淘宝镜像）：

npm config set registry https://registry.npmmirror.com

安装步骤

只需两步即可完成全局安装与项目初始化：

1. 全局安装工具包 在终端执行以下命令安装工作流系统：

   npm i -g @pimzino/claude-code-spec-workflow
   

2. 初始化项目 进入您的项目根目录，运行设置命令。该命令会自动创建 .claude/ 目录结构、生成斜杠命令文件及文档模板：

   claude-code-spec-workflow
   

   按提示确认即可，若需跳过确认可添加 --yes 参数。

基本使用

安装完成后，您可以在项目中启动 claude 交互界面，直接使用内置的自动化工作流命令。

1. 启动交互模式

在项目目录下输入：

claude

2. 新功能开发流程 (Spec Workflow)

使用一条命令即可自动完成从需求分析、架构设计到任务拆解的全过程：

/spec-create user-dashboard "实现用户个人资料管理功能"

执行后，系统将生成需求文档、技术设计图及原子化任务列表。

执行具体任务： 您可以手动执行特定任务，或使用自动生成的命令：

/spec-execute 1 user-dashboard
# 或直接使用自动生成的命令
/user-dashboard-task-1

3. 缺陷修复流程 (Bug Fix Workflow)

针对 Bug 修复提供标准化的四步闭环：

/bug-create login-error "用户登录时出现 500 错误"  # 记录问题
/bug-analyze                                      # 分析根本原因
/bug-fix                                          # 实施修复方案
/bug-verify                                       # 验证修复结果

4. 项目上下文引导 (可选)

首次使用时，建议运行此命令让 AI 分析项目并生成产品、技术及结构规范文档，以提升后续代码生成的一致性：

/spec-steering-setup

5. 可视化监控 (Dashboard)

如需在浏览器中实时查看任务进度和状态，可在另一终端窗口运行：

npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard