项目启动器

一个通用的 Claude Code 工作流插件，为任何软件项目提供专业化的智能体、技能、钩子和输出样式。兼容 skills.sh — 可与 Claude Code、Cursor、Codex 以及 35 多种 AI 智能体协同工作。

---

快速入门

选项 1：skills.sh（推荐 — 适用于任何智能体）

npx skills add CloudAI-X/claude-workflow-v2

会自动将技能安装到 Claude Code、Cursor、Codex、Windsurf、Cline 等 35 多种 AI 智能体中。

选项 2：npx（Claude Code — 完整插件）

npx install-claude-workflow-v2@latest

安装完整的插件：包括智能体、命令、技能和钩子。

选项 3：CLI（单次会话）

# 克隆插件
git clone https://github.com/CloudAI-X/claude-workflow-v2.git

# 使用插件运行 Claude Code
claude --plugin-dir ./claude-workflow-v2

选项 4：智能体 SDK

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Hello",
  options: {
    plugins: [{ type: "local", path: "./claude-workflow-v2" }],
  },
})) {
  // 插件中的命令、智能体和技能现已可用
}

选项 5：永久安装

# 从市场安装（待上线时）
claude plugin install project-starter

# 或从本地目录安装
claude plugin install ./claude-workflow-v2

验证安装

加载插件后，请验证其是否正常工作：

> /plugin

使用 Tab 键切换到 Installed，您应能看到 project-starter 列出。再切换到 Errors，此处应为空（无错误）。

此时以下命令将可用：

/project-starter:architect    # 架构优先模式
/project-starter:rapid        # 快速交付模式
/project-starter:commit       # 自动生成提交信息
/project-starter:verify-changes  # 多智能体验证

---

包含内容

组件	数量	描述
智能体	7	用于代码审查、调试、安全等的专业子智能体
命令	26	用于工作流、输出样式、规划和入职的斜杠命令
技能	14	支持按需加载上下文的知识领域
钩子	14	用于格式化、安全、指标统计和通知的自动化脚本

---

使用示例

命令实战

自动提交更改：

> /project-starter:commit

正在查看暂存的更改...
✓ 创建了提交：feat(auth): 添加 JWT 刷新令牌端点

完整 Git 工作流：

> /project-starter:commit-push-pr

✓ 提交：feat: 添加用户仪表板
✓ 推送到 origin/feature/dashboard
✓ 创建了 PR #42：https://github.com/you/repo/pull/42

发布前验证：

> /project-starter:verify-changes

正在启动验证智能体...
├─ build-validator: ✓ 构建通过
├─ test-runner: ✓ 42 个测试全部通过
├─ lint-checker: ⚠ 2 条警告（非阻塞）
└─ security-scanner: ✓ 未发现漏洞

可以发布！

智能体实战

智能体会根据您的请求自动启动：

您说： “登录功能坏了，用户收到 401 错误”

[调试智能体已激活]
→ 检查认证中间件... 发现问题
→ 生产环境中的令牌验证使用了错误的密钥
→ 解决方案：更新 .env.production 中的 AUTH_SECRET

您说： “请审查我的更改”

[代码审查智能体已激活]
→ 正在分析 3 个修改文件...
✓ 逻辑正确
⚠ 第 42 行缺少空值检查
⚠ 建议在此端点添加限流机制

您说： “为 API 添加认证功能”

[协调智能体已激活]
→ 将任务分解为子任务：
  1. 设计认证架构（启动架构师）
  2. 实现 JWT 中间件
  3. 添加登录/注册端点
  4. 编写测试用例（启动测试架构师）
  5. 更新 API 文档（启动文档编写者）

技能实战

技能会自动提供领域知识：

您问： “支付服务应该如何设计？”

[设计架构技能生效]
→ 推荐采用六边形架构
→ 将支付服务商作为适配器
→ 核心业务层与基础设施层隔离

您问： “如何让这个端点更快？”

[性能优化技能生效]
→ 添加数据库索引
→ 实施响应缓存
→ 对大量结果使用分页

钩子实战

钩子会在特定事件发生时自动触发：

安全拦截（编辑前）：

⛔ 已阻止：检测到潜在密钥
   文件：src/config.ts，第 5 行
   模式：API 密钥 (sk-...)

   请移除密钥，并使用环境变量。

自动格式化（编辑后）：

✓ 使用 Prettier 格式化：src/components/Button.tsx
✓ 使用 Black 格式化：scripts/deploy.py

桌面通知：

🔔 “Claude 等待输入” - 当等待您的回复时
🔔 “任务已完成” - 当任务结束时

---

命令参考

所有命令均采用 /project-starter:<命令> 的格式。

输出样式

命令	模式
/project-starter:architect	系统设计模式 - 先设计架构再写代码
/project-starter:rapid	快速开发模式 - 快速交付并迭代
/project-starter:mentor	教学模式 - 解释“为什么”
/project-starter:review	代码审查模式 - 严格把控质量

