一句话结论
代码注释与提交信息规范化，本质是定一份团队共用模板，再用 AI 把历史留言对齐，最后产出一份能贴进仓库的规范清单。
这篇解决什么问题
同一个仓库里，有人写”fix bug”，有人写”修复支付回调重复问题”，注释更随缘——三个月后连写的人自己都要读一遍才敢改。
这篇讲的就是把这两件事拧成一套能执行的规则，顺带把历史留言拉齐。适用：三到二十人、代码已经挂在 Git 上的研发团队。
不适用：一次性的个人脚本、还没进版本管理的实验代码，写了也没人看。
开始前要准备什么
- 一个能访问的仓库，最好有几十条以上历史提交当样本
- Cursor 或 Trae 任选一个，免费额度够用，网页对话工具也能顶上
- 三行项目背景：技术栈、团队人数、日常提交习惯
- 留出两小时，其中调模板文件大概占三分之一
具体怎么做
第 1 步 · 定字段口径
先别急着写规则。我踩过的坑是：一上来列十几条”必须”，团队当天就开始阳奉阴违。这一步只做一件事——让 AI 从项目现状里挑出真正值得写进规范的几项。
你是资深研发工程师，帮我提炼代码注释和 Git 提交信息需要统一的字段口径。项目背景：订单服务 order-service，Java + Spring Boot，团队 6 人，日常用 Cursor 和 Trae 写代码，历史提交约 200 条。请按下面格式输出：一、注释必须写的三件事，每件配一句说明；二、提交信息必须写的三件事；三、可以完全不写注释的三种情况。只给结论，不要解释推理过程。
预期产出：三组短清单，加起来不到一屏，后面所有步骤都围绕它展开。
第 2 步 · 生成规范清单主体
把上一步的结果原样贴进去，让 AI 写成表格。有个小技巧：要求每条规范配一个反例，反例比正向描述好记得多。
基于下面这份字段口径，写一份能直接贴进仓库 README 的《注释与提交信息规范清单》，用 Markdown 表格呈现。字段口径：注释要写函数意图、入参与出参含义、边界条件与异常；提交信息要写类型（feat / fix / refactor / docs / chore）、影响范围、一句话说明。要求：一、表格列固定为”场景 / 必须写什么 / 反例”；二、反例要短，不超过 15 字；三、不要出现”尽量””建议””可以”这类模糊词；四、总行数控制在 8 到 12 行。
预期产出：一张 Markdown 表格，复制进 README 就能用，这就是最终要交付的规范清单。
第 3 步 · 落成两个仓库文件
清单只写在文档里，过两周就没人翻了。真正起作用的是提交时自动弹出来的那个模板。
请给我两个可以直接复制的文件内容。第一个是 .gitmessage，包含类型、影响范围、一句话说明、关联 issue 四行，每行后面带一句中文注释提示，整行用 # 注释掉。第二个是 commitlint.config.js 的最小配置，允许的 type 为 feat、fix、refactor、docs、chore、test，subject 长度上限 72 个字符。最后再给我一行命令，把 .gitmessage 设成当前仓库的默认提交模板。不要依赖任何需要单独开通的外部服务。
预期产出：两个文件的具体内容，加一条 git config commit.template 命令；随便提交一次就能看到模板弹出来。
第 4 步 · 抽查历史提交
历史提交不要动。改写历史会打乱所有人的本地分支，代价远大于收益。抽一批当反面样本就够了。
下面是我从这个仓库里抽的一批提交信息，请逐条改写，原意保持不变。原始信息：改了下代码 / fix bug / 111 / update / 支付回调偶发重复的问题处理 / 优化一下 / 临时提交 / 修改配置文件。输出格式：原信息 → 改写后 → 这条为什么不合格（一句话）。改写规则：类型 + 影响范围 + 一句话说明，说明用中文、动词开头、不超过 40 字。
预期产出：八组对照示例，其中几条会被判成”信息量为零”，正好当团队内部的反面例子用。
第 5 步 · 塞进评审环节
规范的最后一步，是变成评审时能问出口的问题。我把下面这段设成固定句式，谁评审谁用。
你是代码评审人。我给你一段改动摘要，请判断它是否符合我们的规范，并指出需要补哪一句注释。规范：一、新增的公开函数必须有意图注释；二、修改了边界条件必须在提交信息里说明；三、不允许只有”优化””调整”这类提交信息。改动摘要：（把改动文件、函数名、变更点贴在这里）输出格式：合规 / 不合规 + 缺什么 + 建议补上的注释原文。
预期产出：一条固定的评审句式，来回几次之后，团队自己就会照着问。
实测记录
| 环节 | 实际情况 |
|---|---|
| 提炼字段口径 | 约 8 分钟，来回改了两轮 |
| 生成规范清单 | 约 10 分钟，基本一次成型 |
| 模板与提交校验 | 约 20 分钟，大半花在调报错提示 |
| 历史样本改写 | 约 12 分钟，大半被判信息量为零 |
| 团队跑第一周 | 返工集中在说明写得太笼统 |
最容易错的 3 个地方
- 只写正向规则，团队记不住。每条后面补一个短反例，比多写三句解释管用。
- 想批量重写历史提交，会打乱别人分支。历史只抽样本，规则只管新提交。
- 清单一次写三四十条，没人看。先压到 8 条以内，跑两周再往上加。
可复用的东西
把前面五段提示词按顺序存进同一个文件：字段口径提炼、清单生成、模板文件、历史样本改写、评审自查。换项目时只改开头的项目背景和技术栈，其余照抄。
规范清单本身建议控制在 12 行以内——注释三类、提交三项、反例若干，贴在 README 最上面，比塞进 Wiki 深处有用得多。
你们团队现在的提交记录，随便翻十条，有几条能一眼看懂在改什么？
常见问题解答
代码注释规范要写多细？
只约束必须写的三类——公开函数的意图、参数含义、边界与异常。其余交给代码本身，写太细没人维护，反而变成噪音。
用 Cursor 还是 Trae 做这件事，差别大吗？
差别不大，都能读代码、生成 Markdown。区别在能不能直接改仓库文件，支持文件编辑的省掉复制粘贴；网页对话工具也行，只是多几步手工搬运。
这套东西落地要多久？
从提炼口径到模板生效，通常两小时以内。真正的成本在后面两周的执行，评审时多问一句，比写规则费劲。
历史提交太乱，要不要统一改掉？
不建议。重写历史会影响所有协作者的本地分支。抽一批当反面例子就够，规则从下一个提交开始生效。
三五人的小团队值得做吗？
值得，但可以更轻。小团队只保留提交信息模板和公开函数注释两条，清单越短越容易活下来。
本网站的部分内容可能来源于网络或用户投稿，仅供大家学习与参考，如有侵权，请联系客服： hhxmw778 进行删除处理。
本站一切资源不代表本站立场，并不代表本站赞同其观点和对其真实性负责。
教程如引导您添加微信或有另外收费服务，请自行甄别！
如遇充值环节或绑定支付账户或输入支付密码之类的异常步骤，建议停止操作！本站不对操作项目的损失负责！
本站一律禁止以任何方式发布或转载任何违法的相关信息，访客发现任何资源有问题请向站长举报下架
(手机微信用户建议用默认浏览器打开，可体验完整功能)