你的Git提交记录，正在暴露团队的混乱

我见过太多工程师的提交记录写着"fix: broken links"或者"feat: build core payment feature"。诚实吗？诚实。能跑吗？能跑。但当团队扩张、CEO追问六个月前为什么砍掉那个功能时，这句"broken links"就成了 liability——不是答案，是 liability。

如果你发现自己花在翻 Slack 线程和过期 Notion 文档上的时间，比写代码还长，问题不在工具，在流程。Git 本身就是文档，而且它是唯一能和代码版本强制同步的 artifact。

当然，内部工具、原型、只有两个人维护的数据管道，写"fix: broken links"完全没问题。不是每个仓库都需要 FAANG 级别的提交纪律。这篇文章只写给那些被 micromanagement 折磨的团队、大组织里的工程师、以及需要向客户证明工作量的咨询师。判断标准很简单：如果项目有外部利益相关者监督，且需要长期维护，提交记录就必须有纪律。

Git 是产品文档。如果你还在用外部工具记录代码 trade-off 和实现细节，流程需要改进了。重大架构决策和业务层细节当然可以单独成文，但代码层面的上下文应该留在 Git 里。更重要的是，机器正在读你的提交历史——AI agent、自动 changelog 生成器、技术审计员，他们都会基于你的提交记录做判断。你得为他们结构化这些信息。

第一，实施提交范围限定（Commit Scoping）。

通用提交没问题，但带 scope 的提交能创建地图。用 git log --grep 命令时，逻辑结构一目了然。采用 Conventional Commits 这类约定，能立即提供上下文。

反面教材：feat: add Stripe support

更好：feat(payments): add Stripe integration for subscription billing

修复：fix(payments): add missing idempotency key in Stripe webhook

这样任何开发者都能过滤历史，瞬间看到所有触碰过支付网关的变更。

第二，把 Pull Request 当成故事来讲。

PR 不应该是代码倾倒场。我的建议：控制在 200-300 行以内；解释业务意图，不只是技术实现；附上截图、视频或终端输出来证明能跑；标题里关联具体的 issue 或 ticket 编号（如 #125），这能在任务管理和代码之间创建双向链接；用 draft 模式标记进行中的工作；分配 reviewer 之前先自己 review 一遍；回复评论、推送 fixup 提交，然后有纪律地 squash。

第三，善用提交正文（Commit Body）。

大多数工程师把提交信息当短信写——短、急。这正是价值流失的地方。对于重大功能或复杂重构，务必利用提交正文。

示例：

feat(payments): implement PayPal strategy for enterprise billing

正文：

- Adds PayPal as secondary payment provider alongside Stripe

- Required for enterprise customers with existing PayPal contracts

- Implements idempotency layer to prevent duplicate charges

- See ADR-042 for architectural decision on payment abstraction

六个月后，当审计员问"为什么支持 PayPal"时，答案就在 git log 里，而不是某个已归档的 Slack 频道。

我见过一个团队因为提交记录混乱，花了整整两天复盘一个三个月前的功能回滚决策。CEO 在会议室里盯着投影屏上的 fix: stuff 和 wip: changes，表情从困惑变成愤怒。那两天的人力成本，足够重构整个提交规范了。

Git 是你的记忆。当团队规模、项目复杂度、外部监督这三项中任意一项上升时，提交纪律就从"锦上添花"变成"生存必需"。不是为了让代码更好看，是为了让你在凌晨两点被叫起来排查问题时，能在十分钟内而不是十小时内定位上下文。

开始的方式很简单：下次写 git commit 时，多打两行字。说明为什么做这个变更，而不仅仅是什么变更。你的未来自己会感谢现在的你。