Git 工作流（内循环）

命令	用途
/project-starter:commit	自动生成规范化的提交信息
/project-starter:commit-push-pr	提交 → 推送 → 创建 PR（完整流程）
/project-starter:quick-fix	快速修复 Lint 或类型错误
/project-starter:add-tests	为最近的更改生成测试用例
/project-starter:lint-fix	自动修复所有 Lint 问题
/project-starter:sync-branch	与主分支同步（变基或合并）
/project-starter:summarize-changes	生成站会或 PR 摘要

验证

命令	用途
/project-starter:verify-changes	多子代理对抗式验证
/project-starter:validate-build	构建流程验证
/project-starter:run-tests	分层测试执行
/project-starter:lint-check	代码质量检查
/project-starter:security-scan	安全漏洞检测
/project-starter:code-simplifier	实施后清理

规划与重构

命令	用途
/project-starter:plan	持久化 PLAN.md 文件，跟踪各阶段进展
/project-starter:refactor-guided	四阶段系统性重构，确保安全
/project-starter:dependency-upgrade	安全升级依赖项，并支持回滚

新手引导与知识积累

命令	用途
/project-starter:tutorial	针对新用户的交互式引导教程
/project-starter:bootstrap-repo	10个子代理并行探索代码库
/project-starter:save-session-learnings	将会话中的发现持久化到文档中
/project-starter:metrics	查看子代理性能指标

---

子代理

子代理是 Claude 根据您的任务自动创建的专用子代理。

子代理	用途	自动触发条件
orchestrator	协调多步骤任务	“改进”、“增强”、“构建”、“架构设计”、复杂任务
code-reviewer	审查代码质量	“评审”、“PR 审核”、“代码风格检查”、代码变更
debugger	系统性排查 bug	错误、崩溃、内存泄漏、超时、竞态条件
docs-writer	编写技术文档	README、变更日志、迁移指南、发布说明
security-auditor	检测安全漏洞	认证、加密、敏感信息、OAuth、JWT、CORS
refactorer	改进代码结构	技术债务、代码异味、降低复杂度
test-architect	设计测试策略	测试计划、模拟、不稳定测试、集成/端到端测试

---

技能

技能是 Claude 在相关场景下自主使用的知识领域。

技能	领域
analyzing-projects	理解代码库结构和模式
designing-tests	单元测试、集成测试、端到端测试方法
designing-architecture	清晰架构、六边形架构等
optimizing-performance	加速应用，识别瓶颈
managing-git	版本控制，遵循规范提交
designing-apis	REST/GraphQL 模式及最佳实践
parallel-execution	多子代理并行执行任务模式
web-design-guidelines	自包含 UI 审计（A11Y、PERF、RD、SEC、I18N）
vercel-react-best-practices	React/Next.js 性能优化（45 条规则）
convex-backend	Convex 后端开发（函数、模式等）
database-design	数据库模式设计、索引优化、查询优化
devops-infrastructure	Docker、CI/CD、部署、基础设施即代码、监控
error-handling	错误模式、结构化日志记录、重试/熔断机制
security-patterns	认证、RBAC、敏感信息、CORS、限流、HTTP 头部

---

钩子

钩子会在特定事件发生时自动运行。

钩子	触发条件	动作
安全扫描	编辑/写入	阻止包含潜在敏感信息的提交
文件保护	编辑/写入	阻止对锁定文件、.env、.git 的编辑
自动格式化	编辑/写入	根据文件类型运行 prettier/black/gofmt
TypeScript 检查	编辑/写入	对 .ts/.tsx 文件运行 tsc --noEmit
提交前检查	Bash 脚本	检测调试语句及临时标记
分支保护	Bash 脚本	警告对保护分支的提交
命令日志记录	Bash 脚本	日志记录至 .claude/command-history.log
环境检查	会话开始	验证 Node.js、Python、Git 是否正常
提示分析	用户提示	推荐合适的子代理
自动验证	任务完成	运行测试/代码风格检查，报告结果
文档更新建议	任务完成	建议更新 CLAUDE.md 以反映更改
会话指标	任务完成	将会话遥测数据记录到指标文件中
输入提醒	需要输入	桌面通知
完成提醒	任务完成	桌面通知

---

示例

有关详细的多子代理编排示例，请参阅 examples/ 目录：

示例	描述
全面代码审查	6个子代理按顺序协作，进行彻底的代码分析

每个示例包括：

• README.md - 概述及快速入门
• workflow.md - 具体使用提示
• verification.md - 如何验证其有效性
• sample-outputs/ - 子代理输出示例

---

配置

为项目添加权限

将权限模板复制到您的项目中：

