# Commit Design Doc

> 基于当前 commit 或指定 commit range 生成代码设计文档，重点分析算法代码改动、代码重构改动，并输出结构化Markdown文档

- Skill: `jiangyinzuo/commit-design-doc` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jiangyinzuo/commit-design-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jiangyinzuo/commit-design-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: jiangyinzuo (https://skillmd.com/u/jiangyinzuo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jiangyinzuo/commit-design-doc

---


# Commit Design Doc

## 目标

根据当前仓库中的 **当前 commit** 或 **指定 commit range**，生成一份**详细的**代码设计文档，
你需要在代码文档中详细说明背景问题、算法设计、代码实现、重构模块、测试设计与实现。

文档的重点不是简单罗列 diff，而是：

1. 整体算法设计
2. 详细分析代码改动
    - 哪些改动属于 **算法代码改动**，对算法代码改动，详细说明改动的前后逻辑
    - 哪些改动属于 **代码重构改动**
    - 每一处改动的目的、位置、实现方式、影响范围（功能/性能）
    - 是否存在潜在风险、兼容性影响、验证建议
3. 测试设计
    - 功能测试
    - 性能测试

## 输入

输入应当包含两部分：

1. 问题背景（issue、需求分析文档等等）
2. 当前仓库上下文。若用户没有明确指定范围，默认分析 `HEAD~1..HEAD`。若用户指定了 commit、branch、tag 或 range，则按用户指定范围分析。

## 你需要完成的事情

读取背景需求、git 历史和代码 diff，并基于代码语义而不是仅基于文本变化，输出一份高质量的、**详细的**设计文档。

### 核心要求

必须重点识别并单独成节输出以下内容：

1. 算法整体改动设计
2. 算法代码具体实现改动。这一步请适当贴出变更前后的源代码 / 伪代码。
3. 代码重构改动

## 不要做的事情

以下内容不要作为重点，不要喧宾夺主：

- 纯格式化改动
- 纯注释改动
- import/include 顺序调整
- 无语义变化的 rename
- 自动生成文件变动
- 构建产物、临时文件
- 与设计无关的机械性修改

如果某些文件只包含上述噪音，可以在“非重点改动”中一句话带过，不要展开。

---

## 分析步骤

请按照**三阶段生成**。

### 第一阶段：将diff hunk按照算法改动与代码重构进行分类

在这一阶段，请将diff改动根据类型分类。列出改动的**文件与行号**、关键代码片段。
请不要忽视任何改动。即使是不重要的改动，如格式化改动、重命名、调整函数参数等简单改动，也请列出文件位置和行号。
请将diff改动分类后输出到Markdown，供其他人类reviewer参考。

**注意**：

不要直接写一连串原始hunk header，而是要改写为“每个改动函数/区域 + 当前 commit 中的行号 + 分类 + 关键片段”，方便人类reviewer 阅读。

### 第二阶段：确立文档大纲

在这一阶段，请根据实际项目背景、改动内容来为后续的设计文档草拟一份大纲。请将大纲保存为一份Markdown，供用户查看指导。

### 第三阶段：根据文档大纲编写文档

在这一阶段，请根据刚才的大纲生成一份新的markdown文件，供用户查看指导。

#### 第一步：确定分析范围

优先识别用户要求分析的 commit 范围。若未指定，则默认：

- `HEAD~1..HEAD`

#### 第二步：读取提交元信息

收集：

- commit id
- commit message
- 变更文件列表
- 变更规模（插入/删除）

### 第三步：根据大纲，阅读 diff以及涉及的相关文件，生成文档

**请根据大纲内容逐章节生成文档，生成文档前按需阅读相关文件，保证上下文充分、理解全面。**
最后，输出一份结构化 Markdown 文档，而不是零散评论。

#### 文件阅读说明

优先阅读：

- 变更较大的核心源码文件
- 涉及算法、执行路径、数据结构、接口层的文件
- 被多个文件共同引用的公共模块

**注意**：

1. 为了保证上下文充分，不仅要阅读diff patch，还应当根据需要阅读完整文件；
2. 有时候即使一个文件没有被修改，但如果该文件对于理解本次commit非常重要，也应当阅读。

### 按语义分类详细改动

分析详细代码改动时，将改动分为：

- 算法代码改动
- 代码重构改动
- 接口/行为变化
- 测试与验证相关改动
- 非重点改动

**注意：**

分类应基于**语义判断**，不是简单基于文件名或目录名。

## 和用户协作改进

当用户打断你生成大纲或者最终文档的进程时，请首先重写审视大纲是否要修改，然后再修改生成的文档。

## 输出格式

输出必须使用 Markdown。
不过，如果某一章节不适用，请明确写 "未发现" / "不涉及" / "不适用"，不要直接省略。