docs: 建立通用规则目录并落 todo 收口纪律

This commit is contained in:
cat-shark
2026-10-10 14:34:23 +08:00
parent d5896498c1
commit d3e7f713d8
3 changed files with 102 additions and 6 deletions
+30
View File
@@ -0,0 +1,30 @@
# 通用规则(`.agents/roles/`)
存放**跨仓库通用的代理行为规则**。
目录名叫 `roles`,但里面不放「角色扮演」式定义(没有「你是某某角色、你的职责是……」),
**只记录规则本身**:什么情况下必须做什么、怎么核对。
## 放什么,不放什么
判断标准只有一句:**这条规则换到另一个仓库还成立吗?**
| 内容 | 位置 | 例子 |
|------|------|------|
| 通用规则(不限仓库) | 本目录,meta 统一管理 | 提交后收口 todo、轮末对账 |
| 项目专属规则 | 各仓库自己的 `AGENTS.md` | 后端的迁移写法、前端的测试隔离 |
| 项目知识与架构约定 | 各仓库 `AGENTS.md` | 端口、调用关系、命名约定 |
| 跨仓库待办与验收标准 | `OPTIMIZATION_BACKLOG.md` | 优化条目 |
| 按任务触发的专业指令 | `.agents/skills/` | 绘图评审流程 |
## 生效方式(重要)
**`.agents/roles/` 不是自动加载入口。** 规则要真正约束行为,必须在 `AGENTS.md` 里被引用——
`AGENTS.md` 是每次会话自动加载的项目指令入口,只有它(和按描述触发的 skills)会被读到。
所以:新增规则时,务必同时在 `AGENTS.md` 对应章节挂上入口。
## 规则清单
| 规则 | 文件 | 触发点 |
|------|------|--------|
| todo 收口纪律 | `todo-discipline.md` | 提交后 / 轮末 / 会话压缩后 |
+54
View File
@@ -0,0 +1,54 @@
# todo 收口纪律
## 为什么有这条规则
2026-10-09 的一次会话里:`todo` 工具 `create` 23 次,`update` 只有 14 次——
**13 条(57%)从未被标记完成**,而它们对应的活儿全都做完并提交了。
表现是待办面板长期显示一堆「未完成」,看起来像插件不显示完成态,实际是**没人去收口**。
放大因素(都真实发生过):
- 批量创建后跨多轮续跑,缺少「收口上一条」这个动作的触发点;
- 多项经 subagent 执行,子代理返回、验证后直接进入下一步;
- **会话被压缩后,压缩摘要与 todo 列表漂移**,没人对账;
- 插件会把已完成项在下一轮隐藏(其既定设计),使遗漏反而更不容易被看见。
## 规则
三条都有明确触发点——不需要「记得」,只需要在触发点做一次。
### R1 提交后立即收口
**触发点**:`git commit` 成功。
每次提交成功后,**立刻**把这次提交覆盖的 todo 标为 `completed`。
提交是本项目工作的收尾动作,触发点天然存在,不依赖记性。
### R2 轮末对账
**触发点**:准备发出最终回复前。
发最终回复前跑一次 `todo list`,凡是「实际已完成、但状态仍是 `pending` / `in_progress`」的,
一律收口。对账是幂等的:没有遗漏时它就是一次空转。
### R3 压缩后对账
**触发点**:会话被压缩、出现压缩摘要之后。
压缩摘要与 todo 列表是两套状态,压缩后先对账一次再继续干活。
本规则正是从压缩后漂移的场景里总结出来的。
## 边界
- **不得为收口而收口**:测试失败、实现不完整、仍有未解决报错时保持 `in_progress`,
并为阻塞另建条目(既有约定不变)。
- 建议单批条目不超过 5 条。本规则的诞生场景里 23 条远超面板默认 12 行预算,
本来看不全,也更难发现自己漏维护。这是建议,不是硬规则。
- 这些 todo 只是会话内草稿(插件不写盘,状态由会话分支重放),
收口不涉及代码、数据库或任何仓库内容。
## 怎么核对
- `todo list` 看最终状态分布;
- 需要复盘时,重放会话文件里的 `todo` 调用,统计 `create` 与 `update` 次数是否匹配。