create-vibe-workflow 0.1.0 → 0.2.0

package/dist/templates/rules/hooks.md

@@ -0,0 +1,159 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+
+# Hooks 配置指南
+
+> 本文件定义如何通过 `.claude/settings.json` 配置 Claude Code 的 PostToolUse 和 Stop hooks。
+> 具体依赖声明见 `.claude/settings.json`（由 `create-vibe-workflow` 生成）。
+
+## 什么是 Hooks
+
+Hooks 是 Claude Code 在工具调用前后触发的自动化脚本，用于：
+
+- **PostToolUse hooks**: 在工具使用后自动执行（如自动格式化代码）
+- **Stop hooks**: 在会话停止/结束时执行（如最终检查）
+
+Hooks 在 `.claude/settings.json` 中配置，脚本存放在 `.claude/hooks/` 目录。
+
+## PostToolUse Hooks
+
+在每次工具调用后触发。适用于自动化质量检查。
+
+### 配置结构
+
+```jsonc
+// .claude/settings.json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": {
+          "tool_name": "$<工具名>",
+          "scope": "project"  // 或 "user" / "global"
+        },
+        "command": "node .claude/hooks/<脚本名>",
+        "description": "描述这个 hook 的作用"
+      }
+    ]
+  }
+}
+```
+
+### matcher 字段说明
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| `tool_name` | 匹配的工具名称 | `Bash`、`Edit`、`Write` |
+| `scope` | 作用域 | `project`（项目级）、`user`（用户级）、`global`（全局） |
+
+### Stop Hooks
+
+在会话停止时触发。适用于清理、审计等一次性操作。
+
+```jsonc
+// .claude/settings.json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": {
+          "scope": "project"
+        },
+        "command": "node .claude/hooks/<脚本名>",
+        "description": "描述这个 hook 的作用"
+      }
+    ]
+  }
+}
+```
+
+## 本项目生成的 Hooks
+
+本模板生成了以下两个 hook 脚本（在 `.claude/hooks/` 目录）：
+
+| 脚本 | 类型 | 触发时机 | 作用 |
+|------|------|----------|------|
+| `post-commit-check.js` | PostToolUse | 每次 Bash 工具调用后 | 检测到 `git commit` 命令后提示文档反写检查清单 |
+| `check-deps.mjs` | PostToolUse | 每次工具调用后 | 检查 git 配置是否满足项目规范 |
+
+## 自定义 Hooks 示例
+
+### 示例 1：PostToolUse — 自动格式化
+
+编辑 TypeScript 文件后自动运行 Prettier：
+
+```jsonc
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": {
+          "tool_name": "Edit",
+          "scope": "project"
+        },
+        "command": "npx prettier --write --ignore-unknown .claude/hooks/post-commit-check.js",
+        "description": "编辑文件后自动格式化"
+      }
+    ]
+  }
+}
+```
+
+### 示例 2：PostToolUse — 每次 Bash 后检查 TypeScript 编译
+
+```jsonc
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": {
+          "tool_name": "Bash",
+          "scope": "project"
+        },
+        "command": "npx tsc --noEmit 2>&1 | head -30",
+        "description": "Bash 命令后检查 TypeScript 编译"
+      }
+    ]
+  }
+}
+```
+
+### 示例 3：Stop — 格式化所有文件
+
+```jsonc
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": {
+          "scope": "project"
+        },
+        "command": "npx prettier --write \"src/**/*.{ts,tsx,js,jsx,json}\"",
+        "description": "会话结束时格式化所有源文件"
+      }
+    ]
+  }
+}
+```
+
+## 最佳实践
+
+1. **Hook 脚本要轻量**: hook 在每次工具调用后触发，脚本执行时间不宜超过 1 秒
+2. **避免副作用**: hook 脚本应该只读或只写格式化相关的内容，不要修改业务逻辑
+3. **合理使用 matcher**: 精确匹配工具名，避免不必要的触发
+4. **静默执行**: hook 脚本不应该输出大量日志到终端，除非有错误
+5. **错误不影响主流程**: hook 脚本执行失败不应阻断主工具调用
+
+## 故障排查
+
+| 现象 | 可能原因 | 解决 |
+|------|----------|------|
+| Hook 未触发 | matcher 不匹配或路径错误 | 检查 `tool_name` 和脚本路径 |
+| Hook 输出乱码 | 脚本编码问题 | 确保脚本使用 UTF-8 编码 |
+| Hook 执行缓慢 | 脚本中存在耗时操作 | 简化脚本逻辑 |
+| Hook 报错但未被注意 | 错误被静默吞掉 | 在脚本中添加 `console.error` 输出 |

