一个人和几个 AI，做一套组件库

这个站的提交记录里，从 10 月 25 日到 28 日一共 197 个提交，覆盖组件、文档、区块、模板、主题、验收脚本和这几篇博客。写代码的不止一个模型：一个主控 Agent 负责拆任务和审查，几个子 Agent 分头干活，最后由主控统一提交。

这篇讲这套分工是怎么定的，任务说明怎么写才不会出岔子，以及几次验收抓出的真实问题。具体的调度规则是我本机的配置，这里讲它背后的原因。

分工：按出错代价分，不按“谁更强”分

我把角色定成四类：

分工的依据是三条：

成本。 能力强的模型额度有限，不该拿去写大批结构相同的文档。能用 Pi 完成的任务一律交给 Pi，判断标准是三点：已有可照抄的模式、验收标准明确、出错代价低。批量写组件的 MDX 文档和 demo 就符合这三点：第一个写好之后模式已经定下来，后面的照着来。

能力。 布局原语、主题系统、复杂交互组件这类要跨文件做判断的代码，交给 A 或 B。它们互为替补：看哪边剩余额度多就先用哪边，一边受限或报错就换另一边。

出错代价。 同样是写代码，改错一个 demo 只影响一个示例页，改错布局原语会牵动整站。代价越高，派给越强的模型，审查也越严。

主控自己写代码的条件很窄：任务需要跨模块判断，或者子任务连续两次失败。其余时间它做的是拆任务、审查和集成。

任务说明怎么写：自包含

子 Agent 不会读到我和主控之前的对话。它只看到一段任务说明，所以说明必须自己把事情讲清楚。每份说明都要包含四项（这部分约定写在仓库的 AGENTS.md 里，对任何用 AI 协作的贡献者都适用）：

• 目标：要做出什么，不是“改一下”；
• 要读的文件和技能：先读哪些文件、哪些技能；
• 允许修改的文件范围：写明哪些路径可以动；
• 验收标准：比如 pnpm build 通过，或者某个脚本不报错。

再加上汇报要求：修改了哪些文件，做了哪些取舍，还有什么遗留问题。一个典型的说明大致长这样（示意）：

目标：新增 tone-picker 的三个内页示例，每个示例讲一个场景。
先读：AGENTS.md，component-conventions 与 registry-item 技能，
     src/registry/examples/segmented-control-demo.tsx（照这个写）。
允许修改：src/registry/examples/tone-picker-*.tsx、content/docs/components/tone-picker.mdx。
不要改：registry.json 及其他任何文件。
验收：pnpm lint、pnpm build 通过。
不要 git commit。完成后汇报：改了哪些文件、做了哪些取舍、遗留问题。

这里面有两条规则不是凭空来的。

文件范围不能重叠。 同一个工作区里并行的子任务，如果改同一个文件，后写的会覆盖先写的。最典型的是 registry.json：每新增一个组件都要在里面登记，几个子任务同时登记就会冲突。我的办法是让子任务只汇报自己引入的依赖清单，由主控统一改这个文件。范围有重叠就串行，或者给子任务一个独立的 worktree。

子 Agent 不提交。 提交由主控在审查之后统一做，并且只暂存自己改过的路径，不用 git add -A。这条是吃过亏才定的：有一次我在同一个工作区里手改标志和文章，主控用 git add -A 把这些没改完的内容混进了两条无关的提交，后来才拆回来。

技能：把规范写下来，别每次口述

子 Agent 每次从零开始，不记得上一次的约定。所以约定得写在它能读到的地方。项目里 .agents/skills/ 下放了一批技能文件，任务说明里只需要写“先读 xxx 技能”：

• component-conventions：组件书写规范，管分层、命名、data-slot、导出方式、Props、文案、样式 token、可访问性，以及上一篇讲的“加载与占位”。写或改 src/registry 下任何代码都要先读它。
• registry-item：新增 registry 条目的完整流程，从源码位置、registry.json 登记、写 demo 和文档，到构建与安装验证。
• component-acceptance：组件从开发到验收的流程与标准，附一份可以逐条勾选的清单。
• grid-design：线条网格设计规范，页面布局都按它来。
• humanizer-zh：中文润色，博客成稿前必须过一遍。

