create-vibe-workflow 0.1.0 → 0.2.0

package/templates/rules/coding-style.md

@@ -1,117 +1,156 @@
----
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "**/*.js"
-  - "**/*.jsx"
----
-# TypeScript/JavaScript Coding Style
-
-> 本文件是 TypeScript/JavaScript 项目的代码风格规范。
-
-## Types and Interfaces
-
-Use types to make public APIs, shared models, and component props explicit, readable, and reusable.
-
-### Public APIs
-
-- Add parameter and return types to exported functions, shared utilities, and public class methods
-- Let TypeScript infer obvious local variable types
-- Extract repeated inline object shapes into named types or interfaces
-
-```typescript
-// WRONG: Exported function without explicit types
-export function formatUser(user) {
-  return `${user.firstName} ${user.lastName}`
-}
-
-// CORRECT: Explicit types on public APIs
-interface User {
-  firstName: string
-  lastName: string
-}
-
-export function formatUser(user: User): string {
-  return `${user.firstName} ${user.lastName}`
-}
-```
-
-### Interfaces vs. Type Aliases
-
-- Use `interface` for object shapes that may be extended or implemented
-- Use `type` for unions, intersections, tuples, mapped types, and utility types
-- Prefer string literal unions over `enum` unless an `enum` is required for interoperability
-
-### Avoid `any`
-
-- Avoid `any` in application code
-- Use `unknown` for external or untrusted input, then narrow it safely
-- Use generics when a value's type depends on the caller
-
-```typescript
-// WRONG: any removes type safety
-function getErrorMessage(error: any) {
-  return error.message
-}
-
-// CORRECT: unknown forces safe narrowing
-function getErrorMessage(error: unknown): string {
-  if (error instanceof Error) {
-    return error.message
-  }
-  return 'Unexpected error'
-}
-```
-
-## Immutability
-
-Use spread operator for immutable updates:
-
-```typescript
-// WRONG: Mutation
-function updateUser(user: User, name: string): User {
-  user.name = name // MUTATION!
-  return user
-}
-
-// CORRECT: Immutability
-function updateUser(user: Readonly<User>, name: string): User {
-  return { ...user, name }
-}
-```
-
-## Error Handling
-
-Use async/await with try-catch and narrow unknown errors safely:
-
-```typescript
-async function loadUser(userId: string): Promise<User> {
-  try {
-    return await riskyOperation(userId)
-  } catch (error: unknown) {
-    logger.error('Operation failed', error)
-    throw new Error(getErrorMessage(error))
-  }
-}
-```
-
-## Input Validation
-
-Use Zod for schema-based validation and infer types from the schema:
-
-```typescript
-import { z } from 'zod'
-
-const userSchema = z.object({
-  email: z.string().email(),
-  age: z.number().int().min(0).max(150)
-})
-
-type UserInput = z.infer<typeof userSchema>
-const validated: UserInput = userSchema.parse(input)
-```
-
-## Console.log
-
-- No `console.log` statements in production code
-- Use proper logging libraries instead
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# TypeScript / JavaScript 编码规范
+
+> 本文件是项目的代码风格规范。所有生成的代码都应遵循这些规则。
+
+## 类型系统
+
+### 公共 API
+- 导出函数、共享工具类、公共类方法必须添加参数和返回类型
+- 局部变量让 TypeScript 自动推断
+- 重复的内联对象形状应提取为命名类型或接口
+
+```typescript
+// ❌ 导出函数没有显式类型
+export function formatUser(user) {
+  return `${user.firstName} ${user.lastName}`
+}
+
+// ✅ 显式类型
+interface User { firstName: string; lastName: string }
+export function formatUser(user: User): string {
+  return `${user.firstName} ${user.lastName}`
+}
+```
+
+### Interface vs Type
+- 可能需要扩展或实现的对象形状 → 用 `interface`
+- 联合、交叉、元组、映射类型 → 用 `type`
+- 优先用字符串字面量联合代替 `enum`（除非需要互操作性）
+
+### 禁止 `any`
+- 应用代码中避免使用 `any`
+- 外部/不可信输入用 `unknown`，然后安全收窄
+- 依赖调用者决定类型的场景用泛型
+
+```typescript
+// ❌ any 破坏了类型安全
+function getErrorMessage(error: any) { return error.message }
+
+// ✅ unknown 强制安全收窄
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message
+  return 'Unexpected error'
+}
+```
+
+## 不可变性
+
+使用展开运算符进行不可变更新：
+
+```typescript
+// ❌ 直接修改（Mutation）
+function updateUser(user: User, name: string): User {
+  user.name = name
+  return user
+}
+
+// ✅ 不可变更新
+function updateUser(user: Readonly<User>, name: string): User {
+  return { ...user, name }
+}
+```
+
+## 错误处理
+
+使用 async/await + try-catch + 安全的错误收窄：
+
+```typescript
+async function loadUser(userId: string): Promise<User> {
+  try {
+    return await riskyOperation(userId)
+  } catch (error: unknown) {
+    logger.error('操作失败', error)
+    throw new Error(getErrorMessage(error))
+  }
+}
+```
+
+> **业务层统一错误类（AppError / NotFoundError / ValidationError）及使用示例见 `.claude/rules/patterns.md` § 错误处理统一模式**
+> 本节专注底层错误收窄技巧，patterns.md 定义上层错误分类体系。
+
+## 输入校验
+
+使用 Zod 做 schema 驱动的校验，并从 schema 推断类型：
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  email: z.string().email(),
+  age: z.number().int().min(0).max(150)
+})
+
+type UserInput = z.infer<typeof userSchema>
+const validated: UserInput = userSchema.parse(input)
+```
+
+## 命名规范
+
+| 类别 | 规范 | 示例 |
+|------|------|------|
+| 文件名 | kebab-case | `user-service.ts` |
+| 变量/函数 | camelCase | `getUserById` |
+| 类/接口/类型 | PascalCase | `UserService` |
+| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| 枚举值 | UPPER_SNAKE_CASE | `Role.ADMIN` |
+| Boolean 前缀 | is/has/can/should | `isActive`, `hasPermission` |
+
+## 文件组织
+
+```
+src/
+├── modules/
+│   └── {module-name}/
+│       ├── {module}.module.ts     # 模块入口
+│       ├── {module}.controller.ts # 路由处理
+│       ├── {module}.service.ts    # 业务逻辑
+│       ├── {module}.schema.ts     # Zod 校验
+│       ├── dto/                   # 数据传输对象
+│       └── entities/              # 实体定义
+├── shared/                        # 跨模块共享代码
+│   ├── utils/
+│   ├── types/
+│   └── constants/
+└── config/                        # 配置
+```
+
+## 日志
+
+- **禁止**在生产代码中使用 `console.log`
+- 使用结构化日志库（如 winston / pino）
+- 日志级别：error > warn > info > debug
+
+## 注释规范
+
+```typescript
+/**
+ * 根据用户 ID 获取用户信息。
+ *
+ * @param userId - 用户唯一标识符
+ * @returns 用户对象，不存在时返回 null
+ * @throws {ValidationError} 当 userId 格式无效时抛出
+ */
+async function getUserById(userId: string): Promise<User | null> {
+  // ...
+}
+
+// TODO(victor): 这里的缓存策略需要优化 — 后续改为 Redis
+const CACHE_TTL = 3600;
+```

package/templates/rules/development-workflow.md

@@ -1,25 +1,41 @@
-# Development Workflow（9 环节完整流程）
+# 开发工作流（9 步完整流程）
 
 > 每个环节都必须执行（除非标注了跳过条件）。
-> 完成标志 = 该环节产出的可验证产物，没有产物 = 没做完。
+> **完成标志 = 该环节产出的可验证产物**，没有产物 = 没做完。
 
-## 完整链路
+## 完整链路（含命令对应）
 
 ```
