本文为 5 月撰写，本周于公司内部宣讲的相关架构实践，出于公开分享实践交流考虑，信息脱敏后对外公布。其内容在 7 月并不新颖，因此有需要的同学可以自取，如果熟悉的同学可以直接忽略，感觉对你有帮助的话也可以帮忙点个赞

TLDR（为方便各位同学快速判断文章质量与内容主旨，AI 生成摘要，这样就不用自己再烧 token 提取摘要了）

配合 LINUX DO 社区要求对 TLDR 生成进行截图

近期使用 OpenSpec 做了大量基于 SDD 的多人前端协同开发工作。这一块的相关经验，相比起过去常见的篝火模式分享而言，能够参考和借鉴的内容会更实际、更多一些。因此，我特地拉了这次分享，给大家介绍一下：如何运用软件工程的方法，在多人协同 Claude Code 研发的过程中，做到「不冲突、不返工」。

这与我们之前通常的宣传不同，标题里我谈的是「确保」而非「提升」，许诺的也是「不冲突、不返工」这两条否定式的底线，而不是「效率翻倍」之类的漂亮数字。这其中的区别在于，如果大家真的深度使用过 Claude Code 或者 Codex 这一类产品的话，在一个人开发的时候往往会觉得很爽——在这个阶段，人人谈的都是提升，也确实在提升；但在两到三个人针对同一个需求进行并行开发的时候，各种问题就会涌现出来，单人迭代时提升的效率，会被协作中内耗原数返还，甚至还会倒贴。所以在多人协作的场景下，重要的并不是把上限再抬高一点，而是守住下限。总结下来，这些内耗无非是两类：

1. 互相冲突打扰：多人（或多会话）的改动互相影响，分支冲突频发，解决合并冲突的时间甚至超过写代码本身，研发的心流被反复打断 —— 这是体验问题。


2. 产出不可信：Agent 生成的代码无法确定是否符合预期，交付之后被研发反复打回重做 —— 这是质量问题。

而在我们这一次 Vision Agent 的迭代开发过程中，实际上是没有模块与模块间的大量冲突的。相反，我们甚至可以做到单人在同一台电脑的同一个项目、同一个分支上，同时启动 3 到 4 个并行的 Claude Code 会话去完成当天的开发工作；并且整个迭代过程中，frontend-agent 文件夹下也没有进行任何手写代码动作。

所以这里我们主要来讨论的就是：作为前端研发，我们是如何做到这一点的？

结论先行，我们做的事情，本质上只有两件：

1. 架构拆分 → 避免冲突发生，守住协作体验下限


2. Harness 管控 → 避免频繁返工，守住对外交付质量

这里先简单解释一下 Harness 这个词。所谓 Harness，指的是围绕 Agent 搭建起来的一整套验证与约束护栏——单元测试、Storybook、E2E、Hooks、提交卡点等等的总和。Claude Code 生成代码的能力已经足够强，但生成的代码是否可信，取决于我们给它套上的这层「马具」。这也是本次分享的重点。

一、架构拆分：让冲突不发生

首先，在之前的项目实践中，我反反复复会提到一个概念，就是「架构」。

对于结构拆分这一点来说，由于当前 Vision Agent 是一个全新的项目，在这种前提之下，我就可以对前端项目进行一些更加彻底且更加激进的架构选择。

代码分层与业务域拆分

在整个仓库的代码层面，我将其分为了以下几部分：

1. 组件层


2. Utils 层


3. api 层


4. 业务组件层


5. 对应的真实业务实现

同时，这里做了数据层和视图层的完全解耦分离。这部分实践不是本文今天的重点，过去的前端实践有很多可供参考的范例，比如这篇：数据与视图分离的前端实践

在整个仓库的业务层面，根据 Vision Agent 本身的能力，将其分为了编辑器和流式渲染这两大部分。最终上线前，需要一个支持只读模式的流式渲染，因此又引入了推荐域。

其中对应的流式渲染又根据业务需要拆成了四块：

1. 意图分析


2. 大纲编辑


3. 内容选取


4. 对应的设计实现

为什么拆分之后，并行就成立了？

