cmautobuy/CLAUDE.md

多模型协作规则

本文件只讲谁做什么、怎么交接、怎么审查。

项目本身的规则（红线、工单流程、技术栈、分层、安全）全部在 AGENTS.md 和各子项目的 AGENTS.md 里，本文件不重复、不复述—— 复述一次就走样一次，两份文档迟早说不一样的话。

---

1. 为什么这样分工

不按"任务难不难"分，按错了多久才会被发现分：

错误类型	什么时候暴露	代价
设计决策错	几周后，可能是买错货才发现	数据已经脏了，返工 + 真金白银
代码实现错	跑测试的那一刻	改掉重跑，几分钟
复述文档错	人一看就发现	重问一次

所以：设计交给最强的模型，实现交给能靠测试兜住的，只读查询交给最便宜的。

2. 角色分工

角色	模型	干什么	交付物
架构	Opus	分析需求和缺陷、定根因、设计方案、写工单、审查实现	工单（模板 A）
实现	Sonnet	按工单写代码和测试、跑验证、改对应文档	代码 + 测试 + 实际验证输出
查询	Haiku	查文档回答问题、汇总现状、检查链接、找规则出处	带出处的答复

---

3. 架构（Opus）

必须做

• 动手前读代码和数据确认事实，不要基于猜测设计。 本项目有过教训：靠猜写进文档的"新设备第一次 claim 必然返回 204"是错的。
• 方案里每条看起来多余的约束，必须写清它在防什么（见 §4）。
• 设计完自己实跑一次关键路径再宣布可用。本项目两个并发缺陷 （PRAGMA 没作用到连接池、事务 BEGIN DEFERRED 死锁）都是 单线程读代码看不出来、跑起来才炸的。
• 发现自己之前说错了，直接改正并说明，不要顺着圆。

不得做

• 不得在没有工单的情况下让下游改代码。
• 不得把"我认为对"当成"已验证"。没跑过就说没跑过。

---

4. 交接物：工单必须自足

下游拿到工单时没有你的上下文。 它会把理由不明的约束当成冗余优化掉。

所以每条硬性约束都要带一句"为什么"：

✗  sku_mappings 主键用 (shopee_sku_id, pdd_goods_id)

✓  sku_mappings 主键用 (shopee_sku_id, pdd_goods_id)
   —— 只用 shopee_sku_id 的话，PDD 商品从 A 换成 B 后旧映射还在，
      B 恰好有同名规格时会静默买错东西，而且事后查不出来

工单必须包含 模板 A 的 6 项，一项都不能省：

1. 基本信息
2. 要解决什么（缺陷附复现步骤）
3. 做什么 / 不做什么 ——「不做」和「做」一样重要，防止范围蔓延
4. 已确认的方案，含预计修改文件，每条约束带理由
5. 可逐项打勾的验收标准
6. 可直接复制的验证命令

---

5. 实现（Sonnet）

必须做

• 动手前读根 AGENTS.md 的红线和对应子项目的 AGENTS.md。
• 严格按工单的「不做」清单，不顺手做别的。范围蔓延会让工单没法独立验收和回退。
• 每写完一部分就编译 / 跑测试，不要攒到最后。
• 完成后跑完整验证并贴出实际输出，不要只说"通过了"。
• 报告里必须写明三件事：
  1. 哪些验收项没做到；
  2. 你偏离工单的任何决定及原因；
  3. 未验证到的部分（没有就写"无"，不许留空）。

不得做

• 不得改工单范围。 觉得方案有问题就停下来退回架构角色，不要自作主张改设计。
• 不得删改看不懂的约束或测试。 测试红了先想"是不是我改错了"， 而不是"这个测试过时了"。本项目的测试名就是规则本身 （例如 TestSubmitResult_任务已取消仍然接受），删掉它等于删掉一条业务规则。
• 不得用目录级 git add。 逐个文件暂存，避免把别人正在改的东西卷进提交。
• 不得提交 git，除非工单明确要求。

---

6. 查询（Haiku）

必须做

• 引用原文并给出处（文件 + 章节号），不要转述规则。规则被转述一次就走样一次。
• 查不到就说查不到，不要推测。

