Git合并请求描述规范指南 MR自动化撰写方法

如果你正在使用WorkBuddy来自动生成Git合并请求（MR或PR）的描述，却常常感到生成的内容格式松散、信息不全，或者与团队的规范模板不符，那么问题的核心很可能在于：AI缺乏对项目特定上下文的结构化理解。

简单来说，WorkBuddy默认的生成逻辑是基于通用语言模型的“自由发挥”。它不会主动读取你项目中定义好的规则文件，例如 .gitmessage、.github/PULL_REQUEST_TEMPLATE.md，或是CI/CD流水线中设置的字段约束。这导致其生成的描述常常“天马行空”，难以符合团队既定的协作规范。

无需担心，这个问题有系统的解决方案。核心思路是将项目级的规则与约束“注入”给AI，引导它从“自由创作”转变为“命题作文”。以下四个步骤，从直接到深入，将帮助你系统性地解决MR/PR描述不规范的问题。

一、挂载项目级 PR 模板作为上下文源

这是最直接有效的方法。与其让AI猜测所需格式，不如直接将标准答案——即项目中现成的PR模板文件——作为生成时的参考依据（context）。这能确保输出严格遵循模板中定义的字段顺序、必填项和占位符语义，从根本上杜绝结构错乱。

具体操作分为四步：

首先，确认你的项目根目录下存在标准的PR模板文件，常见路径为 .github/PULL_REQUEST_TEMPLATE.md 或 .gitmessage。

接着，在WorkBuddy的workflow配置文件中，定位到context字段，将模板文件的路径添加进去。例如：context: [".github/PULL_REQUEST_TEMPLATE.md"]。

然后，务必检查文件权限与路径拼写，确保WorkBuddy具备读取该文件的权限。

最后，在给AI的prompt指令中，需要明确“点题”。可以这样表述：“请严格依照 .github/PULL_REQUEST_TEMPLATE.md 文件的结构生成MR描述，不得增删任何章节，所有 [ ] 形式的占位符都必须替换为实际内容，若某项为空，则填写‘无’。”

二、在 workflow 中嵌入结构化校验与补全环节

如果说第一个方法是“考前给大纲”，那么这个方法就是“考后加批改”。它在AI生成描述之后，通过一个自动化的校验步骤，强制检查结果的完整性，甚至能自动补全缺失的信息。

操作上，你需要打开当前使用的workflow文件，例如 ~/.workbuddy/workflows/create-pr.yaml。

在 generate_description 步骤之后，新增一个名为 validate_and_enrich 的步骤，类型设置为 run_script。脚本内容可以是一个简单的Python检查程序，例如验证是否包含了“## 变更摘要”、“## 关联 Issue”、“## 测试验证”这些必有的章节标题。

你还可以进一步添加一个 post-process 步骤，用于自动补全缺失的字段。例如，编写脚本自动从git log历史中提取本次提交关联的Issue编号，并填充到对应位置。

配置完成后，保存文件，并执行 workbuddy run create-pr --no-cache 来强制重新运行整个流程，以验证校验和补全机制是否生效。

三、使用 Prompt 注入带校验逻辑的生成指令

如果你不希望修改配置文件，或者需要快速为某个临时分支适配，那么优化Prompt指令是一个轻量且高效的方案。此方法的精髓在于，用一段高度精确、自带校验逻辑的自然语言指令，驱动AI在单次响应中完成“生成、自检、修正”的全过程。

你可以尝试输入如下完整的Prompt指令：

“你是一名资深Git协作工程师，请为本次MR撰写一份完全符合以下所有要求的描述：

① 标题必须以 feat/fix/chore 开头，后接冒号与空格；
② 正文首段为20字以内的功能概要；
③ 必须包含三个二级标题：## 变更摘要（分点列出代码改动）、## 关联 Issue（格式必须为 Closes #123）、## 测试验证（说明本地验证方式与结果）；
④ 生成后，请逐项核对上述四条要求，若有任何一条不满足，立即修正并重新输出完整的描述。”

这里有两个关键优化点需要注意。第一，在指令中明确禁止使用“大概”、“可能”、“建议”这类模糊词汇，所有关于测试验证的描述，都必须包含具体的命令和预期的输出片段。例如：“运行 npm test -- --testPathPattern=auth.spec.ts，所有测试用例返回PASS状态，且覆盖率不低于92%。”

第二，在最终提交前，建议手动确认生成内容中关联的Issue（如 Closes #123）在当前仓库中真实存在且状态为Open，以避免引用错误。

四、对接 CI 流水线实现提交时自动注入

这是最彻底的解决方案，旨在从源头——Git提交阶段——就实现规范化。该方法将MR描述的生成动作“下沉”，利用Git的 pre-commit 或 commit-msg 钩子，在开发者执行 git commit -m 命令时，自动触发WorkBuddy生成一份结构化的描述初稿。

如此一来，开发者在推送代码前，就可以基于这份初稿进行微调，然后再用于创建PR。这保证了所有PR描述的源头都是一致且规范的。

具体实施路径如下：

首先，在项目根目录初始化Git钩子路径：git config core.hooksPath .githooks。

然后，创建 .githooks/commit-msg 脚本，在脚本中调用WorkBuddy CLI命令，例如：workbuddy run generate-pr-desc --input $1 --output /tmp/pr-desc-draft.md，其中 $1 是提交信息。

接着，在WorkBuddy的workflow中配置好 generate-pr-desc 任务，定义其输入为单行commit message，输出指向刚才的草稿文件。

此后，每当开发者执行 git commit，系统就会自动生成描述草稿。在最终推送代码前，开发者可以手动编辑项目PR模板文件（如 .github/PULL_REQUEST_TEMPLATE.md）中的对应字段。

最后，当在GitHub上触发PR创建时，平台会自动读取这份已经编辑好的模板文件并填充内容，完全无需二次复制粘贴，彻底杜绝了格式错位的可能性。

通过以上四种方法，你可以根据团队和项目的实际情况，灵活选择或组合使用，将WorkBuddy从一个“有想法的写手”，训练成一位“严谨规范的文书员”，确保每一次的MR描述都清晰、标准、省心。