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. 验证是唯一的验收依据
|
|||
|
|
|
|||
|
|
- 说"通过了"必须附**实际命令输出**。
|
|||
|
|
- 说"实现了"必须有**能跑的测试**。
|
|||
|
|
- 说"验证过"必须**真的跑过**，不是读代码推断的。
|
|||
|
|
- 没跑到的部分**必须明说**，不允许留空。
|
|||
|
|
|
|||
|
|
本项目已经证明：单线程读代码看不出并发问题，测试跑一次就抓到了——
|
|||
|
|
而且抓到了两次，两次根因还不一样。
|