-① 需求澄清 ──── OpenSpec /opsx:propose
-② 计划拆分 ──── gstack /plan-ceo-review /plan-eng-review（可选）
-③ 研究复用
-④ TodoList编写
-⑤ TDD开发 ──── Superpowers 强制执行 TDD 纪律
-⑥ 代码审查 ──── code-reviewer agent（自动）
-⑦ 安全审查 ──── gstack /cso（可选）+ security-reviewer（自动）
-⑧ 文档反写
-⑨ 提交归档 ──── gstack /ship（跑测试+生成PR）→ OpenSpec /opsx:archive
+① 需求澄清  📋 /office-hours → /opsx:propose → /brainstorm
+② 计划拆分  📐 /plan
+③ 研究复用  🔍 search-first skill
+④ TodoList   📝 手写 todolist.md
+⑤ TDD开发   🧪 /tdd → 完成时 /verify
+⑥ 代码审查  🔎 /review
+⑦ 安全审查  🛡️ /cso
+⑧ 文档反写  📄 每 commit 后检查 (post-commit hook)
+⑨ 提交归档  🚀 /ship → /opsx:archive
 ```
 
-> 工具说明详见 `CLAUDE.md` § AI 协作工具链
-
----
+## 命令速查
+
+| 步骤 | 命令 | 用途 | 来源 |
+|------|------|------|------|
+| ①-a | `/office-hours` | 需求验证：值不值得做、最小切口 | gstack |
+| ①-b | `/opsx:propose` | 需求规格化：proposal + design + tasks | OpenSpec |
+| ①-c | `/brainstorm` | 方案探索：多方案对比、设计文档 | Superpowers |
+| ② | `/plan` | 计划拆分：P0/P1 子任务、写入 todolist.md | — |
+| ③ | (search-first skill) | 研究复用：GitHub/npm/Context7 搜索 | — |
+| ④ | (手动) | TodoList 编写 | — |
+| ⑤-a | `/tdd` | TDD 执行：RED→GREEN→REFACTOR | Superpowers |
+| ⑤-b | `/verify` | 完成前验证：编译/测试/lint/安全扫描/diff | Superpowers |
+| ⑥ | `/review` | 代码审查：SQL/信任边界/副作用/错误处理 | gstack |
+| ⑦ | `/cso` | 安全审查：密钥/供应链/CI/CD/OWASP/STRIDE | gstack |
+| ⑧ | (post-commit hook) | 文档反写提醒 | — |
+| ⑨-a | `/ship` | 发布：merge→test→review→version→PR | gstack |
+| ⑨-b | `/opsx:archive` | 归档：变更移至 archive/ | OpenSpec |
+
+> 命令是独立的 markdown 文件，位于 `.claude/commands/` 目录，重启 Claude Code 后即可使用。
 
 ## 开发前必读文档
 
@@ -32,61 +48,92 @@
 | 5 | `docs/ui-ux-spec.md` | 页面线框图 + 组件规范（有前端时） |
 | 6 | 相邻已完成模块代码 | 复用实现模式 |
 
-缺少信息？先补设计文档，再写代码。
+缺少信息？**先补设计文档，再写代码。**
 
 ---
 
 ## 各环节
 
 ### ① 需求澄清
-- 动作: 对照 PRD 确认功能边界和优先级
-- **新功能必须先用 OpenSpec**: `/opsx:propose 你的需求描述` → 生成结构化规格 + 任务清单
-- **复杂需求可选 gstack**: `/office-hours` 验证想法，`/plan-ceo-review` 挑战假设
-- ✅ 完成标志: OpenSpec 任务清单已生成 + 明确了做什么、不做什么、P0/P1 划分
-- 跳过条件: 纯技术任务（重构、升级依赖等）
+
+```
+/office-hours → 验证需求 → /opsx:propose → 规格化 → /brainstorm → 方案设计
+```
+
+- **动作**: 先验证需求合理性（/office-hours），再结构化规格（/opsx:propose），最后设计技术方案（/brainstorm）
+- **新功能必须走完整三步**：验证 → 规格 → 方案
+- **/office-hours**: 用六个强制性问题验证需求真伪——用户现在怎么解决的？痛点有多深？最小切口是什么？
+- **/opsx:propose**: 产出 proposal.md（做什么+为什么）、design.md（怎么做）、tasks.md（任务清单）
+- **/brainstorm**: 探索 2-3 种方案、选最佳路径、写设计文档
+- ✅ **完成标志**: 设计文档已提交 + 明确了做什么/不做什么/P0P1 划分
+- **跳过条件**: 纯技术任务（重构、升级依赖等），可直接从 /plan 开始
 
 ### ② 计划拆分
-- 动作: 拆分为可独立提交的子任务（每个 50-300 行）
-- 复杂功能使用 **planner** agent
-- **P0 优先策略**：新模块只先实现 P0，P1 完整列出放待开发区
-- ✅ 完成标志: 有明确的子任务列表，每个子任务对应一个 commit
-- 跳过条件: 单文件小修改（<50 行）
+
+```
+/plan → todolist.md
+```
+
+- **动作**: 将设计文档拆分为可独立提交的子任务（每个 50-300 行）
+- **P0 优先策略**: 新模块只先实现 P0，P1 完整列出放"后续"区
+- **/plan** 命令自动生成 todolist.md，每个子任务对应一个独立 commit
+- ✅ **完成标志**: todolist.md 已更新，每个子任务对应一个 commit
+- **跳过条件**: 单文件小修改（<50 行）
 
 ### ③ 研究复用
-- 动作: GitHub code search → Context7 → npm → 相邻模块代码
-- ✅ 完成标志: 确认了实现模式（复用现有 or 新写）
-- 跳过条件: 已有明确模式可复用
+- **动作**: GitHub code search → npm → 项目内相邻模块代码
+- **search-first skill** 提供结构化搜索流程：并行搜索 → 评估（复用/扩展/组合/自建）→ 决定
+- ✅ **完成标志**: 确认了实现模式（复用现有 or 新写）
+- **跳过条件**: 已有明确模式可复用
 
 ### ④ TodoList 编写
-- 动作: 将子任务写入 `todolist.md`
-- 粒度: 一个子任务 = 一个可独立 commit 的变更
-- ✅ 完成标志: `todolist.md` 已更新，包含所有 P0 + P1 任务
+- **动作**: 将子任务写入 `todolist.md`（若 /plan 已生成则确认）
+- **粒度**: 一个子任务 = 一个可独立 commit 的变更
+- ✅ **完成标志**: `todolist.md` 已更新，包含所有 P0 + P1 任务
 - **不可跳过**
 
 ### ⑤ TDD 开发
-- 动作: RED → GREEN → REFACTOR，覆盖率 ≥80%
-- **Superpowers 强制执行**: `tdd-workflow` skill 确保先写测试再写代码，禁止跳过
-- **按 OpenSpec 任务清单逐项实现**，每完成一项标记 done
-- ✅ 完成标志: 测试通过 + 编译通过
+
+```
+/tdd (循环) → 所有任务完成 → /verify (一次性)
+```
+
+- **动作**: RED → GREEN → REFACTOR，覆盖率 ≥80%
+- **/tdd** 命令强制执行 TDD 纪律：先写失败测试 → 最简实现 → 重构
+- **按任务清单逐项实现**，每完成一项标记 done
+- **所有 P0 任务完成后**，运行 `/verify`：编译→类型检查→Lint→测试→安全扫描→Diff 审查
+- ✅ **完成标志**: /verify 全部通过 + 覆盖率 ≥80%
 - **不可跳过**
+> 完整 TDD 工作流（含测试文件组织 / 命名规范 / 反模式）见 `.claude/rules/testing.md`
 
 ### ⑥ 代码审查
-- 动作: 使用 **code-reviewer** agent
-- ✅ 完成标志: CRITICAL/HIGH 问题已修复
+
+```
+/review
+```
+
+- **动作**: 运行 `/review`，检查 5 维度——SQL 安全性、LLM 信任边界、条件副作用、错误处理、安全
+- **问题分级**: CRITICAL（必须修）> HIGH（应该修）> MEDIUM（可修）> LOW（风格偏好）
+- ✅ **完成标志**: 无 CRITICAL/HIGH 问题
 - **不可跳过**（纯文档/配置变更除外）
 
 ### ⑦ 安全审查
-- 动作: 使用 **security-reviewer** agent
-- ✅ 完成标志: 无 CRITICAL 安全问题
-- 触发: 仅 auth / finance / system 模块
-- 跳过条件: 非安全敏感模块
 
-### ⑧ 文档反写（每个 commit 后立即执行，不可跳过）
+```
+/cso
+```
 
-> 这是最容易遗漏的环节。代码改了但文档没同步 = 技术债。
-> 小功能/临时需求可能不在 PRD 中，反写是唯一让文档跟上代码的机会。
+- **动作**: 运行 `/cso`，5 阶段审计——密钥考古 → 依赖供应链 → CI/CD 管道 → OWASP Top 10 → STRIDE 威胁建模
+- **两种模式**: 日常（零噪音，高置信度门槛）和全面（月度深度扫描）
+- ✅ **完成标志**: 无 CRITICAL 安全问题
+- **触发条件**: 仅 auth / finance / system 模块
+- **跳过条件**: 非安全敏感模块
 
-**逐条检查，改了哪个就同步哪个：**
+### ⑧ 文档反写（**每个 commit 后立即执行，不可跳过**）
+
+> 这是最容易遗漏的环节。**代码改了但文档没同步 = 技术债。**
+
+post-commit hook 会在每次 commit 后自动提醒检查以下对应关系：
 
 | 改了什么 | 必须同步到 |
 |----------|-----------|
@@ -101,13 +148,19 @@
 | 完成了 todolist 中的子任务 | `todolist.md` 删除/勾选 |
 | 模块完成/里程碑 | `memory/MEMORY.md` |
 
-✅ 完成标志: `git diff` 中包含对应的文档文件变更
+✅ **完成标志**: `git diff` 中包含对应的文档文件变更
 
 ### ⑨ 提交归档
-- 动作: `/ship` → 自动跑全量测试 + 检查覆盖率 + 生成 PR 描述 + push + 创建 PR
-- PR merge 后执行 `/opsx:archive` 将变更移至 archive
+
+```
+/ship → PR 合并后 → /opsx:archive
+```
+
+- **/ship 命令自动执行**: merge base → `/verify` → `/review` → bump version → update changelog → commit → push → create PR
+- **如果 verify 失败或 review 发现 CRITICAL 问题，/ship 自动中止**
+- PR 合并后运行 `/opsx:archive` 将变更移至 `openspec/changes/archive/YYYY-MM-DD-<name>/`
 - 小改动（<50行）可直接 `git commit`（遵循 `git-workflow.md` 格式和粒度规范）
-- ✅ 完成标志: PR 已创建（或 commit 成功）+ OpenSpec 已归档
+- ✅ **完成标志**: PR 已创建（或 commit 成功）+ 变更已归档
 - **不可跳过**
 
 ---

package/templates/rules/git-workflow.md

@@ -1,47 +1,103 @@
-# Git Workflow
-
-## Commit Message Format
-```
-<type>: <description>
-
-<optional body>
-```
-
-Types: feat, fix, refactor, docs, test, chore, perf, ci
-
-## Commit 粒度规范
-
-一个 commit = todolist.md 中的一个子任务，满足：
-- 代码可编译通过
-- 相关测试通过
-- 变更文件 1-8 个，行数 50-300 行
-- 超过 500 行应继续拆分
-
-### 典型 commit 序列（后端模块）
-
-```
-feat: 添加{模块}Zod schema          # shared schema
-feat: 实现 {Module}Service           # service 层
-test: 添加 {Module}Service 单元测试   # 测试
-feat: 实现 {Module}Controller        # controller
-feat: 注册 {Module}Module            # module
-docs: 同步{模块}治理文档              # 文档反写
-```
-
-### 典型 commit 序列（前端页面）
-
-```
-feat: 实现{模块}列表页    # 列表
-feat: 实现{模块}详情页    # 详情
-feat: 实现{模块}表单      # 表单
-docs: 同步{模块}治理文档   # 文档反写
-```
-
-## Pull Request Workflow
-
-When creating PRs:
-1. Analyze full commit history (not just latest commit)
-2. Use `git diff [base-branch]...HEAD` to see all changes
-3. Draft comprehensive PR summary
-4. Include test plan with TODOs
-5. Push with `-u` flag if new branch
+# Git 工作流规范（Git Workflow）
+
+## Commit Message 格式
+
+```
+<type>(<scope>): <subject>
+
+<body>
+```
+
+### Type 类型
+
+| Type | 说明 |
+|------|------|
+| `feat` | 新功能 (feature) |
+| `fix` | Bug 修复 (bugfix) |
+| `refactor` | 重构（不增加功能、不修复 bug） |
+| `docs` | 文档变更 |
+| `test` | 测试相关变更 |
+| `chore` | 构建过程/辅助工具变动 |
+| `perf` | 性能优化 |
+| `ci` | CI/CD 配置变更 |
+
+### 格式要求
+
+- **subject**：不超过 50 字符，使用中文或英文，不要结尾加句号
+- **body**：解释 what 和 why（不是 how），每行不超过 72 字符
+- 使用祈使语气（"添加" 而不是 "添加了"）
+
+```bash
+# ✅ 好的提交信息
+feat(user): 添加用户注册接口
+
+- 支持 email + 用户名两种注册方式
+- 注册后自动发送验证邮件
+- 包含 Zod schema 校验
+
+# ❌ 不好的提交信息
+fix: 修了个bug
+随便改了点东西
+```
+
+## Commit 粒度规范
+
+> 一个 commit = todolist.md 中的一个子任务
+
+每个 commit 应满足：
+- 代码可编译通过
+- 相关测试通过
+- 变更文件数：1-8 个
+- 代码行数：50-300 行
+- ⚠️ **超过 500 行应继续拆分**
+
+### 典型 commit 序列 — 后端模块
+
+```
+feat: 添加{模块}Zod schema          # 共享校验层
+feat: 实现 {Module}Service           # 业务逻辑层
+test: 添加 {Module}Service 单元测试   # 测试覆盖
+feat: 实现 {Module}Controller        # API 控制器
+feat: 注册 {Module}Module            # 模块注册
+docs: 同步{模块}设计文档              # 文档反写
+```
+
+### 典型 commit 序列 — 前端页面
+
+```
+feat: 实现{模块}列表页    # 列表视图
+feat: 实现{模块}详情页    # 详情视图
+feat: 实现{模块}表单      # 创建/编辑表单
+docs: 同步{模块}设计文档   # 文档反写
+```
+
+## 分支策略
+
+```
+main ──────────────────────────────── 生产环境
+  ├── develop ────────────────────── 开发集成分支
+  │     ├── feature/user-register    功能分支
+  │     └── feature/payment-integrate
+  └── hotfix/critical-fix-001       紧急修复分支（直接合并 main）
+```
+
+- `feature/*` — 新功能开发，从 develop 创建，完成后 PR 回 develop
+- `hotfix/*` — 紧急线上修复，从 main 创建，完成后 PR 回 main + cherry-pick 到 develop
+- PR 标题格式与 commit message 一致
+
+## Pull Request 工作流
+
+创建 PR 时：
+1. 分析**完整提交历史**（不只是最新一个 commit）
+2. 使用 `git diff [base-branch]...HEAD` 查看所有变更
+3. 编写全面的 PR 摘要（包括做了什么、为什么、怎么验证）
+4. 包含带 TODO 的测试计划
+5. 新分支首次推送时使用 `-u` 标志
+
+## Git Hooks 配置建议
+
+| Hook | 用途 | 建议工具 |
+|------|------|----------|
+| pre-commit | lint + format | Husky + lint-staged / simple-git-hooks |
+| commit-msg | message 格式校验 | commitlint |
+| pre-push | 全量测试通过 | vitest / npm test |