package/dist/templates/rules/hooks.md.ejs

@@ -0,0 +1,159 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+
+# Hooks 配置指南
+
+> 本文件定义如何通过 `.claude/settings.json` 配置 Claude Code 的 PostToolUse 和 Stop hooks。
+> 具体依赖声明见 `.claude/settings.json`（由 `create-vibe-workflow` 生成）。
+
+## 什么是 Hooks
+
+Hooks 是 Claude Code 在工具调用前后触发的自动化脚本，用于：
+
+- **PostToolUse hooks**: 在工具使用后自动执行（如自动格式化代码）
+- **Stop hooks**: 在会话停止/结束时执行（如最终检查）
+
+Hooks 在 `.claude/settings.json` 中配置，脚本存放在 `.claude/hooks/` 目录。
+
+## PostToolUse Hooks
+
+在每次工具调用后触发。适用于自动化质量检查。
+
+### 配置结构
+
+```jsonc
+// .claude/settings.json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": {
+          "tool_name": "$<工具名>",
+          "scope": "project"  // 或 "user" / "global"
+        },
+        "command": "node .claude/hooks/<脚本名>",
+        "description": "描述这个 hook 的作用"
+      }
+    ]
+  }
+}
+```
+
+### matcher 字段说明
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| `tool_name` | 匹配的工具名称 | `Bash`、`Edit`、`Write` |
+| `scope` | 作用域 | `project`（项目级）、`user`（用户级）、`global`（全局） |
+
+### Stop Hooks
+
+在会话停止时触发。适用于清理、审计等一次性操作。
+
+```jsonc
+// .claude/settings.json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": {
+          "scope": "project"
+        },
+        "command": "node .claude/hooks/<脚本名>",
+        "description": "描述这个 hook 的作用"
+      }
+    ]
+  }
+}
+```
+
+## 本项目生成的 Hooks
+
+本模板生成了以下两个 hook 脚本（在 `.claude/hooks/` 目录）：
+
+| 脚本 | 类型 | 触发时机 | 作用 |
+|------|------|----------|------|
+| `post-commit-check.js` | PostToolUse | 每次 Bash 工具调用后 | 检测到 `git commit` 命令后提示文档反写检查清单 |
+| `check-deps.mjs` | PostToolUse | 每次工具调用后 | 检查 git 配置是否满足项目规范 |
+
+## 自定义 Hooks 示例
+
+### 示例 1：PostToolUse — 自动格式化
+
+编辑 TypeScript 文件后自动运行 Prettier：
+
+```jsonc
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": {
+          "tool_name": "Edit",
+          "scope": "project"
+        },
+        "command": "npx prettier --write --ignore-unknown .claude/hooks/post-commit-check.js",
+        "description": "编辑文件后自动格式化"
+      }
+    ]
+  }
+}
+```
+
+### 示例 2：PostToolUse — 每次 Bash 后检查 TypeScript 编译
+
+```jsonc
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": {
+          "tool_name": "Bash",
+          "scope": "project"
+        },
+        "command": "npx tsc --noEmit 2>&1 | head -30",
+        "description": "Bash 命令后检查 TypeScript 编译"
+      }
+    ]
+  }
+}
+```
+
+### 示例 3：Stop — 格式化所有文件
+
+```jsonc
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": {
+          "scope": "project"
+        },
+        "command": "npx prettier --write \"src/**/*.{ts,tsx,js,jsx,json}\"",
+        "description": "会话结束时格式化所有源文件"
+      }
+    ]
+  }
+}
+```
+
+## 最佳实践
+
+1. **Hook 脚本要轻量**: hook 在每次工具调用后触发，脚本执行时间不宜超过 1 秒
+2. **避免副作用**: hook 脚本应该只读或只写格式化相关的内容，不要修改业务逻辑
+3. **合理使用 matcher**: 精确匹配工具名，避免不必要的触发
+4. **静默执行**: hook 脚本不应该输出大量日志到终端，除非有错误
+5. **错误不影响主流程**: hook 脚本执行失败不应阻断主工具调用
+
+## 故障排查
+
+| 现象 | 可能原因 | 解决 |
+|------|----------|------|
+| Hook 未触发 | matcher 不匹配或路径错误 | 检查 `tool_name` 和脚本路径 |
+| Hook 输出乱码 | 脚本编码问题 | 确保脚本使用 UTF-8 编码 |
+| Hook 执行缓慢 | 脚本中存在耗时操作 | 简化脚本逻辑 |
+| Hook 报错但未被注意 | 错误被静默吞掉 | 在脚本中添加 `console.error` 输出 |

