---
title: "基础代码协作"
description: "把个人用法接进团队流程：让差异生成提交信息与合并请求说明，用清单自查，再把团队规范写成配置，减少来回沟通。"
updated: 2026-11-13
canonical: https://docai.cc/learn/basic-code-collaboration/
markdown_mirror: https://docai.cc/learn/basic-code-collaboration.md
---
## 提交信息：让改动自己说话

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

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

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

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

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

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

> 基于当前分支与主干的差异，写一份合并请求说明：
> 1. 改了什么，三到五条；
> 2. 背景与取舍，为什么选这个方案；
> 3. 验证步骤，照着做能复现；
> 4. 风险点，以及希望审查者重点看的地方。

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

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

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

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

## 审查：自己先过一遍

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

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

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

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

## 把团队规范写进配置

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

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

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

## 文档：让下一个人少问

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

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

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

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

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

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

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

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

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

## Git 出问题时

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

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

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

会写、会改、会合作，下一步是把工具本身的命令用顺。下一节从整体看命令体系：[命令系统简介](/learn/command-system-overview/)。