chengmaandClaude Opus 5
ab988b39de
CLAUDE.md（新增） 按"错了多久才会被发现"划分角色，而不是按任务难度： 设计错要几周后买错货才发现，实现错跑测试就红，复述错人一看就知道。 所以 Opus 设计和审查、Sonnet 实现、Haiku 只读查询。 关键几条： - 工单里每条约束必须写清"在防什么"。下游没有上游的上下文， 理由不明的约束会被当成冗余优化掉 - 实现角色不得改工单范围、不得删改看不懂的约束或测试 （本项目测试名就是规则本身，删掉等于删掉一条业务规则） - 审查五步，第一步是架构角色亲自跑验证，不采信报告结论 - 打回必须说清：哪条没达到、当前是什么、期望是什么 - 同一个点打回两次仍不达标，问题在工单不在实现， 这时该改工单或自己接手，继续打回只是消耗 AGENTS.md §0 重写 Gitea 一直可用（#1~#13 在正常使用），但 §0 还留着 <待填写>， 于是"未配置"成了跳过建单的长期借口。这次 PDD 那批就是靠聊天里的 草稿直接开工的，没有工单号。 - §0.1 填上真实地址和仓库；写明工单层级靠标题前缀区分， 不使用标签和里程碑（13 条工单实测两者均为空，也不要去建） - §0.2 聊天里的草稿不算工单；不得默认直通， 不得因为上次直通过就默认这次也行 - §0.3 防呆：任何地方看到本仓库的工单链接就说明 Gitea 可用， 必须立刻回填 §0.1 并停止直通。提交信息里不得再出现 "Gitea 未配置 / 无工单号"这类说法 两份文档边界划清：CLAUDE.md 只讲协作方式，项目规则一律指向 AGENTS.md 不复述——复述一次就走样一次。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
211 lines
8.5 KiB
Markdown
211 lines
8.5 KiB
Markdown
# 多模型协作规则
|
||
|
||
本文件只讲**谁做什么、怎么交接、怎么审查**。
|
||
|
||
项目本身的规则（红线、工单流程、技术栈、分层、安全）全部在
|
||
[AGENTS.md](AGENTS.md) 和各子项目的 `AGENTS.md` 里，**本文件不重复、不复述**——
|
||
复述一次就走样一次，两份文档迟早说不一样的话。
|
||
|
||
---
|
||
|
||
## 1. 为什么这样分工
|
||
|
||
不按"任务难不难"分，按**错了多久才会被发现**分：
|
||
|
||
| 错误类型 | 什么时候暴露 | 代价 |
|
||
|---|---|---|
|
||
| 设计决策错 | 几周后，可能是买错货才发现 | 数据已经脏了，返工 + 真金白银 |
|
||
| 代码实现错 | 跑测试的那一刻 | 改掉重跑，几分钟 |
|
||
| 复述文档错 | 人一看就发现 | 重问一次 |
|
||
|
||
所以：**设计交给最强的模型，实现交给能靠测试兜住的，只读查询交给最便宜的。**
|
||
|
||
## 2. 角色分工
|
||
|
||
| 角色 | 模型 | 干什么 | 交付物 |
|
||
|---|---|---|---|
|
||
| **架构** | Opus | 分析需求和缺陷、定根因、设计方案、写工单、**审查实现** | 工单（模板 A） |
|
||
| **实现** | Sonnet | 按工单写代码和测试、跑验证、改对应文档 | 代码 + 测试 + 实际验证输出 |
|
||
| **查询** | Haiku | 查文档回答问题、汇总现状、检查链接、找规则出处 | 带出处的答复 |
|
||
|
||
---
|
||
|
||
## 3. 架构（Opus）
|
||
|
||
### 必须做
|
||
|
||
- 动手前**读代码和数据**确认事实，不要基于猜测设计。
|
||
本项目有过教训：靠猜写进文档的"新设备第一次 claim 必然返回 204"是错的。
|
||
- 方案里每条**看起来多余的约束，必须写清它在防什么**（见 §4）。
|
||
- 设计完**自己实跑一次关键路径**再宣布可用。本项目两个并发缺陷
|
||
（PRAGMA 没作用到连接池、事务 `BEGIN DEFERRED` 死锁）都是
|
||
单线程读代码看不出来、跑起来才炸的。
|
||
- 发现自己之前说错了，直接改正并说明，不要顺着圆。
|
||
|
||
### 不得做
|
||
|
||
- 不得在没有工单的情况下让下游改代码。
|
||
- 不得把"我认为对"当成"已验证"。没跑过就说没跑过。
|
||
|
||
---
|
||
|
||
## 4. 交接物：工单必须自足
|
||
|
||
**下游拿到工单时没有你的上下文。** 它会把理由不明的约束当成冗余优化掉。
|
||
|
||
所以每条硬性约束都要带一句"为什么"：
|
||
|
||
```text
|
||
✗ sku_mappings 主键用 (shopee_sku_id, pdd_goods_id)
|
||
|
||
✓ sku_mappings 主键用 (shopee_sku_id, pdd_goods_id)
|
||
—— 只用 shopee_sku_id 的话，PDD 商品从 A 换成 B 后旧映射还在，
|
||
B 恰好有同名规格时会静默买错东西，而且事后查不出来
|
||
```
|
||
|
||
工单必须包含 [模板 A](docs/templates/task.md) 的 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. **期望是什么**（可验证的描述，不是"改好一点"）。
|
||
|
||
```text
|
||
✗ 测试不够，再补一些
|
||
|
||
✓ 验收标准「换回 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. 验证是唯一的验收依据
|
||
|
||
- 说"通过了"必须附**实际命令输出**。
|
||
- 说"实现了"必须有**能跑的测试**。
|
||
- 说"验证过"必须**真的跑过**，不是读代码推断的。
|
||
- 没跑到的部分**必须明说**，不允许留空。
|
||
|
||
本项目已经证明：单线程读代码看不出并发问题，测试跑一次就抓到了——
|
||
而且抓到了两次，两次根因还不一样。
|