mkdir -p /path/to/your/project/.claude
cp templates/settings.local.json.template /path/to/your/project/.claude/settings.local.json

这将预先允许常用的安全命令，避免每次操作都需确认。

添加团队规范

将 CLAUDE.md 模板复制到你的项目根目录：

cp templates/CLAUDE.md.template /path/to/your/project/CLAUDE.md

然后根据你的需求进行自定义：

• 包管理器命令
• 测试/构建/代码检查命令
• 代码规范
• 架构决策

MCP 服务器

复制 MCP 模板以启用 Slack、GitHub、Sentry 等集成：

cp templates/mcp.json.template /path/to/your/project/.mcp.json

然后配置你想要使用的服务器的环境变量。

GitHub Action（在 PR 中使用 @.claude）

通过安装 GitHub Action，使 Claude 能够回复 PR 评论：

# 在你的仓库中
claude /install-github-action

这将启用以下功能：

• 在 PR 评论中标记 @claude 以获取代码建议
• 在代码审查期间自动更新 CLAUDE.md
• Claude 会自动回复审查反馈

PR 评论示例：

@claude 请为邮箱字段添加输入验证

团队工作流程提示： 使用 @claude 来根据代码审查中的经验更新 CLAUDE.md：

@claude 在 CLAUDE.md 中添加一条注释，说明我们在调用 API 之前应始终验证邮箱格式

---

扩展插件

添加自定义命令

在 commands/ 目录下创建 .md 文件：

---
allowed-tools: Bash(git:*), Read, Write
description: 此命令的作用
argument-hint: [可选参数]
---

[命令的具体操作步骤]

添加自定义代理

在 agents/ 目录下创建 .md 文件：

---
name: my-agent
description: 它的功能。在 [触发条件] 时主动使用。
tools: Read, Write, Edit, Bash
model: sonnet
---

[代理的操作指南]

添加自定义技能

在 skills/ 目录下创建子目录，并在其中包含一个 SKILL.md 文件：

---
name: my-skill
description: 指导 [领域]。在 [触发条件] 时使用。
---

[技能相关的知识和模式]

---

插件结构

claude-workflow/
├── .claude-plugin/
│   ├── plugin.json           # 必需：插件清单
│   └── marketplace.json      # 可选：市场元数据
├── agents/                   # 7 个专业代理
│   ├── orchestrator.md
│   ├── code-reviewer.md
│   ├── debugger.md
│   ├── docs-writer.md
│   ├── security-auditor.md
│   ├── refactorer.md
│   └── test-architect.md
├── commands/                 # 26 个斜杠命令
│   ├── architect.md          # 输出样式
│   ├── rapid.md
│   ├── mentor.md
│   ├── review.md
│   ├── commit.md             # Git 工作流
│   ├── commit-push-pr.md
│   ├── quick-fix.md
│   ├── add-tests.md
│   ├── lint-fix.md
│   ├── sync-branch.md
│   ├── summarize-changes.md
│   ├── verify-changes.md     # 验证
│   ├── validate-build.md
│   ├── run-tests.md
│   ├── lint-check.md
│   ├── security-scan.md
│   ├── code-simplifier.md
│   ├── parallel-review.md    # 并行
│   ├── parallel-analyze.md
│   ├── plan.md               # 规划与重构
│   ├── refactor-guided.md
│   ├── dependency-upgrade.md
│   ├── tutorial.md           # 入职培训与知识普及
│   ├── bootstrap-repo.md
│   ├── save-session-learnings.md
│   └── metrics.md
├── skills/                   # 14 个知识领域
│   ├── analyzing-projects/
│   ├── convex-backend/
│   ├── database-design/
│   ├── designing-apis/
│   ├── designing-architecture/
│   ├── designing-tests/
│   ├── devops-infrastructure/
│   ├── error-handling/
│   ├── managing-git/
│   ├── optimizing-performance/
│   ├── parallel-execution/
│   ├── security-patterns/
│   ├── vercel-react-best-practices/
│   └── web-design-guidelines/
├── hooks/
│   ├── hooks.json            # 钩子配置
│   └── 14 个自动化脚本     # 工具前后、会话、指标、通知等
├── templates/                # 用户可复制的模板
│   ├── CLAUDE.md.template
│   ├── settings.json.template
│   ├── settings.local.json.template
│   └── mcp.json.template
├── CLAUDE.md                 # 插件开发指南
└── README.md

---

系统要求

• Claude Code v1.0.33 或更高版本
• Python 3（用于钩子脚本）
• Node.js（可选，用于 npm 命令）
• Git（用于版本控制功能）

---

多代理兼容性（skills.sh）

此仓库与 skills.sh——通用代理技能平台——完全兼容。我们的 14 种技能可与 38+ 个 AI 编码代理 一起使用：

