Skip to content

foryourhealth111-pixel/Vibe-Skills / bundled/skills/commit-with-reflection

commit-with-reflection

Verified

Git提交与调试反思报告生成技能。用于分析开发过程中的错误、调试步骤和解决方案,生成结构化的中文反思报告,并创建包含报告引用的Git提交。显式请求词:反思提交、智能提交、生成调试报告、commit with reflection。

FileKindSize
README.mdmarkdown5.1 KB
SKILL.mdskill md20.9 KB
assets/template-chinese.mdmarkdown1.4 KB
examples/feature-example.mdmarkdown19.9 KB
references/best-practices.mdmarkdown18.1 KB
references/error-taxonomy.mdmarkdown12.4 KB
references/index.mdmarkdown2.9 KB
scripts/update-index.jsscript11.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
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall