create-vibe-workflow 0.1.0 → 0.2.0

package/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/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/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);
+```

package/templates/rules/performance.md

@@ -0,0 +1,108 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+
+# 性能优化规则
+
+> 本文件定义了模型选择、上下文管理和构建调优策略。
+
+## 模型选择策略
+
+根据任务类型选择最合适的模型，平衡性能和成本。
+
+| 模型 | 适用场景 | 成本效益 |
+|------|----------|----------|
+| **Haiku 4.5** | 90% Sonnet 能力，3 倍成本节省 | 高频轻量任务的首选 |
+| **Sonnet 4.6** | 最佳编码模型 | 主要开发工作、复杂编码 |
+| **Opus 4.5** | 最深推理能力 | 复杂架构决策、研究分析 |
+
+### 推荐分配
+
+```
+轻量 Agent（频繁调用） → Haiku 4.5
+  - 代码审查
+  - 简单重构
+  - 测试生成
+
+主要开发工作 → Sonnet 4.6
+  - 功能实现
+  - Bug 修复
+  - 多文件修改
+
+深度推理 → Opus 4.5
+  - 架构决策
+  - 复杂问题排查
+  - 安全审计
+```
+
+## 上下文窗口管理
+
+上下文窗口的最后 20% 区域执行效率显著下降。以下操作应**避免**在最后 20% 区域执行：
+
+- ❌ 大规模重构（跨多个文件）
+- ❌ 涉及多文件的功能实现
+- ❌ 复杂交互的 Debug
+
+以下操作对上下文位置**不敏感**，可在任意位置执行：
+
+- ✅ 单文件编辑
+- ✅ 独立工具函数创建
+- ✅ 文档更新
+- ✅ 简单 Bug 修复
+
+### 最佳实践
+
+- **分段提交**: 大任务拆分为多个小段，每段独立提交
+- **关键操作前置**: 需要全上下文感知的操作优先在对话早期完成
+- **适时重启**: 如果上下文已满且还有复杂任务，保存进度后开启新对话
+
+## 扩展思考 + Plan 模式
+
+扩展思考（Extended Thinking）默认启用，保留最多 31,999 个 token 用于内部推理。
+
+### 控制方式
+
+| 操作 | 快捷键 |
+|------|--------|
+| 开启/关闭 | Option+T (macOS) / Alt+T (Windows/Linux) |
+| 配置文件 | `~/.claude/settings.json` 中的 `alwaysThinkingEnabled` |
+| 预算上限 | 环境变量 `MAX_THINKING_TOKENS` |
+
+### 适用场景
+
+对于复杂任务，结合 Plan 模式获得最佳效果：
+
+1. 确保扩展思考已启用（默认开启）
+2. 启用 Plan 模式进行结构化规划
+3. 多轮 Critique 确保充分分析
+4. 使用子 Agent 分工获取多角度视角
+
+## 构建调优
+
+如果构建失败，按以下流程排查：
+
+```
+构建失败
+  ↓
+① 分析错误信息
+  ↓
+② 定位出错文件/模块
+  ↓
+③ 增量修复（一次修一个错误）
+  ↓
+④ 重新编译验证
+  ↓
+⑤ 重复直至通过
+```
+
+### 如果构建反复失败
+
+1. 使用 **build-error-resolver** agent 专项排查
+2. 检查依赖版本是否兼容
+3. 检查 TypeScript 配置（`tsconfig.json`）是否正确
+4. 清除缓存后重试（`rm -rf node_modules/.cache`、`rm -rf dist/`）
+5. 逐文件排查增量编译报错

package/templates/rules/security.md

@@ -1,37 +1,52 @@
----
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "**/*.js"
-  - "**/*.jsx"
----
-# TypeScript/JavaScript Security
-
-## Secret Management
-
-```typescript
-// NEVER: Hardcoded secrets
-const apiKey = "sk-proj-xxxxx"
-
-// ALWAYS: Environment variables
-const apiKey = process.env.OPENAI_API_KEY
-if (!apiKey) {
-  throw new Error('OPENAI_API_KEY not configured')
-}
-```
-
-## Mandatory Security Checks
-
-Before ANY commit:
-- [ ] No hardcoded secrets (API keys, passwords, tokens)
-- [ ] All user inputs validated
-- [ ] SQL injection prevention (parameterized queries)
-- [ ] XSS prevention (sanitized HTML)
-- [ ] CSRF protection enabled
-- [ ] Authentication/authorization verified
-- [ ] Rate limiting on all endpoints
-- [ ] Error messages don't leak sensitive data
-
-## Agent Support
-
-- Use **security-reviewer** agent for comprehensive security audits
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# 安全规范（Security）
+
+> 安全是特性，不是事后补救。
+> **触发条件**: 仅 auth / finance / system 模块（或涉及用户数据、支付、权限的代码变更）。
+> **跳过条件**: 非安全敏感模块（纯 UI 调整、文档修改、重构不涉数据流等）。
+> 完整触发/跳过规则见 `development-workflow.md` 第 ⑦ 步。
+
+## 密钥管理
+
+```typescript
+// ❌ 硬编码密钥（绝对禁止）
+const apiKey = "sk-proj-xxxxx"
+
+// ✅ 使用环境变量
+const apiKey = process.env.OPENAI_API_KEY
+if (!apiKey) {
+  throw new Error('OPENAI_API_KEY not configured')
+}
+```
+
+## 提交前强制检查清单
+
+- [ ] 无硬编码密钥（API Key、密码、Token）
+- [ ] 所有用户输入已校验（Zod schema）
+- [ ] SQL 注入防护（参数化查询 / ORM 内置防护）
+- [ ] XSS 防护（HTML 净化 / 转义输出）
+- [ ] CSRF 保护已启用（有表单提交时）
+- [ ] 身份认证/授权已验证
+- [ ] 所有端点已限流
+- [ ] 错误消息不泄露敏感数据（不返回堆栈、内部路径等）
+
+## 常见安全漏洞防范
+
+| 漏洞 | 防范方式 |
+|------|----------|
+| SQL 注入 | 使用 ORM / 参数化查询 |
+| XSS | 输出转义、CSP 头、HTML Sanitizer |
+| CSRF | SameSite Cookie、CSRF Token |
+| SSRF | 白名单域名 + 不响应内网 IP |
+| IDOR (越权) | 每次操作验证资源所有权 |
+| 敏感数据泄露 | 日志脱敏、错误信息泛化 |
+
+## Agent 支持
+
+- 使用 **security-review** skill 进行全面的安全审计