代理	安装方法
Claude Code	npx skills add CloudAI-X/claude-workflow-v2 或完整插件安装
Cursor	npx skills add CloudAI-X/claude-workflow-v2
Codex	npx skills add CloudAI-X/claude-workflow-v2
Windsurf	npx skills add CloudAI-X/claude-workflow-v2
Cline	npx skills add CloudAI-X/claude-workflow-v2
35+ 其他	npx skills add CloudAI-X/claude-workflow-v2

注意： npx skills add 只会安装 技能。若要获得完整的 Claude Code 体验（代理、命令、钩子），请使用 npx install-claude-workflow-v2@latest。

---

贡献

欢迎贡献！请参阅 CONTRIBUTING.md。

1. 分支仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: 添加超赞功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

---

星标历史

致谢

• 插件由 @cloudxdev 创建
• 工作流模式灵感来源于 Boris Cherny（Claude Code 的创造者）

许可证

MIT - 详情请参阅 LICENSE。

claude-workflow-v2 快速上手指南

claude-workflow-v2 是一个通用的 Claude Code 工作流插件，提供专用的智能体（Agents）、技能（Skills）、钩子（Hooks）和输出风格，适用于任何软件项目。它兼容 Claude Code、Cursor、Codex 等 35+ 种 AI 编程助手。

环境准备

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

• 操作系统：Linux, macOS, 或 Windows (WSL2 推荐)
• 核心依赖：
  • Node.js (建议 v18+)
  • Git
• AI 客户端（任选其一）：
  • Claude Code (官方 CLI，推荐)
  • Cursor IDE
  • 其他支持 skills.sh 或本地插件加载的 AI 代理

注意：本工具主要设计用于命令行环境或集成开发环境中的 AI 对话界面。

安装步骤

您可以根据使用习惯选择以下任意一种安装方式。

方式一：通用安装（推荐）

适用于 Claude Code、Cursor、Codex、Windsurf、Cline 等 35+ 种 AI 代理。此方式通过 skills.sh 自动配置。

npx skills add CloudAI-X/claude-workflow-v2

方式二：完整插件安装（仅限 Claude Code）

如果您使用的是原生 Claude Code CLI，并希望安装包含所有智能体、命令、技能和钩子的完整版本：

npx install-claude-workflow-v2@latest

方式三：临时会话使用（CLI）

无需永久安装，仅在当前会话中加载插件：

# 1. 克隆仓库
git clone https://github.com/CloudAI-X/claude-workflow-v2.git

# 2. 带插件启动 Claude Code
claude --plugin-dir ./claude-workflow-v2

验证安装

启动 AI 助手后，输入以下命令检查插件状态：

> /plugin

• 切换到 Installed 标签页，应能看到 project-starter。
• 切换到 Errors 标签页，应为空（无报错）。

基本使用

安装成功后，您可以直接使用 /project-starter:<命令> 格式的指令来增强开发流程。

1. 切换工作模式

根据任务类型选择合适的输出风格：

• 架构优先模式（适合新项目或重构）：

  > /project-starter:architect
  

• 快速交付模式（适合快速迭代）：

  > /project-starter:rapid
  

• 代码审查模式（严格质量检查）：

  > /project-starter:review
  

2. 自动化 Git 工作流

自动处理提交信息生成、推送和 PR 创建：

• 自动生成规范提交信息：

  > /project-starter:commit
  

  输出示例：✓ Created commit: feat(auth): add JWT refresh token endpoint

• 完整流程（提交 -> 推送 -> 创建 PR）：

  > /project-starter:commit-push-pr
  

3. 多智能体验证

在发布前自动调用多个子智能体进行构建、测试、Lint 和安全扫描：

> /project-starter:verify-changes

系统将自动执行：构建验证、测试运行、代码检查和安全扫描，并汇总报告。

4. 智能体自动触发

您无需手动调用智能体，只需在自然语言描述中提及相关任务，系统会自动激活对应的专用智能体：

• 场景：修复 Bug

  • 用户输入："登录功能坏了，用户收到 401 错误"
  • 系统反应：自动激活 debugger 智能体排查认证中间件和 Token 问题。

• 场景：代码审查

  • 用户输入："审查我的更改"
  • 系统反应：自动激活 code-reviewer 智能体分析文件变更，指出逻辑错误或潜在风险。

• 场景：复杂功能开发

  • 用户输入："为 API 添加认证功能"
  • 系统反应：自动激活 orchestrator 智能体，拆解任务并协调 architect、test-architect 等子智能体并行工作。

5. 自动化钩子（Hooks）

以下操作将在后台自动运行，无需额外指令：

• 安全拦截：尝试提交包含 API Key 或_SECRET 的代码时会被自动阻断。
• 自动格式化：保存或编辑文件时，自动运行 prettier 或 black 进行格式化。
• 类型检查：编辑 TypeScript 文件时自动运行 tsc --noEmit。