当我们完成了上述拆分之后，接下来前端的开发任务便可以以业务本身的区块划分来并行开发。这里需要展开讲一下背后的机制——这也是「同一分支多会话并行」能够成立的根本原因。

Claude Code 的每一个会话，本质上是在一个文件集合内做修改。当模块拆分足够松散时，每个业务模块对应的文件集合互相之间几乎没有交集：意图分析的改动不会碰大纲编辑的文件，内容选取也不会碰设计实现。此时我们只需要保证一件事——每个会话所领的任务，落在互不重叠的模块之内——那么多个会话（无论它们属于一个人还是多个人）在同一个分支上并行修改，在文件层面就不会产生冲突。

比如，在本次开发过程中，我主要处理大纲编辑及对应的设计实现这两块，另一位同学处理的是意图分析以及内容选取这两部分。由于模块天生拆分得比较松散，我们在各自做对应实现的时候，几乎很少遇到合并冲突。少数的合并冲突，仅仅体现在一些公共组件之上——这也是模块化拆分后，唯一无法被完全消除的交叉区域。

组件层：让提前确认与核对变为可能

我们针对本次开发，拆分了较为明确的组件层。组件分为两部分：

1. 业务组件


2. 当前项目的可复用组件

基于 Storybook 拆分了组件层后，前端在初期设计稿、原型稿尚未就绪的期间，就可以去跟产品确认一些初期很难确定效果的动画设计。有了组件层，我们可以直接将对应的原子组件交付给产品做先期确认，而不是等到所有的设计稿全部就绪后，再去对这部分进行确认。

二、Harness 管控：让返工不出门

架构拆分解决了「不冲突」，接下来的问题是「不返工」：Claude Code 生成的代码，如何确保其符合预期，不至于交付之后被打回重做？

在展开之前，先说一个大前提。架构防腐是一件长期工程，当我们确定了项目架构后，很难避免项目在后续的长期迭代中出现腐化迹象。此时便依赖架构师去做对应的约束和管控，且以不依赖人主观能动性的方式去实现这一目标。具体的架构防腐实践，可参考陶文老师的：modularization-examples

「不依赖人的主观能动性」，正是我们整套 Harness 的设计哲学。我们在研发流程的每一个环节上设一道闸门，让问题在脱离当前环节前便被拦下，而不是在流转到下游时才暴露。依照我们约束发生的时机排布，一共七道。

第一道闸 · 编码前：Claude.md 静态规约

由这个 Markdown 文档来规定当前项目的结构以及一些基本常识。这部分内容想必大家都已经很了解了，不再展开。

第二道闸 · 编码中：三级验证闭环

得益于我们对单元测试、Storybook、E2E 集成测试的关注，在前端的整个研发链路中，前端能够相对自闭环地让 Claude 逐级、逐层地去验证最终逻辑，大致流程如下：

1. 在逻辑刚书写完成时，使用 jest 做对应的单元测试，避免一眼能判断出来的问题


2. 在后端尚未就绪的时候，基于 Storybook 去做基于 mock 数据的组件视觉还原验证、组件的功能验证、页面的视觉还原验证


3. 在后端可进行联调的时候，基于 E2E 去做整体的链路集成测试，验证整个产品流程是否符合预期

为了让第 2、3 级能顺利运转，我们和后端之间约定了两件事：开发过程中会先制定详细的后端开发文档，规定对应的 API、入参出参以及所有的数据格式；同时在分批交付的过程中，要求后端先交付对应的 Mock 接口，让前端能先基于 Mock 接口去做后续的开发工作，这样在初期阶段，前端不至于被阻塞。

第三道闸 · 编码后：Hooks 自动触发

基于 Claude Code 的 Hooks 能力，我们会在开发者开发结束时，自动执行类型检查以及 Lint 规约。这一步不依赖任何人的主观能动性——只要会话的开发动作结束，检查就会执行。

第四道闸 · 提交时：OpenSpec 变更协议 + Husky 卡点

这里首先介绍一下 OpenSpec。OpenSpec 是近期比较流行的 SDD 研发模式中的一种方式。很多人会将其理解成其出产的是产品经理的设计文档，但实质上整个 OpenSpec 的组织模式并非是产品需求设计文档，而是更类似于研发在迭代过程中，针对每个研发变更点所记录的研发过程记录。

