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。 不过，如果某一章节不适用，请明确写 "未发现" / "不涉及" / "不适用"，不要直接省略。