package/dist/templates/rules/memory.md

@@ -0,0 +1,106 @@
+---
+paths:
+  - "**/*"
+---
+
+# 记忆系统使用规则
+
+> 本文件定义了 AI 如何读写项目记忆文件。记忆系统是项目的"长期大脑"，记录经验、决策和上下文。
+
+## 记忆类型
+
+| 类型 | 目录 | 内容 | 谁写 | 谁读 |
+|------|------|------|------|------|
+| **用户 & 团队** | `memory/` (MEMORY.md 索引) | 团队角色、用户偏好、沟通方式 | AI 记录 | AI 在启动时读取 |
+| **反馈 & 经验** | `memory/` | 用户反馈、经验教训、历史决策 | AI + 用户 | AI 在相关任务时读取 |
+| **项目状态** | `memory/` | 里程碑、活跃模块、TODO、技术债务 | AI 维护 | AI 在规划时读取 |
+| **参考 & 外部** | `memory/` | ADR、外部 API、术语表 | AI + 用户 | 按需读取 |
+
+## 记忆文件格式
+
+每条记忆文件使用以下格式：
+
+```markdown
+# 标题
+
+> 记忆元数据
+> - 创建: YYYY-MM-DD
+> - 相关: 关联的模块/功能
+> - 状态: active | archived | deprecated
+
+## 内容
+
+记忆正文...
+
+---
+
+## 相关链接
+
+- [相关记忆](../other-memory.md)
+- [相关代码](../../src/modules/xxx.ts)
+```
+
+### 元数据说明
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `创建` | 是 | 该条记忆的创建日期 |
+| `相关` | 否 | 关联的模块、功能、PR 编号等 |
+| `状态` | 否 | `active`（默认）、`archived`（不再相关但保留）、`deprecated`（已过时） |
+
+## MEMORY.md 索引格式
+
+`memory/MEMORY.md` 是所有记忆的索引文件，每次对话开始时 AI 会自动读取。
+
+```markdown
+# 记忆索引
+
+## 👤 用户 & 团队
+- [标题](file.md) — 一句话钩子
+
+## 💬 反馈 & 经验
+- [标题](file.md) — 一句话钩子
+
+## 📋 项目状态
+- [标题](file.md) — 一句话钩子
+
+## 📚 参考 & 外部
+- [标题](file.md) — 一句话钩子
+```
+
+### 索引规则
+
+1. **每行一个记忆文件**，用 `- [标题](相对路径)` 格式
+2. **一句话钩子**帮助 AI 在启动时判断是否值得深入阅读
+3. 新增记忆后**立即更新** MEMORY.md
+4. 已归档的记忆保留索引行，标注 `(archived)`
+5. 不做硬性分类，四条大类足够
+
+## 写入前置检查清单
+
+在写入或修改任何记忆文件前，检查以下四项：
+
+- [ ] **是否重复**: 这条信息是否已经存在于某条记忆中？如果是，更新已有记录而不是新建
+- [ ] **是否有价值**: 这条信息对未来开发有用吗？3 个月后还会需要它吗？
+- [ ] **是否事实**: 这是客观事实还是主观猜测？如是猜测，标注 `(待确认)`
+- [ ] **一个主题一个文件**: 相关事实是否应归入同一条目或同一个文件？
+
+## 何时读取记忆
+
+| 场景 | 应该读取 |
+|------|----------|
+| 对话开始时 | MEMORY.md 索引 |
+| 开始新功能 | 用户偏好、相关模块状态 |
+| 遇到错误 | troubleshooting.md |
+| 做技术决策 | architecture-decisions.md |
+| 修 Bug | 相关模块记忆、troubleshooting.md |
+| 用户给反馈 | 反馈历史（避免重复讨论） |
+
+## 记忆目录保护规则
+
+> **关键规则：在合并模式下（已有 `.claude/` 目录），`memory/` 目录永不覆盖。**
+
+- 合并模式下：`memory/` 目录**完全保留不动**，不写入、不修改、不删除任何文件
+- 覆盖模式下（`--overwrite`）：仍保留 `memory/`，但会添加缺失的模板文件
+- 卸载模式下（`--uninstall`）：`memory/` 中的文件不列入 manifest，不会被卸载删除
+- 原因：记忆是项目积累的宝贵上下文，新生成的模板不应冲掉已有记录

