foryourhealth111-pixel/Vibe-Skills / bundled/skills/commit-with-reflection
commit-with-reflection
VerifiedGit提交与调试反思报告生成技能。用于分析开发过程中的错误、调试步骤和解决方案,生成结构化的中文反思报告,并创建包含报告引用的Git提交。显式请求词:反思提交、智能提交、生成调试报告、commit with reflection。
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 5.1 KB |
| SKILL.md | skill md | 20.9 KB |
| assets/template-chinese.md | markdown | 1.4 KB |
| examples/feature-example.md | markdown | 19.9 KB |
| references/best-practices.md | markdown | 18.1 KB |
| references/error-taxonomy.md | markdown | 12.4 KB |
| references/index.md | markdown | 2.9 KB |
| scripts/update-index.js | script | 11.0 KB |
references/best-practices.md
View on GitHub# 反思报告最佳实践指南
本指南提供编写高质量反思报告的方法论、技巧和实用建议,帮助将每次开发经验转化为可复用的知识资产。
## 核心原则
### 1. 及时性原则
**为什么重要**: 记忆会随时间衰减,调试细节容易遗忘。
**最佳实践**:
- 在调试过程中实时记录关键步骤
- 完成修复后立即生成反思报告
- 不要等到一天结束或项目完成后再回忆
**实用技巧**:
```
调试时的记录习惯:
1. 遇到错误 → 复制完整错误消息
2. 尝试解决方案 → 记录"尝试X,结果Y"
3. 找到根本原因 → 立即写下洞察
4. 修复完成 → 触发反思报告生成
```
---
### 2. 深度分析原则
**为什么重要**: 表面原因无法防止错误再次发生,只有深入根本原因才能真正学习。
**最佳实践**:
- 使用"5个为什么"技术挖掘根本原因
- 区分直接原因、深层原因和促成因素
- 分析自己的思维过程和假设
**5个为什么示例**:
```
错误: 用户无法登录
为什么1: API返回401错误
为什么2: Token验证失败
为什么3: Token格式不正确
为什么4: 前端发送了旧格式的token
为什么5: 升级后端API时未同步更新前端代码
根本原因: 缺少前后端API版本同步机制
```
---
### 3. 可执行性原则
**为什么重要**: 模糊的建议无法指导未来行动,具体的策略才能真正预防错误。
**最佳实践**:
- 预防策略要具体、可执行
- 提供检查清单而非泛泛而谈
- 包含具体的工具、命令或代码示例
**对比示例**:
❌ **不好的预防策略**:
```
- 要更加小心
- 注意类型安全
- 做好测试
```
✅ **好的预防策略**:
```
- 在修改API前,先运行 `git grep "api.login"` 查找所有调用点
- 使用 TypeScript strict mode 强制类型检查
- 为每个API端点编写集成测试,覆盖认证流程
- 在 package.json 添加 pre-commit hook: "lint && test"
```
---
### 4. 模式识别原则
**为什么重要**: 单个错误是个案,模式是可复用的知识。
**最佳实践**:
- 识别错误背后的通用模式
- 提炼可应用于其他场景的经验
- 建立个人/团队的模式库
**模式提炼示例**:
```
具体错误:
在React组件中直接修改state导致UI不更新
通用模式:
"状态不可变性原则" - 在任何状态管理系统中,
直接修改状态对象都会导致变更检测失败
可复用知识:
- React: 使用 setState 或 useState
- Redux: 使用 reducer 返回新对象
- Vue: 使用 Vue.set 或响应式API
- 通用: 始终创建新对象而非修改原对象
```
---
## 报告章节编写指南
### 第1章: 概述
**目的**: 用1-2句话说明本次修改的核心内容和目的。
**编写技巧**:
- 使用主动语态
- 说明"做了什么"和"为什么做"
- 避免技术细节(留给后续章节)
**示例**:
✅ **好的概述**:
```
实现了用户认证功能,包括JWT token生成和验证,
以支持安全的API访问控制。
```
❌ **不好的概述**:
```
修改了一些文件,添加了代码,修复了bug。
```
---
### 第2章: 修改内容
**目的**: 清晰列出所有变更,便于快速了解改动范围。
**编写技巧**:
- 按功能模块分组文件
- 每个文件附上简短说明(5-10字)
- 主要变更要具体,不要只说"添加功能"
**示例**:
```markdown
### 修改的文件
**认证模块**:
- `server/auth/jwt.ts` - JWT token生成和验证逻辑
- `server/middleware/auth.ts` - 认证中间件
**API路由**:
- `server/routers/auth.ts` - 登录/注册API端点
**前端组件**:
- `client/src/pages/Login.tsx` - 登录页面UI
- `client/src/hooks/useAuth.ts` - 认证状态管理
### 主要变更
- 实现JWT token生成,使用HS256算法,有效期24小时
- 添加认证中间件,自动验证所有/api/*路由的token
- 创建登录页面,支持用户名/密码登录
- 实现token自动刷新机制,避免频繁登录
```
---
### 第3章: 遇到的错误
**目的**: 详细记录每个错误,为根本原因分析提供素材。
**编写技巧**:
- 每个错误独立一个小节
- 包含完整的错误消息(不要截断)
- 提供足够的代码上下文
- 说明解决方案的具体步骤
**模板**:
```markdown
### 错误 1: [错误类型]
**严重程度**: [严重|重要|次要]
**错误信息**:
```
[完整的错误消息,包括堆栈跟踪]
```
**上下文**:
[触发错误的代码片段或操作步骤]
**解决方案**:
[具体的修复步骤,包括代码变更]
```
**示例**:
```markdown
### 错误 1: TypeScript类型错误
**严重程度**: 重要
**错误信息**:
```
Property 'userId' does not exist on type 'User'.
at server/routers/auth.ts:45:23
```
**上下文**:
在生成JWT token时,尝试访问 `user.userId`:
```typescript
const token = jwt.sign({ userId: user.userId }, SECRET);
```
但User接口定义中没有userId字段:
```typescript
interface User {
id: number;
name: string;
email: string;
}
```
**解决方案**:
1. 检查数据库schema,确认用户表的主键字段名为 `id`
2. 修改代码使用 `user.id` 而非 `user.userId`
3. 运行 `tsc --noEmit` 验证类型错误已解决
```
---
### 第4章: 根本原因分析
**目的**: 这是反思报告的核心,深入分析错误的本质。
**编写技巧**:
- 使用"5个为什么"技术
- 区分三个层次:直接原因、深层原因、促成因素
- 反思自己的思维过程和假设
**分析框架**:
```markdown
### 为什么会出现这个错误?
**直接原因**:
[表面上看到的直接触发因素]
**深层原因**:
[背后的系统性问题或知识盲区]
**促成因素**:
[环境、流程、工具等方面的缺陷]
### 是什么导致编写时出现这个错误?
**做出的假设**:
[编写代码时的错误假设]
**知识盲区**:
[不了解或忽略的知识点]
**忽略的模式**:
[应该遵循但未遵循的最佳实践]
```
**示例**:
```markdown
### 为什么会出现这个错误?
**直接原因**:
User接口定义中缺少userId字段
**深层原因**:
- 数据库schema使用 `id` 作为主键,但代码中习惯性使用 `userId`
- 接口定义与数据库schema不同步
- 缺少从schema自动生成类型的机制
**促成因素**:
- 项目中同时存在 `id` 和 `userId` 两种命名,不一致
- TypeScript配置未启用严格模式,早期未发现此类问题
- 缺少代码审查流程
### 是什么导致编写时出现这个错误?
**做出的假设**:
假设User对象有userId字段,因为其他模型(如Post)使用userId作为外键
**知识盲区**:
不了解User表的实际schema结构,未先查看数据库定义
**忽略的模式**:
未遵循"先查看类型定义再编写代码"的最佳实践
```
---
### 第5章: 调试过程
**目的**: 记录调试的完整过程,包括失败的尝试,为他人提供参考。
**编写技巧**:
- 按时间顺序记录调查步骤
- 包含失败的尝试及其原因
- 记录耗时,识别效率瓶颈
**示例**:
```markdown
### 调查步骤
1. 查看TypeScript错误提示,定位到 `server/routers/auth.ts:45`
2. 检查User接口定义,发现缺少userId字段
3. 查看数据库schema文件 `drizzle/schema.ts`
4. 确认数据库使用 `id` 而非 `userId`
5. 搜索代码库中所有使用 `user.userId` 的地方: `git grep "user.userId"`
6. 发现3处使用,逐一修改为 `user.id`
### 迭代过程
**尝试 1**: 在User接口中添加 `userId: number` 字段
- 结果: 类型错误消失,但运行时 `userId` 为 `undefined`
- 原因: 数据库返回的是 `id`,不是 `userId`
- 结论: 治标不治本,放弃此方案
**尝试 2**: 修改代码使用 `user.id`
- 结果: 类型检查通过,运行时正常
- 原因: 与数据库schema一致
- 结论: 正确方案,采用
### 耗时统计
- 调查: 15 分钟 (查看错误、检查定义、搜索代码)
- 实现: 10 分钟 (修改3处代码)
- 测试: 5 分钟 (运行类型检查和手动测试)
- **总计: 30 分钟**
**效率反思**:
如果一开始就查看数据库schema,可以节省10分钟的错误尝试时间。
```
---
### 第6章: 经验总结
**目的**: 提炼可复用的经验和具体的预防策略。
**编写技巧**:
- 核心洞察要有启发性
- 预防策略要具体可执行
- 最佳实践要可推广
**示例**:
```markdown
### 核心洞察
1. **命名一致性至关重要**:
项目中同时存在 `id` 和 `userId` 两种命名,
增加了认知负担和出错概率。
2. **类型定义应该是单一事实来源**:
手动维护类型定义容易与数据源不同步,
应该从schema自动生成。
3. **假设需要验证**:
编写代码前的假设(如"User有userId字段")
应该通过查看定义来验证,而非依赖记忆。
### 预防策略
**策略 1: 统一命名规范**
- 在项目中统一使用 `id` 作为主键字段名
- 外键使用 `<table>Id` 格式(如 `userId`, `postId`)
- 在 `CONTRIBUTING.md` 中文档化此规范
**策略 2: 自动生成类型定义**
- 使用 `drizzle-kit introspect` 从数据库生成类型
- 添加 npm script: `"types:generate": "drizzle-kit introspect"`
- 在 pre-commit hook 中检查类型是否最新
**策略 3: 编码前检查**
- 在使用对象属性前,先用 IDE 的"Go to Definition"查看类型
- 启用 TypeScript 的 `noUncheckedIndexedAccess` 选项
- 使用 ESLint 规则禁止使用 `any` 类型
### 识别的最佳实践
**实践 1: Schema-First开发**
- 先定义数据库schema
- 从schema生成TypeScript类型
- 基于类型编写业务逻辑
**实践 2: 类型驱动开发**
- 让TypeScript编译器成为第一道防线
- 使用严格模式(`strict: true`)
- 定期运行 `tsc --noEmit` 检查类型错误
**实践 3: 文档化假设**
- 在代码注释中说明关键假设
- 使用断言验证运行时假设
- 在README中记录数据模型约定
```
---
### 第7章: 知识提炼
**目的**: 将具体经验抽象为可复用的模式和原则。
**编写技巧**:
- 识别通用模式(不限于当前技术栈)
- 明确反模式(应该避免的做法)
- 提供检查清单供未来参考
**示例**:
```markdown
### 可复用模式
**模式 1: 单一事实来源(Single Source of Truth)**
**问题**: 多处维护相同信息导致不一致
**解决方案**:
- 确定权威数据源(如数据库schema)
- 其他表示(如TypeScript类型)从权威源生成
- 使用工具自动化生成过程
**适用场景**:
- 数据库schema → TypeScript类型
- OpenAPI spec → API客户端代码
- GraphQL schema → TypeScript类型
- Protobuf定义 → 多语言代码
**模式 2: 契约测试(Contract Testing)**
**问题**: 前后端接口不一致导致集成失败
**解决方案**:
- 定义明确的接口契约(如TypeScript接口)
- 前后端共享类型定义
- 编写测试验证实现符合契约
**适用场景**:
- 前后端分离项目
- 微服务之间的API
- 第三方API集成
### 应避免的反模式
**反模式 1: 手动同步类型定义**
**为什么不好**:
- 容易遗忘更新
- 人工维护易出错
- 浪费时间
**替代方案**:
使用代码生成工具自动同步
**反模式 2: 依赖记忆编写代码**
**为什么不好**:
- 记忆不可靠
- 假设可能过时
- 增加认知负担
**替代方案**:
使用IDE的"Go to Definition"和类型提示
**反模式 3: 忽略类型错误**
**为什么不好**:
- 类型错误通常指示真实问题
- 使用 `any` 或 `@ts-ignore` 掩盖问题
- 运行时可能出现难以调试的错误
**替代方案**:
修复根本原因,而非绕过类型检查
### 类似任务检查清单
在实现涉及数据模型的功能时:
- [ ] 查看数据库schema,确认字段名和类型
- [ ] 检查TypeScript类型定义是否与schema一致
- [ ] 使用 `tsc --noEmit` 运行类型检查
- [ ] 搜索代码库中类似的实现作为参考
- [ ] 编写单元测试覆盖数据访问逻辑
- [ ] 在开发环境测试完整流程
- [ ] 代码审查时重点检查类型安全性
```
---
### 第8章: 测试与验证
**目的**: 记录如何验证修复的正确性,为回归测试提供参考。
**编写技巧**:
- 列出所有测试用例
- 包含正常情况和边界情况
- 说明验证步骤
**示例**:
```markdown
### 测试用例
**测试 1: 用户登录成功**
- 输入: 有效的用户名和密码
- 预期: 返回JWT token,token包含正确的userId(实际是id)
- 结果: ✅ 通过
**测试 2: Token验证**
- 输入: 有效的JWT token
- 预期: 中间件成功验证,允许访问受保护的API
- 结果: ✅ 通过
**测试 3: 无效Token**
- 输入: 过期或格式错误的token
- 预期: 返回401 Unauthorized
- 结果: ✅ 通过
**测试 4: 类型检查**
- 操作: 运行 `tsc --noEmit`
- 预期: 无类型错误
- 结果: ✅ 通过
### 验证步骤
1. **本地开发环境测试**:
```bash
npm run dev
# 访问 http://localhost:3000/login
# 输入测试账号登录
# 检查Network面板,确认token格式正确
```
2. **单元测试**:
```bash
npm test -- auth
# 所有认证相关测试通过
```
3. **类型检查**:
```bash
tsc --noEmit
# 无错误输出
```
4. **集成测试**:
```bash
npm run test:e2e
# 端到端登录流程测试通过
```
5. **代码审查**:
- 提交PR,请求团队成员审查
- 重点检查类型安全性和命名一致性
```
---
### 第9章: 参考资料
**目的**: 提供相关资源链接,便于深入学习和查证。
**编写技巧**:
- 包含相关的commit hash
- 链接到项目内部文档
- 引用外部权威资源
**示例**:
```markdown
## 参考资料
### 相关提交
- `abc123f` - 初始实现用户认证功能
- `def456a` - 修复userId类型错误
- `ghi789b` - 统一命名规范
### 项目文档
- [数据库Schema文档](../database/schema.md)
- [API接口文档](../api/authentication.md)
- [TypeScript配置说明](../docs/typescript-setup.md)
### 外部资源
- [TypeScript Handbook - Interfaces](https://www.typescriptlang.org/docs/handbook/interfaces.html)
- [Drizzle ORM - Type Safety](https://orm.drizzle.team/docs/type-safety)
- [JWT Best Practices](https://tools.ietf.org/html/rfc8725)
### 相关Issue
- #123 - 用户认证功能需求
- #456 - 类型定义不一致问题
```
---
### 第10章: 指标
**目的**: 量化本次开发的复杂度和效率,识别改进空间。
**编写技巧**:
- 记录准确的数字
- 计算成功率和效率指标
- 与历史数据对比
**示例**:
```markdown
## 指标
### 错误统计
- 总错误数: 3
- 严重错误数: 0
- 重要错误数: 2
- 次要错误数: 1
### 调试效率
- 调试迭代次数: 5
- 首次尝试成功率: 20% (1/5)
- 总耗时: 45 分钟
- 平均每个错误耗时: 15 分钟
### 代码变动
- 新增行数: +120
- 删除行数: -15
- 净增加: +105 行
- 修改文件数: 5 个
### 测试覆盖
- 新增测试用例: 8 个
- 测试通过率: 100%
- 代码覆盖率: 85%
### 效率分析
- **高效部分**: 使用git grep快速定位所有相关代码
- **低效部分**: 尝试错误方案浪费10分钟
- **改进空间**: 如果先查看schema可节省33%时间
```
---
## 高级技巧
### 技巧 1: 使用思维导图组织思路
在编写复杂的根本原因分析时:
```
错误: 用户无法登录
|
├─ 直接原因
│ └─ API返回401
│ └─ Token验证失败
│ └─ userId字段不存在
│
├─ 深层原因
│ ├─ 类型定义不完整
│ ├─ 命名不一致(id vs userId)
│ └─ 缺少自动生成机制
│
└─ 促成因素
├─ 未启用TypeScript严格模式
├─ 缺少代码审查
└─ 文档不完善
```
### 技巧 2: 建立个人错误模式库
创建 `personal-patterns.md`:
```markdown
# 我的常见错误模式
## 模式 1: 忘记await异步函数
**频率**: ⭐⭐⭐⭐⭐ (非常常见)
**后果**: 得到Promise对象而非实际值
**预防**: 使用ESLint规则 `@typescript-eslint/no-floating-promises`
## 模式 2: 直接修改state
**频率**: ⭐⭐⭐
**后果**: React组件不更新
**预防**: 使用ESLint规则 `react/no-direct-mutation-state`
```
### 技巧 3: 定期回顾和总结
每周/每月回顾所有反思报告:
```markdown
# 2026年2月反思总结
## 统计
- 总报告数: 12
- 总错误数: 28
- 最常见错误类型: TypeScript类型错误 (10次)
## 趋势分析
- 类型错误从第1周的5次降低到第4周的1次
- 说明类型安全意识在提高
## 重复出现的问题
- 异步函数忘记await (3次)
- 需要加强异步编程训练
## 行动计划
- 启用更严格的ESLint规则
- 学习TypeScript高级类型
- 建立代码审查检查清单
```
### 技巧 4: 团队知识共享
将有价值的反思报告分享给团队:
```markdown
# 团队分享: 如何避免类型定义不同步
**背景**: 本周遇到3次类型定义与数据库不一致的问题
**解决方案**:
1. 使用 drizzle-kit 自动生成类型
2. 添加 pre-commit hook 检查类型
3. 在CI中运行类型检查
**效果**:
- 类型错误减少80%
- 节省每周2小时调试时间
**推荐**:
所有项目采用此方案
```
---
## 常见问题
### Q1: 报告太长,如何控制篇幅?
**A**:
- 概述和总结要简洁(各1-2段)
- 错误描述要完整但不冗余
- 使用代码片段而非完整文件
- 将详细的技术细节放到参考资料
### Q2: 没有遇到错误,还需要写报告吗?
**A**:
- 如果是简单修改,不需要
- 如果是复杂功能,可以写"开发总结"而非"反思报告"
- 重点记录设计决策和架构考虑
### Q3: 如何处理重复出现的错误?
**A**:
- 在报告中引用之前的相关报告
- 分析为什么预防策略没有生效
- 更新预防策略,使其更具体
- 考虑是否需要工具或流程改进
### Q4: 报告写给谁看?
**A**:
- 首先是写给未来的自己
- 其次是团队成员
- 也可以是新人培训材料
- 甚至可以公开分享(去除敏感信息)
---
## 检查清单
在提交反思报告前,检查:
- [ ] 所有10个章节都已填写
- [ ] 错误信息完整(包括堆栈跟踪)
- [ ] 根本原因分析有深度(不只是表面原因)
- [ ] 预防策略具体可执行(不是泛泛而谈)
- [ ] 包含失败的尝试(不只是成功方案)
- [ ] 代码片段格式正确(使用代码块)
- [ ] 中文表达清晰流畅
- [ ] 文件名符合规范(YYYY-MM/DD_type_desc.md)
- [ ] 已更新索引文件(INDEX.md)
- [ ] 报告已提交到Git仓库
---
**最后更新**: 2026-02-15
**版本**: v1.0
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |