全景图

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

协作这几篇——并行开发的秩序、协作的架构与权限、不写代码的人怎么借 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 报冲突:停下来问,不硬合。

② 分支不过夜

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

③ 提交前数一眼文件数

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

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

规矩是真的,闸未必是有的

上面三条铁律,读起来像是系统会帮你盯着。实际未必——常见的代码托管平台,私有仓库在免费档位下开不了「分支保护」这道闸。这意味着:不该直推主干的,技术上推得上去;检查红灯时,合并按钮照样能点;该谁审的,也不会自动指派给他。

规矩仍然成立,只是这个阶段它靠的是人,不是机器。这不丢人——两个人、约定还新鲜、改动量不大的阶段,这样跑完全可以。要紧的是你知道自己此刻站在哪一档,以及什么时候该换档。

换档要花钱,那就得算账。怎么算,下面这张表和一句算法给你。

这一页出现过的词

讲协作绕不开一批词。这里按人话说一遍,看完不用回头再查。带链接的几个,概念词典里有更细的一条。

构建(build)
把源代码打包成可运行成品的过程。它同时是一道免费体检:代码有低级错误,构建会直接报红失败。构建绿=至少能跑起来,不代表逻辑全对。 细讲见词典《源码与生成物
仓库副本(克隆)
每台电脑上那份完整的仓库拷贝,含全部历史。它是一张「照片」——拍摄时刻=上次取最新的时刻;不主动取,它永远不会自己更新。 细讲见词典《代码仓库
生产服务器
跑着正式系统、每天真实被使用的那台服务器。它按主干同步,是「主干就是生产」这句话的物理落点。 细讲见词典《部署
取最新(pull)
一条命令:把平台上主干的最新内容取下来,更新我这台电脑的副本。开工第一动作,真正作用是给协作双方换上同一张最新地图。 细讲见词典《提交与推送
主干(master / main)
仓库的主线,所有人的改动最终都汇入这里。服务器按它部署,所以主干的内容=线上系统的来源。这也是「主干就是生产」的含义。 细讲见词典《分支
合并请求(PR)
一份「我改了这些,请过目后并入主干」的申请单。页面上能看到全部改动对比、讨论区和合并按钮。它就是异步协作台。 细讲见词典《送审与合并
合并(merge)
把分支上的改动正式并入主干的那个动作。合并后改动进入主干——但合并不等于上线,部署是独立的下一步。 细讲见词典《送审与合并
审查(review)
合并前的人工过目。看的是机器管不了的四条:改动范围、口径一致、有无误伤、理解对不对。不挑语法——语法有构建管。 细讲见词典《送审与合并
请求修改(Request changes)
审查的一种结论:「有问题,按我标在具体行上的意见改」。对方在同一分支改完再推,自动更新进同一份合并请求,不用新开。
唯一事实源
判断「现在系统到底是什么样」时,唯一算数的那份依据。约定:以平台上的主干为准——不以任何人的记忆、聊天记录、或某台电脑上的副本为准。
踩脚
两个人同时改同一处,一方把另一方的成果覆盖或搞乱。整套协作流程的设计目标,就是让踩脚在结构上不可能发生,而不是靠小心。
自动成立
指「不需要额外做任何事就天然为真」。说「对齐不是把代码放一起就自动成立的」——意思是:对齐要靠约定和动作持续维持,放一起只是前提。
代码实况
代码此刻真实的样子——打开代码看到的,而不是记忆里、聊天里、旧文档里说的样子。判断一律以实况为准。
机器
泛指每人自己那台电脑。「两台机器之间没有连线」=双方从不直接互传文件,一切经由中间的仓库。
共管区
两条线都会碰到、动了会影响对方的区域:数据结构、对外接口、共用文档。规矩统一是「只增不改,要改先打招呼」。
各自为营只对代码成立,对文档不成立
代码有物理分区(一人一个目录,合并永不碰头);共用文档是单个文件,两人同时写必然相撞。所以代码可以放手各干,文档必须约定「只有一个人写」。
断网也能干
因为副本是完整的(含全部历史),中间干活不需要联网。只有开工取和收工送两个时刻需要网络——这就是「各自为营」的技术底气。
爆炸半径管理
一项改动出错时,波及范围有多大、能不能控制住。分支的意义=把爆炸半径压到零:合并之前,改动只存在于自己的分支上,对线上影响为零。
全员合并请求制
所有人(包括负责人)都走合并请求、没有任何人直推的模式——多人团队的标准形态。小团队常见的过渡期形态是:新加入者走合并请求,负责人保留直推,跑顺后再议。
对齐检测器
指合并请求页面的自动冲突检查:平台自动比对你的分支与最新主干,有冲突就标红提示。免费、自动、不需要任何人盯着。
这不是官僚,是成本账
流程取舍的标准不是「正规不正规」,而是哪种做法总成本更低。例:共用大文档约定一人写,比教会每个人处理几十万字的合并冲突,便宜一个数量级。