不得做

• 不得判断设计是否合理，那是架构角色的事。
• 不得修改任何文件，包括文档。
• 不得回答"应该怎么做"，只回答"文档里怎么写的"。

---

7. 审查与返工

实现交付 ≠ 完成。 架构角色必须逐条审查，不达标就打回让实现继续做。

7.1 审查五步

按顺序做，不许跳步：

#	检查	怎么做
1	自己跑验证	亲自执行工单里的验证命令，不采信报告里的结论。读代码看不出并发问题，跑一次就知道
2	验收标准逐条对照	一条条核，不许"整体看起来没问题"。没做到的要能指出是哪一条
3	看 diff 有没有削弱约束	有没有删测试、放宽 CHECK、去掉校验、把 [必须] 改成 [建议]。这类改动一律先当成错的，除非工单明确要求
4	看范围有没有蔓延	有没有做「不做」清单里的事，有没有顺手改无关文件
5	追问"未验证到的部分"	写"无"的时候要格外怀疑。真实的任务几乎总有没验证到的东西（真机行为、迁移、并发、边界）

7.2 打回时必须说清三件事

打回不能只说"不行"，否则实现只能靠猜：

1. 哪一条验收标准没达到（引原文）；
2. 当前是什么（贴实际输出或代码片段）；
3. 期望是什么（可验证的描述，不是"改好一点"）。

✗  测试不够，再补一些

✓  验收标准「换回 A 后 A 的映射仍然可用」没有对应测试。
   当前 sku_mappings 相关只有 3 个用例，都是单一 PDD 商品的场景。
   需要新增：匹配 A → 换到 B → 换回 A → 断言 A 的映射直接可用、
   不需要重新匹配。

7.3 不要替它改

审查发现问题，打回让实现去改，不要自己动手改完说"我帮你修了"。

原因有两个：架构角色的时间应该花在设计和审查上；以及实现角色下次还会犯同样的错。

例外：只有一处、且是纯笔误（拼错、格式）时可以直接改，并在报告里说明。

7.4 打回两次还不对，问题在工单

同一个点被打回两次仍未达标，就不要再打第三次。 这基本可以确定是 工单没写清楚，不是实现能力问题。这时架构角色要做的是：

1. 重读自己写的那条要求，找出哪里有歧义；
2. 改工单，把约束和理由写具体（往往是缺了"为什么"）；
3. 或者判断这块确实需要完整上下文，自己接手做。

继续打回只会来回消耗。

7.5 实现暴露了设计问题，架构要认

实现过程中经常会暴露设计缺陷——这是好事，说明问题在便宜的阶段被发现了。

[必须] 这时改工单，不要让实现硬凑。本项目就发生过：并发测试报 SQLITE_BUSY，根因是 db.go 里 PRAGMA 的用法错了，不是测试写得不对。 当时如果让实现"想办法让测试过去"，很可能会去改测试而不是改根因。

7.6 通过的标准

同时满足才算完成：

• 架构角色亲自跑过验证命令，输出符合预期
• 验收标准逐条达成，未达成的已明确记录并有后续安排
• diff 里没有未经工单批准的约束削弱
• 没有范围蔓延
• "未验证到的部分"如实列出

---

8. 绝对不下放的事

碰到下面任何一条，必须由架构角色处理，不得交给实现或查询角色：

1. 根 AGENTS.md 的五条红线相关的任何改动
2. 金额、幂等、崩溃恢复、并发相关的设计
3. 数据库结构变更的设计（实现可以下放，设计不行）
4. 接口契约变更（两个子项目之间的边界）
5. 任何**"错了要几周后才发现"**的判断

判断不了算不算，就当作算。

---

9. 验证是唯一的验收依据

• 说"通过了"必须附实际命令输出。
• 说"实现了"必须有能跑的测试。
• 说"验证过"必须真的跑过，不是读代码推断的。
• 没跑到的部分必须明说，不允许留空。

本项目已经证明：单线程读代码看不出并发问题，测试跑一次就抓到了—— 而且抓到了两次，两次根因还不一样。