全景图

一张图看懂:两个人、一个仓库、互不踩脚

协作这几篇——并行开发的秩序、协作的架构与权限、不写代码的人怎么借 AI 干活、还有那篇接入实录——讲的其实是同一套秩序的四个侧面。这一页把那套秩序画成一张图。先看懂结构,再进任何一篇,都不会迷路。

多人共用一个仓库,最怕的不是不会改代码,是互相踩脚:你覆盖我的成果,我基于过时的事实乱指挥。而这套秩序的全部目标,是让踩脚在结构上不可能发生——而不是靠每个人时刻小心。

三个地方,两个方向

两台电脑 + 一个中心仓库 + 一台生产服务器

【你的电脑】

  • 一条线 · 主责自己的目录
  • 大脑读全库、定位、出任务单;双手照单改码
  • 本机有一份完整副本

【两台电脑之间】✕ 没有连线——从不互传文件、不登录对方电脑

【同事的电脑】

  • 另一条线 · 主责另一个目录
  • 执行 AI 照单改码,本地验证
  • 本机有另一份完整副本
【通道 · 你的电脑 ↕ 中心仓库】↓ pull 取最新 ↑ push 直推主干(负责人)
【通道 · 同事的电脑 ↕ 中心仓库】↓ pull 取最新 ↑ push 分支 → 开送审(PR)

【中心仓库】☁️ 托管平台上的私有仓库 · 主干

  • 装的是两样东西:代码实况 + 业务知识文档
  • 唯一事实源

↓ 仅负责人手动执行

【生产服务器】🔒 按主干部署 · 同事们每天在用的正式系统

两台电脑彼此之间没有任何连线——所有信息都绕经中间那个仓库。谁想知道对方干了什么,自己去仓库取。这就是"各自随时开工、互不等待"的结构基础;也是中间那个仓库被称作唯一事实源的原因:判断任何事"现在是什么样",以仓库里的为准——不以谁的记忆、聊天记录、或某台电脑上的副本为准。

四个最容易想错的地方

这张图上有四个地方最容易想错。每一个想错,都会在某一天变成一次真实的事故。

澄清一 「实时同步」不存在——每台电脑上的是一张照片

中心仓库的主干变了,你的电脑不会有任何反应:不提示、不下载、什么都不发生。你手上那份是一张照片,拍摄时间=你上次 pull 的时刻。三天不 pull,你看到的就是三天前的世界。

所以规矩只有两条:开工前 pull 一次(重新拍照),收工 push 出去(把成果送上去)。中间那段时间你完全独立,断网也能干。

最容易漏的一步:合并了对方的改动之后,自己也得 pull 一次——合并只改了托管平台上的内容,你本机一个文件都没变,而且没有任何提醒,全靠纪律。

深读出口 →

想看这套"照片模型"在两台机器之间怎么不弄乱 → 《一个仓库、两台机器:并行开发不弄乱的秩序》

/learn/dev/parallel-dev

澄清二 两条通道不对称——不是层级,是爆炸半径

图里两条上行通道不一样:一边直推主干,一边走分支加送审。看起来像权限高低,其实是爆炸半径管理:主干直连生产,主干上一个坏提交,正在用系统的同事当场受影响。

分支的意义是把爆炸半径压到零:合并之前,你的改动只存在于自己的分支上,对线上的影响是零——放心大胆地试,改错了也不要紧。这是保护,不是限制。

还有一个白拿的好处:送审页面会自动比对你的分支和最新主干有没有冲突,有就标红。这是一个免费的对齐检测器,不需要任何人盯着。

深读出口 →

账号、机构、权限分级怎么搭 → 《别共用一个账号:多人协作的架构与权限》

/learn/dev/collaboration

澄清三 大脑与双手,以及中间那张单子

AI 在这张图里分两层用:一层当大脑,读整个仓库——代码加文档——定位问题、写任务单;一层当双手,拿到单子照着改。单子上写全四样:定位结论、锚点、红线、验收判据。

反直觉的一条:双手不需要、也不应该读整个代码库。让它自己满仓库翻,是跑偏的主要来源——它会"顺手优化"一堆没让它改的东西。通盘了解是大脑侧的活;任务单存在的意义,正是让双手不必重建这份了解。

还有一条铁的:AI 从不碰提交、推送与部署。这些永远是人亲手做。

深读出口 →

不写代码的人怎么借 AI 改、权限怎么划 → 《他不会写代码,但 AI 会》

/learn/dev/delegation

澄清四 真正会撞车的不是代码,是共用文档

代码有物理分区:一人主责一个目录,合并的时候根本不碰头。文档没有分区——共用的大文档,两个人同时往里写就会相撞。

更麻烦的是:代码撞车,电脑会报错拦住你;文档撞车,有时不报错,悄悄就丢了东西。解法是把写入方收敛成一个人:另一方的产出走"一事一文件",要进共用文档的信息写在送审描述里,由那个人统一收进去。这不是官僚,是成本账。

想看这套秩序真的跑起来是什么样——包括当天撞上的坑——有一篇全程实录。

深读出口 →

《第二个人进来那天:一次真实接入的全程实录》

/learn/dev/collab-onboarding

只需要形成肌肉记忆的,是这三条

前面的原理都可以现查,这三条要不假思索。

① 开工第一条命令永远是 pull

它刷新的不只是代码,是 AI 的认知。不 pull 就开工,等于让 AI 拿着上周的地图做今天的判断——而且它不会报错。pull 报冲突:停下来问,不硬合。

② 分支不过夜

分支越老,离主干越远,冲突面不是线性增长。一次送审只做一件事,当天开当天合。

③ 提交前数一眼文件数

工作区里有故意不入库的文件,一个"全部提交"会把它们全卷进去。提交前看一眼这次动了几个文件——数字不对就停,不需要看懂内容。

三条都是用一个机械动作,换掉一次需要判断力的场面。不懂代码也能执行——这正是它们有效的原因。