package/dist/templates/rules/memory.md.ejs

@@ -0,0 +1,106 @@
+---
+paths:
+  - "**/*"
+---
+
+# 记忆系统使用规则
+
+> 本文件定义了 AI 如何读写项目记忆文件。记忆系统是项目的"长期大脑"，记录经验、决策和上下文。
+
+## 记忆类型
+
+| 类型 | 目录 | 内容 | 谁写 | 谁读 |
+|------|------|------|------|------|
+| **用户 & 团队** | `memory/` (MEMORY.md 索引) | 团队角色、用户偏好、沟通方式 | AI 记录 | AI 在启动时读取 |
+| **反馈 & 经验** | `memory/` | 用户反馈、经验教训、历史决策 | AI + 用户 | AI 在相关任务时读取 |
+| **项目状态** | `memory/` | 里程碑、活跃模块、TODO、技术债务 | AI 维护 | AI 在规划时读取 |
+| **参考 & 外部** | `memory/` | ADR、外部 API、术语表 | AI + 用户 | 按需读取 |
+
+## 记忆文件格式
+
+每条记忆文件使用以下格式：
+
+```markdown
+# 标题
+
+> 记忆元数据
+> - 创建: YYYY-MM-DD
+> - 相关: 关联的模块/功能
+> - 状态: active | archived | deprecated
+
+## 内容
+
+记忆正文...
+
+---
+
+## 相关链接
+
+- [相关记忆](../other-memory.md)
+- [相关代码](../../src/modules/xxx.ts)
+```
+
+### 元数据说明
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `创建` | 是 | 该条记忆的创建日期 |
+| `相关` | 否 | 关联的模块、功能、PR 编号等 |
+| `状态` | 否 | `active`（默认）、`archived`（不再相关但保留）、`deprecated`（已过时） |
+
+## MEMORY.md 索引格式
+
+`memory/MEMORY.md` 是所有记忆的索引文件，每次对话开始时 AI 会自动读取。
+
+```markdown
+# 记忆索引
+
+## 👤 用户 & 团队
+- [标题](file.md) — 一句话钩子
+
+## 💬 反馈 & 经验
+- [标题](file.md) — 一句话钩子
+
+## 📋 项目状态
+- [标题](file.md) — 一句话钩子
+
+## 📚 参考 & 外部
+- [标题](file.md) — 一句话钩子
+```
+
+### 索引规则
+
+1. **每行一个记忆文件**，用 `- [标题](相对路径)` 格式
+2. **一句话钩子**帮助 AI 在启动时判断是否值得深入阅读
+3. 新增记忆后**立即更新** MEMORY.md
+4. 已归档的记忆保留索引行，标注 `(archived)`
+5. 不做硬性分类，四条大类足够
+
+## 写入前置检查清单
+
+在写入或修改任何记忆文件前，检查以下四项：
+
+- [ ] **是否重复**: 这条信息是否已经存在于某条记忆中？如果是，更新已有记录而不是新建
+- [ ] **是否有价值**: 这条信息对未来开发有用吗？3 个月后还会需要它吗？
+- [ ] **是否事实**: 这是客观事实还是主观猜测？如是猜测，标注 `(待确认)`
+- [ ] **一个主题一个文件**: 相关事实是否应归入同一条目或同一个文件？
+
+## 何时读取记忆
+
+| 场景 | 应该读取 |
+|------|----------|
+| 对话开始时 | MEMORY.md 索引 |
+| 开始新功能 | 用户偏好、相关模块状态 |
+| 遇到错误 | troubleshooting.md |
+| 做技术决策 | architecture-decisions.md |
+| 修 Bug | 相关模块记忆、troubleshooting.md |
+| 用户给反馈 | 反馈历史（避免重复讨论） |
+
+## 记忆目录保护规则
+
+> **关键规则：在合并模式下（已有 `.claude/` 目录），`memory/` 目录永不覆盖。**
+
+- 合并模式下：`memory/` 目录**完全保留不动**，不写入、不修改、不删除任何文件
+- 覆盖模式下（`--overwrite`）：仍保留 `memory/`，但会添加缺失的模板文件
+- 卸载模式下（`--uninstall`）：`memory/` 中的文件不列入 manifest，不会被卸载删除
+- 原因：记忆是项目积累的宝贵上下文，新生成的模板不应冲掉已有记录

