Claude Code Routines 深度指南：在 CLAUDE.md 中定义团队级可复用工作流

# 项目：电商后台 API

## 技术栈
- Node.js 22, TypeScript 5.4
- PostgreSQL + Prisma ORM
- Jest 单测，覆盖率要求 ≥ 80%

## 代码规范
- 所有函数必须有 JSDoc 注释
- 错误处理统一用 AppError 类
- 禁止裸 SQL，用 Prisma query builder

## Routines

### add-endpoint
添加新 API 端点时执行：
1. 在 /src/routes/{resource}.ts 创建路由 handler
2. 用 Zod schema 做输入验证
3. 写集成测试：happy path + 至少 3 个错误场景
4. 更新 /docs/api.yaml 里的 OpenAPI 文档
5. 如果是公开端点，添加限流配置

### scaffold-component
生成新组件时：
1. 在 /src/components/{ComponentName}/ 目录创建 index.tsx
2. 使用 TEMPLATES.md 里的标准组件模板
3. 创建对应测试文件 index.test.tsx
4. 生成 Storybook story：index.stories.tsx
5. 在 /src/components/index.ts 中导出
6. 在 CHANGELOG.md 的 Unreleased 节点添加条目

规范：
- 严格 TypeScript，不用 any 类型（必须注释原因）
- Props 超过 3 个时封装为 interface
- 所有异步操作加 loading 和 error 状态

### add-api-endpoint
添加 REST API 端点：
1. 在 /src/routes/ 创建或更新路由文件
2. 在 /src/controllers/ 实现业务逻辑
3. Zod schema 做请求体验证
4. 统一错误格式：{ success: false, error: string, code: string }
5. 写单元测试 + 集成测试（覆盖 happy path 和主要错误场景）
6. 更新 API 文档（docs/api.md）
7. 如果影响数据库，检查是否需要新建 migration

### debug-regression
参数：{bug_description}，{first_broken_version}（可选）

排查 {bug_description} 时：
1. 在 git log 里找 {first_broken_version} 后的相关提交
2. 用 git bisect 思路缩小范围（不需要实际执行，分析 commit diff）
3. 检查最近改动的相关文件
4. 在本地重现问题（描述重现步骤）
5. 找到根因后，评估影响范围（哪些其他地方有相同模式）
6. 给出修复方案和防范类似问题的建议

### pre-commit-review
提交代码前，检查当前改动：
1. 逻辑正确性：有无明显的 bug 或边界情况遗漏
2. 重复代码：相同逻辑是否已经在其他地方存在，应该复用
3. 函数职责：单个函数是否做了超过一件事
4. 命名：变量和函数名是否清晰表达意图
5. 性能：有无明显的 N+1 查询、不必要的循环、内存泄漏风险
6. 安全：有无 SQL 注入、XSS、敏感信息泄漏风险
7. 测试：新增代码是否有对应测试覆盖

发现问题直接修复，不只是报告。

### generate-pr-description
基于当前 git diff（对比 main 分支）生成 PR 描述：

格式：
## 改动内容
[2-3 句话的简洁摘要]

## 改动类型
- [ ] 新功能 / [ ] Bug 修复 / [ ] 重构 / [ ] 文档 / [ ] 性能优化

## 主要变更
- [关键改动 1]
- [关键改动 2]

## 测试说明
[描述如何测试这个改动]

## 需要 Review 的重点
[指出哪些地方最需要 reviewer 关注]

## 相关 Issue
Closes #[issue number（如果可以推断）]

### update-docs
参数：{feature_description}

完成功能开发后，同步更新文档：
1. 检查 README.md 是否需要更新（安装步骤、使用示例）
2. 更新 API 文档（如果改动了接口）
3. 检查有没有 CHANGELOG.md 条目（放在 Unreleased 节点）
4. 如果新增了环境变量，更新 .env.example
5. 检查 docs/ 目录的相关文档是否需要更新
6. 如果有配置项变化，更新配置文档

原则：文档应该在看完代码前就能理解 {feature_description} 的功能和用法。

### security-review
对以下代码做安全审查：
1. 输入验证：所有外部输入是否都经过验证和过滤
2. SQL 注入：是否有拼接 SQL 的地方
3. XSS：输出到 HTML 时是否转义
4. 认证：敏感接口是否检查了权限
5. 敏感信息：有无硬编码密码、API Key、私钥
6. 依赖安全：新增依赖是否是已知安全的
7. 错误处理：错误信息是否向外暴露了内部细节

每个问题给出：风险等级（高/中/低）+ 具体代码位置 + 修复建议

### full-feature-implementation
参数：{feature_description}

端到端实现 {feature_description}：
1. 运行 scaffold-component 生成 UI 层
2. 运行 add-api-endpoint 实现后端接口
3. 运行 security-review 检查所有新代码
4. 运行 pre-commit-review 确保代码质量
5. 运行 update-docs 同步文档
6. 最后生成 PR 描述（generate-pr-description）

每步完成后告知进展，遇到需要决策的地方暂停确认。

### performance-audit
参数：{component_or_module}，{performance_threshold_ms}（默认 100ms）

对 {component_or_module} 做性能审查：
1. 找出可能超过 {performance_threshold_ms}ms 的操作
2. 检查数据库查询：有无 N+1、缺少索引、全表扫描
3. 检查前端：不必要的重渲染、缺少 memo/useMemo
4. 检查 API 调用：有无可以并行的串行请求
5. 检查算法复杂度：有无 O(n²) 以上的循环
6. 给出优化建议，按影响大小排序

### onboarding-guide
生成新成员 onboarding 文档：
1. 扫描项目目录，生成架构概览（主要目录的作用）
2. 从 README 和 Makefile 提取本地环境搭建步骤，验证步骤是否完整
3. 列出最重要的 10 个文件（先读这些能最快理解项目）
4. 常用命令速查表（运行/测试/部署/lint 等）
5. 代码规范摘要（从 CLAUDE.md 和 .eslintrc 提取）
6. 推荐的第一个 Issue 类型（适合新人上手的）

保存到 docs/ONBOARDING.md

运行 debug-regression，
bug 描述：登录后立刻跳回登录页，
first_broken_version：v2.3.1

先运行 scaffold-component 创建 PaymentForm，
完成后运行 security-review 检查表单安全性

审查这个 PR，如果涉及 API 变更就运行 update-docs，
如果有新的用户输入就运行 security-review