这样做还有一个好处：规范改了，只需要改一处。像“占位层必须绝对定位，淡出之后保留的节点也不能占尺寸”这样的条目，写进 component-conventions 之后，每个读它的子任务都会按它来。

验收为什么要独立

我的结论是：实现者说“完成了”，只能当作线索，不能当作证据。下面是三个实际发生过的例子。

主题页预览区。 Codex 实现，Pi 验收，结论是“有条件通过”。它指出了两个具体问题：灰阶主题在暗色下，堆叠图里有一段几乎看不见，对比度只有 1.31:1；视口宽度在 640 到 715px 之间时，开关的文字被截断。主控据此修复：图表的取色改成亮色取 chart-2 到 chart-5、暗色取 chart-1 到 chart-4，灰阶主题里就不再有一段贴着底色消失；下排三列在 md 以下退成单列，开关文字不再被截。这两个问题都只在特定的主题或宽度下才出现，换一个状态就看不到了。

全站加载方案。 这一次 Pi 判了“不通过”，抓到三个阻塞问题，详见上一篇：骨架的 CSS 被构建配置当成全局样式，延迟没生效；图表占位把排名图撑高 433px；列表缩略图的骨架高度为 0。而此前自动化的 QA 脚本全是绿的。脚本检查的是我想到要检查的事，验收的人是在页面上实际看。这也是我后来给每类问题补一条断言的原因。

子任务的自述不一定属实。 数值滑块的一个子任务汇报说，缩放动画只加在 Control 内层。实际代码里，是 motion.div 把 Control 整个包住了，这会让 Base UI 换算数值用的矩形跟着缩放。这是一次 Codex 的独立审查发现的。从那之后，我形成了固定做法：涉及手感、坐标、可访问性的关键说法，主控抽查源码；Pi 产出之后固定再派 Codex 审查。审查时只给代码，不给实现者的结论，不然审查者容易被结论带着走。这样的审查通常要两轮。

每一轮的硬门槛是：

pnpm lint
pnpm registry:lint     # 构建前也会自动跑，不允许有警告
pnpm build

涉及视觉和交互的，再加两个脚本：pnpm qa:shots 按组件验收清单批量截图，并检查水合报错和横向溢出，最后生成一页对比报告；pnpm qa:loading 是上一篇里的加载检查。每次提交前还要用禁提词清单对整个仓库扫一遍，结果必须为空。

主控必须自己做的事

分工越细，越有几件事推不出去。

跨模块的判断。 子任务只看得见自己的目录。一个组件该放在 ui 还是 blocks，两个组件的接口怎么约定，哪个依赖该登记进 registry.json，这些要有全局视角。

视觉取舍。 区块改用自研组件的那一轮，AI 助手区块里的步骤流程被换成了 Timeline，结果整个流程变得很长。我否决了：它不如原来的 Trace 紧凑，太占地。于是定下一条规则：换成自研组件之后，尺寸不能比原来更大。后来这个区块的步骤流程换回了 Trace，同时加上了紧凑的图表。要不要换，换完好不好看，没有标准答案，只能由人来看、来判。

集成与提交。 并行的子任务各自在自己的范围里是对的，合在一起可能互相踩脚。主控把改动审查一遍，跑完门槛，再按路径暂存、一次提交。

这套办法的代价

• 写一份自包含的说明本身要花时间。小改动直接做比写说明更快，我不会为了“用上分工”去拆一个三行的改动。
• 独立验收不是免费的：每个重要任务要多一轮，有时两轮。但验收抓出的问题，到了线上就是别人的问题，我宁愿在这里多花一轮。
• 验收者也会漏。上面的例子里 Pi 抓到了自动化脚本漏的问题，但它能抓到什么，取决于它被要求看什么。所以验收说明里要写明“在哪些主题、哪些宽度、哪些状态下看”，不能只写“检查一下”。

开头说四天 197 个提交，写完这篇时已经过了 200。分工表以后多半还会改，模型会换，额度会变；但「验收要实测，不能只读汇报」这一条，我不打算再动。