基础代码协作

提交信息：让改动自己说话

忙到傍晚，改动散在十几个文件里，写提交信息时只剩下「修了点问题」这种句子。队友过两周再来看，完全不知道当时为什么动。

把这件事交给它，前提是让差异当素材：

看一下当前暂存区的改动，用约定式格式写一条提交信息： 类型前缀从新增、修复、重构里选一个，一行摘要说清结果； 空一行，再用三条要点列出主要变化。 不要出现「若干优化」这类空话。

类型前缀、摘要长度、要点数量，都可以按你们仓库的习惯调整。关键是先定格式，再让它填内容，而不是让它自由发挥。

合并请求：描述、自查、拆分

一份能减少来回的合并请求说明，通常包含四块：改了什么、为什么改、怎么验证、哪里需要特别看。可以直接这样要求：

基于当前分支与主干的差异，写一份合并请求说明：

1. 改了什么，三到五条；
2. 背景与取舍，为什么选这个方案；
3. 验证步骤，照着做能复现；
4. 风险点，以及希望审查者重点看的地方。

提交之前，再跑一轮自查清单：

• 全量测试是否通过；
• 边界情况有没有遗漏；
• 调试打印和临时开关是否清理干净；
• 新增入口有没有补齐出错处理；
• 格式检查有没有告警。

清单不用多，五条能每次都跑完，比二十条挂在墙上强。

改动横跨多个功能时，先问它怎么拆。原则只有一条：每个合并请求只做一件事，单独合入也不会让主干坏掉。

审查：自己先过一遍

让它审查你刚写的代码，比自己盯着看更容易发现问题：

帮我检查刚完成的改动，从四个角度给结论： 判断逻辑站不站得住、有没有安全隐患、开销是否异常、写法合不合项目约定。 指到具体行，不要泛泛而谈。

支付、权限这类敏感模块，再加一句「重点关注金额校验、重复提交防御、失败回滚」。别人提交的改动，先让它讲清实现思路，再问潜在风险，比直接下结论可靠。

但要把边界说清楚：机器审查是加速器，不是替代品。业务规则是否成立、方案取舍是否合理，仍要由熟悉上下文的人判断。人工把关的位置见人在回路。

把团队规范写进配置

同一个团队，每个人提的要求不一样，产出自然不一致。把约定固化到项目根目录的 CLAUDE.md，每次调用都会读到：

• 目录职责与命名习惯；
• 组件写法，比如接口定义、显示名、样式来源；
• 允许使用的依赖范围；
• 哪些命令必须先征求同意。

有了这份文件，批量整理旧代码、统一出错处理写法、补注释文档，都可以一句话发起。规范变了就改文件，不用逐个通知。规范文件不是写给机器看的公文，写成能执行的短句才有用。

文档：让下一个人少问

代码里的知识，不写下来就只存在于几个人的记忆里。三类文档最适合交给它起草：

函数注释。 指定文件，要求写清四件事：函数做什么、每个入参的类型与业务含义、返回什么结构、什么情况下抛错。比如：

给 src/services/orderService.ts 里的公开函数补 JSDoc：入参写类型和用途，返回值写结构，可能抛出的异常单独列出。

接口文档。 从路由文件反推，按「路径与请求方法、入参、返回结构、错误码」逐条列。生成后拿一条真实请求对一遍，确认字段名没有臆造。

决策记录。 每次做了影响后续的选型，就留一份短记录：当时的问题与约束、比较过哪几个方案、最后选了什么、代价是什么。四段即可，不必长篇。

把这次「认证改为短期令牌加刷新令牌」的决定写成决策记录：背景与约束、备选方案、最终选择及理由、遗留风险。

文档要和代码放在同一个仓库、同一次提交里。放在网盘或聊天群里，半年后没人找得到。常用指令可以收进提示词模板，下次换几个变量就能复用。

协作里最常见的三类返工，也可以照着排：

现象	为什么	怎么办
提交信息只有「更新」	写的时候没看实际差异	先让它读暂存区差异，再按类型前缀归纳
合并请求没人愿意细看	一个请求塞了几件事	按功能拆开，每个都能单独合入
规范执行时好时坏	约定只停在口头和群公告	写进仓库根目录的配置，审查时逐条对照

Git 出问题时

日常还有三类事可以交给它：

• 合并冲突：让它分别解释两侧改动，再给合并建议，你只做最后确认；
• 定位问题提交：描述症状和出现时间，让它从近期提交里找可疑改动；
• 接手模块：要一份功能边界、数据流、遗留问题清单，快速建立判断。

这些结果都要回到代码和日志里核对。它给的是线索，不是结论。核对时优先看日志和测试结果，它们不会替自己辩护。

会写、会改、会合作，下一步是把工具本身的命令用顺。下一节从整体看命令体系：命令系统简介。