这保证了我们在每一个 Commit 提交的过程中，都能够有对应的 OpenSpec 文档来记录：

1. 当前提交所变更的内容


2. 其所修改的原因


3. 其所影响的范围

基于 OpenSpec 的细致记录，我们可以在后期通过 Claude Code 便捷地找到历史上我们所做过的对应变更，从而加快后续的研发迭代速度。

在卡点上我们做了两层：其一，在 OpenSpec 的每个变更进行归档时，会针对该变更执行单元测试以及端到端测试；其二，为了保证每个变更都是由 OpenSpec 触发、且不会破坏我们的规约，我们将「OpenSpec 文档是否存在且已归档」纳入了提交规范，通过 Husky 确保当前的每个提交都必须包含这一部分。

当然，这里依然存在尚未解决的问题：在多人同时于项目之中进行研发迭代时，OpenSpec 文档的量往往会急剧膨胀。这导致后续提交到 Git 之后，由于文件索引的量过大，线上平台在拉取仓库做构建的时候会变慢。这部分依然在探索有效的维护方案中。

第五道闸 · 持续：自动巡检

基于此前制定的【视图、数据分离】大前提，我们规定了对应的巡检脚本，以代码扫描的形式定期巡检这部分，并通过报告和可数据化的形式去指引 Claude 持续迭代改进。

同时，E2E 部分我们计划以【天】为维度定期执行巡检，借助 Claude Code Agent 的能力去做 E2E 用例的定期自动更新和修正，并每天以 PR 的形式提交到 gitee 上。这一部分是我们规划中的「自动化研发 Agent」方向的第一步，后文的规划部分会再展开。

第六道闸 · 定期：两周一次的 Code Review

SDD 的一大误区就是放弃 Code Review。很多人会觉得在代码量级变大的情况下，Code Review 是不必要的，但这对于 AI 辅助编程而言是大错特错的。

我们需要知道，Claude Code 这类工具在工作时，上下文窗口是有限的，它对整个仓库并没有持久的全局记忆——它每次所能「看到」的，只是当前上下文中被装入的那部分代码。对于代码开发而言，我们的提示词本身就是代码仓库：仓库长什么样，Claude 就会顺着什么样的模式续写下去。如果我们对仓库不做任何规约，在多人协同开发时，很容易出现项目结构被多次改变，或原有项目结构被破坏的情况。

为了避免这种情况，定期的 Code Review 非常重要。而且，我们的定期 Code Review 实际上也不需要像过去一样逐行去做，只需要保证之前规定的整体架构不被破坏即可。

在整个 Vision Agent 的迭代过程中，我们的 Code Review 周期平均是两周一次。每次 Code Review，我们会做这样几件事情：

1. 确保当前的整体架构不被破坏


2. 针对过去频繁变更需求所导致的单测破坏，或端到端测试被跳过的部分，做针对性的修复


3. 在调用 Claude Code 进行过一次重构后，再由人工阅读一些关键部分的代码，确保这部分代码的逻辑符合我们的要求

第七道闸 · 反馈回路提速

前六道闸门有一个共同的隐含前提：反馈必须足够快。如果每一次验证都要等上十分钟的构建，那么再完善的闸门，最终也会被开发者（以及 Agent）想办法绕过去。

Vision Agent 由于是新项目，我们采用了最新的基于 Vite 和 ESM 的构建部署策略，同时将构建部署全面迁移至新质效平台。基于该行动，我们将整个项目的构建时间由原先的 6 到 10 分钟，缩短到了现在的全程 2 分 20 秒左右。

同时，我们通过新质效平台的指定分支自动部署能力，实现了开发推送代码即自动部署前端的效果。验证的等待成本降下来之后，前面六道闸门才能真正高频地运转起来。

小结：规范是写给 Claude Code 的

与过去的规范规约不一致的是，我们这里的七道闸门，实际上是写给 Claude Code 的。过去制定这些规范时，由人工实践很难落地；但现在我们向 Claude Code 规定这些规范，就可以在相当程度上将其内化为项目中的守则。

经过上述这一系列的规约，我们才能够将 SDD 作为一个团队内部的开发守则规范共识，而不是一个仅停留在口头上的倡导来进行推广落地。