package/dist/templates/rules/patterns.md

@@ -1,48 +1,117 @@
----
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "**/*.js"
-  - "**/*.jsx"
----
-# TypeScript/JavaScript Patterns
-
-## API Response Format
-
-```typescript
-interface ApiResponse<T> {
-  success: boolean
-  data?: T
-  error?: string
-  meta?: {
-    total: number
-    page: number
-    limit: number
-  }
-}
-```
-
-## Custom Hooks Pattern
-
-```typescript
-export function useDebounce<T>(value: T, delay: number): T {
-  const [debouncedValue, setDebouncedValue] = useState<T>(value)
-  useEffect(() => {
-    const handler = setTimeout(() => setDebouncedValue(value), delay)
-    return () => clearTimeout(handler)
-  }, [value, delay])
-  return debouncedValue
-}
-```
-
-## Repository Pattern
-
-```typescript
-interface Repository<T> {
-  findAll(filters?: Filters): Promise<T[]>
-  findById(id: string): Promise<T | null>
-  create(data: CreateDto): Promise<T>
-  update(id: string, data: UpdateDto): Promise<T>
-  delete(id: string): Promise<void>
-}
-```
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# 代码模式规范（Patterns）
+
+> 本文件定义项目中应遵循的通用代码模式。保持一致性比"最好"更重要。
+
+## API 响应格式
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+  meta?: {
+    total: number
+    page: number
+    limit: number
+  }
+}
+```
+
+## 自定义 Hook 模式（前端）
+
+```typescript
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value)
+  useEffect(() => {
+    const handler = setTimeout(() => setDebouncedValue(value), delay)
+    return () => clearTimeout(handler)
+  }, [value, delay])
+  return debouncedValue
+}
+```
+
+## Repository 模式（后端）
+
+```typescript
+interface Repository<T, CreateDto, UpdateDto> {
+  findAll(filters?: FilterOptions): Promise<T[]>
+  findById(id: string): Promise<T | null>
+  findByUnique(field: keyof T, value: unknown): Promise<T | null>
+  create(data: CreateDto): Promise<T>
+  update(id: string, data: UpdateDto): Promise<T>
+  softDelete?(id: string): Promise<T>   // 可选：软删除
+  delete(id: string): Promise<void>
+}
+```
+
+## Service 层模式
+
+```typescript
+@Injectable()  // NestJS 示例，其他框架类似
+export class UserService {
+  constructor(
+    private readonly userRepo: UserRepository,
+    private readonly logger: LoggerService,
+  ) {}
+
+  async createUser(dto: CreateUserDto): Promise<User> {
+    // 1. 校验
+    const exists = await this.userRepo.findByEmail(dto.email)
+    if (exists) throw new ConflictException('用户已存在')
+
+    // 2. 业务逻辑
+    const hashedPassword = await hash(dto.password, 10)
+
+    // 3. 持久化
+    const user = await this.userRepo.create({
+      ...dto,
+      password: hashedPassword,
+    })
+
+    this.logger.info('用户创建成功', { userId: user.id })
+    return user
+  }
+}
+```
+
+## 错误处理统一模式
+
+> **底层错误收窄技巧（unknown → Error、async/await try-catch）见 `.claude/rules/coding-style.md` § 错误处理**
+> 本节定义业务层错误分类体系，与 coding-style.md 互补。
+
+```typescript
+// 自定义业务错误类
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number = 500,
+    public code: string = 'INTERNAL_ERROR',
+  ) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+
+// 常用快捷错误
+export class NotFoundError extends AppError {
+  constructor(resource: string, id?: string) {
+    super(`${resource}${id ? ` (${id})` : ''} 不存在`, 404, 'NOT_FOUND');
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(details: string) {
+    super(details, 400, 'VALIDATION_ERROR');
+  }
+}
+
+// 使用示例
+if (!user) throw new NotFoundError('User', userId);
+```