🚀 概览与安装 >>

• Claude Code Spec Workflow：为 Claude Code 提供规范驱动的自动化工作流插件。
• 核心路径：新功能采用「需求 → 设计 → 任务 → 实现」，缺陷采用「报告 → 分析 → 修复 → 验证」。
• 版本提示：官方维护重点已迁移到 spec-workflow-mcp，本版本仍适合纯 Claude Code 场景与存量项目。

全局安装与项目初始化

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

# 在项目目录中生成 .claude 工作流结构
cd <your-project>
claude-code-spec-workflow

# 启动 Claude Code 并创建 Steering 文档
claude
/spec-steering-setup

📊 Spec 工作流（新功能） >>

• /spec-create <name> \"描述\"：一条命令完成需求、设计、任务拆分以及可选的任务命令生成。
• /spec-execute <task-id> <name>：按任务编号执行，实现可控的逐步开发与回溯。
• /spec-status [<name>]：查看单个规格或全部规格的状态与任务完成度。
• /spec-list：列出所有规格，便于在多特性之间快速切换上下文。
• /<name>-task-<id>：为每个任务自动生成的命令，适合精细控制与重复执行。

典型新功能开发流程

# 1. 为新特性创建规格
/spec-create user-auth \"安全登录系统\"

# 2. 查看规格与任务拆分情况
/spec-status user-auth

# 3. 按任务编号执行实现
/spec-execute 1 user-auth
/spec-execute 2 user-auth

# 4. 或使用自动生成的任务命令
/user-auth-task-1
/user-auth-task-2

🐛 Bug Fix 工作流 >>

• /bug-create <name> \"描述\"：记录缺陷的现象、复现步骤与期望行为。
• /bug-analyze：让 Claude Code 分析根因并定位可能出错的代码区域。
• /bug-fix：在上下文就绪后自动生成并应用修复方案。
• /bug-verify：根据用例与检查点验证修复是否生效。
• /bug-status [<name>]：查看当前或指定缺陷的处理进度。

典型缺陷修复流程

# 1. 登记并结构化描述问题
/bug-create login-timeout \"用户登录后过快被登出\"

# 2. 分析根因
/bug-analyze

# 3. 应用修复
/bug-fix

# 4. 验证修复结果
/bug-verify
/bug-status login-timeout

🛠 CLI 与仪表盘命令 >>

项目初始化与测试

# 在当前目录生成工作流文件
claude-code-spec-workflow

# 使用 npx 在指定目录初始化
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

🎯 Steering 文档与项目上下文 >>

• product.md：记录产品愿景、目标用户、核心特性与成功指标。
• tech.md：记录技术栈、开发工具、技术约束与关键三方集成。
• structure.md：约定目录结构、命名规范、导入模式与代码组织原则。

创建与维护 Steering 文档

# 让 Claude Code 帮你梳理项目上下文
/spec-steering-setup

⚡ 上下文优化命令 >>

批量加载 Steering / Spec / 模板上下文

# 一次性加载所有 Steering 文档
claude-code-spec-workflow get-steering-context

# 按特性名称加载规格文档
claude-code-spec-workflow get-spec-context feature-name

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

# 仅加载指定模板类别
claude-code-spec-workflow get-template-context spec     # 规格模板
claude-code-spec-workflow get-template-context bug      # 缺陷模板
claude-code-spec-workflow get-template-context steering # Steering 模板

智能上下文管理与收益

- Steering / Spec / 模板等高冗余文档通过批量加载减少重复读取
- Bug 文档仍采用直接读取，保持简单清晰
- 主代理（如 /spec-create、/spec-execute）一次性加载全量上下文，再向子代理按需下发
- 子代理优先使用已提供的上下文，不重复调用 get-* 命令
- 相比逐文件加载，可节省约 60–80% token，并提升执行速度

🌟 实战示例与推荐组合 >>

新功能开发（Spec 模式）

cd my-awesome-project
claude-code-spec-workflow
claude
/spec-steering-setup
/spec-create user-dashboard \"用户仪表盘\"
/spec-execute 1 user-dashboard
/spec-status user-dashboard

多项目批量启用工作流

for dir in project1 project2 project3; do
  npx @pimzino/claude-code-spec-workflow --project $dir --yes
done