三、成果：两个承诺的兑现

Vision Agent 的迭代介绍暂时告一段落，我们来对照开篇提到的两个承诺。

不冲突这一栏：

1. 整个开发过程中，我们大量调用 Claude Code + OpenSpec 的 SDD 研发模式去做完整的开发。多人在同一个分支上进行提交，几乎没有出现过严重的合并冲突问题；绝大多数冲突都来自临时的代码回退，或少部分公用代码的修改交叉。


2. 我们甚至可以在 frontend-agent 中做到：一个项目下，同一个人同时开 3 到 4 个 Claude Code 会话进行并行修改，且多个会话间互不影响。


3. 整个迭代过程中，frontend-agent 文件夹下没有进行任何手写代码动作。

不返工这一栏：

1. 在研发过程中，为了响应产品对于交互与动效的快速确认，我们实验性地引入了 OpenDesign，配合组件层 Storybook，在整体研发尚未完成的时候先与产品确认整体交互效果，这样能降低后续由于产品变更导致的交互返工成本


2. 在自测过程中，基于完备的 E2E 用例能发现很多我们之前在研发中尚未发现的问题，甚至包括一些我们人工没有关注到的问题，这提升了我们的自测质量，从而使得在倒排期限内交付给测试的产出质量更高

总收束：

目前为止，整个代码仓库的代码行数量级约在 4 万到 5 万左右，且项目架构没有出现大的纰漏。这既得益于架构拆分从源头减少了交叉，也得益于七道闸门——尤其是 1 到 2 周进行一次的频繁 Code Review——在整个过程中的持续兜底。

四、边界与演进

老旧项目如何做 AI 研发适配？

在我看来，老旧项目的 AI 研发体验是直接与「架构合理性 + 模块耦合程度」挂钩的。很多说 Agent 难以处理老旧项目的研发，往往会忽略旧项目本身的架构质量和模块耦合程度。对于目前的 Opus 4.8 和 GPT 5.6 而言，大多数情况下它们是以一个资深研发的视角去做对应的迭代更新的——如果你自己改代码都很吃力的话，怎么能奢望 AI 改代码就比你快得多呢？

因此，对于老旧项目，如果希望做 AI 研发适配的话，第一步一般是重构。借助 Claude、GPT 对已有项目做模块拆分、架构梳理，尽可能将模块拆分到互相之间不耦合的程度，此时才能让 Claude Code 更好地处理项目本身。

下一轮规划：自动化研发 Agent —— Harness 的无人化

在前面的七道闸门中，目前的执行者是命令、Hooks，以及两周一次的人工 Review。下一波我们要做的，是把执行者逐步换成定期自动运行的 Agent——也就是 Harness 的无人化，将架构师在防腐和质量确保过程中投入的时间与精力释放出来。

这条路线分三层：

1. 第一步：E2E 日级巡检 Agent。 也就是第五道闸中提到的——以【天】为维度定期执行 E2E 巡检，基于 E2E 的执行效果去判断是否应该优化当前代码、或更正当前代码的逻辑，借助 Claude Code Agent 的能力做定期自动更新与修正，每天以 PR 模式提交到 gitee。这将是我们最先启动的一步。


2. 第二步：架构巡检 Agent。 将「巡检报告出具 → 自动迭代改进」串成闭环：巡检发现腐化迹象后，由 Agent 自动发起修复，以 PR 形式等待人工确认合入。


3. 基础设施：控制面。 上述 Agent 的调度与管理，依赖我目前正在迭代中的 cloud-agent-platform 控制面项目。后期整体流程跑通后，会单独做一次介绍。

这里也要顺带提一下我们现在的现状：由于现有基建问题（构建发布平台并非流水线概念，而是单纯的构建 + 发布）、以及资源问题（并非任何一家公司都能掏出完整的 E2E 验证集群），我们难以将 E2E 通过流水线模式整合进研发流程。这也是我们选择「日级定期巡检」而非「流水线内嵌」的原因。

潜在提升点

复盘当下的整个研发流程，协作侧还存在一些可以进一步提升的点：

1. 后端接口平台化。 目前前后端的结构约定靠的是人工维护的后端开发文档 + 手工 Mock 接口。如果后端可以接入类似 YAPI 或者 Swagger 这种平台，去做后端接口的结构及 Mock 联调的互通，我们在整个迭代过程中的前后端联调时间是能被进一步压缩的。


2. 设计交付提效。 从产品定下对应的 PRD 到设计稿就位，再到前端负责还原实现，往往需要 3 至 5 天的周期。针对于 Vision Agent 这种响应速度很快的项目而言，这个交付节奏是较为缓慢的。本次 Vision Agent 已经是 OpenDesign 的试验性运用之一（即前文成果部分提到的交互确认环节），但尚未大规模铺开。因此，我们在后期会想办法去推动产品经理全面使用 ClaudeDesign 或者 OpenDesign 等这类产品——也就是将设计稿从 MasterGo 直接转移到新工具上——来提升产品经理侧由 PRD 到设计稿的交付效率，同时规避前端在实现及设计还原上所花费的时间。


3. 测试用例前置共建。 本次迭代 Vision Agent，测试侧的人力投入实际上是偏少的，研发迭代过程中高度依赖研发在初期去做需求自测。如果研发迭代过程中，测试可以跟研发共同讨论并尽早确定单元测试用例，从而指导研发的单元测试、端到端测试用例更贴近于测试回归的真实用例，也会对后续的应用回归测试有所帮助。

结语：重剑无锋 —— 软件工程的老答案

金庸在《神雕侠侣》里写过一处剑冢。剑魔独孤求败纵横江湖三十余载，晚年埋剑立冢，将自己一生的用剑历程分作了四个阶段。

第一阶段是利剑。年少时仗一柄锋锐无比的宝剑，锐不可当，与群雄争锋。这像极了我们每个人初见 Claude Code、Codex 时的样子：单人单会话，需求进去、代码出来，招招见血 —— 单人独立开发的时候，确实会觉得很爽。

第二阶段是紫薇软剑。剑更快了、更灵了，却因为误伤义士，被他弃于深谷。这正是团队规模化用上 Agent 之后的失控期：工具依然锋利，但两三个人并行开发时，改动互相误伤、产出无法取信、项目结构被反复破坏 —— 剑越快，反而越容易伤到队友。本文开头的两个痛点，「互相冲突打扰」与「产出不可信」，就是软剑划出的那道伤口。

第三阶段是玄铁重剑，剑冢上的刻辞只有八个字：「重剑无锋，大巧不工。」独孤求败凭这柄不开锋的重剑，横行天下。而这，就是本文通篇在讲的东西——架构拆分、七道闸门、两周一次的 Code Review。这些手段没有一样是新的，它们笨重、朴素，思路均来自 80 年代的软件工程。但恰恰是这些老手段，支撑了 4 到 5 万行零手写的仓库，也支撑了同一分支上三四个会话的并行不悖。各类新概念是剑招，日新月异；软件工程是重剑，大巧不工。

至于第四阶段 —— 木剑，乃至草木竹石皆可为剑、无剑胜有剑的境界 —— 那正是我们规划中要走的下一程：当规约真正内化为项目守则，当巡检、修复、回归都由 Agent 自动运转，架构师便不必再亲自握剑，Harness 本身就是剑。这也是前文「自动化研发 Agent」一节最终想要抵达的地方。

所以，收剑回鞘，回到正题。从 Vibe-coding 到 Harness Engineering，再到后面提出的各类新概念，在我看来本质上只做了三件事情：

1. 将软件工程的概念引入起初混沌的 AI Vibe-coding 研发流程中 —— 把误伤同伴的软剑，换成不开锋的重剑


2. 通过各类手段，确保项目研发不会因为新同学、不熟悉项目架构的人、Agent 参与后导致原定结构偏移 —— 重剑压阵，结构不散


3. 通过 Agent 等方式，尽量将人的精力从重复性、可复制的任务中抽离出去 —— 渐进于无剑之境

即便如今 AI 辅助研发界的概念日新月异，但我一直认为，各类新概念只是上面几件事情的变种。正所谓万变不离其宗——至少到今天为止，真正能让团队横行天下的，依然是那柄 80 年代就已铸成的、不开锋的重剑。