From d3e7f713d8d41d89727055dfcc36b6449a03aa74 Mon Sep 17 00:00:00 2001 From: cat-shark Date: Sat, 10 Oct 2026 14:34:23 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BB=BA=E7=AB=8B=E9=80=9A=E7=94=A8?= =?UTF-8?q?=E8=A7=84=E5=88=99=E7=9B=AE=E5=BD=95=E5=B9=B6=E8=90=BD=20todo?= =?UTF-8?q?=20=E6=94=B6=E5=8F=A3=E7=BA=AA=E5=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/roles/README.md | 30 ++++++++++++++++++ .agents/roles/todo-discipline.md | 54 ++++++++++++++++++++++++++++++++ AGENTS.md | 24 ++++++++++---- 3 files changed, 102 insertions(+), 6 deletions(-) create mode 100644 .agents/roles/README.md create mode 100644 .agents/roles/todo-discipline.md diff --git a/.agents/roles/README.md b/.agents/roles/README.md new file mode 100644 index 0000000..f03f2e8 --- /dev/null +++ b/.agents/roles/README.md @@ -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` | 提交后 / 轮末 / 会话压缩后 | diff --git a/.agents/roles/todo-discipline.md b/.agents/roles/todo-discipline.md new file mode 100644 index 0000000..c000e2e --- /dev/null +++ b/.agents/roles/todo-discipline.md @@ -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` 次数是否匹配。 diff --git a/AGENTS.md b/AGENTS.md index fc88a34..713ed80 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,13 +33,13 @@ | 目录 | 用途 | |------|------| -| `lpt-docs` | 概念与设计文档项目,只维护系统概念和设计思路 | - -> 工作区级代理技能在 `.agents/skills/`,图表评审产物在 `docs/diagrams/`。 | `lpt-be` | Java Spring Boot 后端,提供 REST API、认证、数据库访问 | | `lpt-fe` | Vue 3 + TypeScript 前端 | | `lpt-ai` | TypeScript + Fastify 独立 AI 服务 | | `lpt-infra` | Kubernetes / Traefik 部署与基础设施清单 | +| `lpt-docs` | 概念与设计文档项目,只维护系统概念和设计思路 | + +> 工作区级代理技能在 `.agents/skills/`,跨仓库通用规则在 `.agents/roles/`,图表评审产物在 `docs/diagrams/`。 ## 子项目 Git 仓库 @@ -77,13 +77,25 @@ clone 完成后,进入或修改某个子项目前,先读取该子项目根 - 可并行的工作优先用 `subagent` 派到对应子项目执行;同一仓库/工作目录同时只允许一个写入者(第二个写入者要么等,要么用 worktree 隔离)。 - 只有存在真实依赖(后一步要用前一步的产出)时才串行,并在派发说明里写明依赖点;不要凭「感觉」串行。 - 派发子任务时把已确认口径、涉及文件、验收命令、提交信息写清楚;`OPTIMIZATION_BACKLOG.md` 只由主代理更新,子代理不要改(避免 meta 仓库并发写)。 -- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。 +- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能与通用规则)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。 - `.gitignore` 忽略所有子项目目录,只放行上述根级条目,避免把独立 Git 仓库提交进本 meta 仓库。 - 不要删除子项目内的 `.git`,也不要对子项目执行跨仓库的 `git add .`。 - 对子项目执行 Git 操作时使用 `git -C lpt-be ` 这类形式。 - 如果某个子项目目录已存在但不是 Git 仓库,或 clone 因 SSH 权限/网络失败,应停止并说明原因,不要用空目录或本地副本替代。 -## 代理技能与图表 +## 代理技能、规则与图表 + +### 规则放在哪 + +判断标准只有一句:**这条规则换到另一个仓库还成立吗?** + +- **通用规则(不限仓库)** 放在 `.agents/roles/`,由本仓库统一管理;例如 todo 收口纪律。 +- **项目专属规则** 留在各仓库自己的 `AGENTS.md`(后端迁移写法、前端测试隔离之类)。 +- 新增通用规则时,记得在 `AGENTS.md` 里挂上入口:`.agents/roles/` **不是自动加载目录**, + 只有 `AGENTS.md`(与按描述触发的 skills)会被读到,不引用等于不生效。 +- 现行通用规则:`todo-discipline.md`(提交后收口 / 轮末对账 / 压缩后对账)。 + +### 技能 - 工作区级技能放在 `.agents/skills/<技能名>/`,不放进子项目;子项目专用技能才留在各仓库 `skills/`。 - `mermaid-diagram`:按业务主题在 `docs/diagrams/<主题>/` 生成 `.mmd` 图源与渲染页,起本地服务在线评审。 @@ -94,7 +106,7 @@ clone 完成后,进入或修改某个子项目前,先读取该子项目根 ## 文档维护 - 所有系统文档统一在 `lpt-docs` 仓库维护,代码仓库不保留 README、`docs/` 等文档文件。 -- 代理协作规范保留在各仓库 `AGENTS.md`。 +- 代理协作规范:通用规则在 `.agents/roles/`,各仓库专属规则保留在该仓库 `AGENTS.md`。 - `lpt-docs` 只维护系统概念描述和设计思路,不保存开发记录、系统中间态和开发过程产物。 - 跨仓库的实现优化清单记录在本仓库 `OPTIMIZATION_BACKLOG.md`(只放待办、依据与验收标准);概念与设计仍归 `lpt-docs`。 - 修改 `lpt-docs` 后,如需在 meta 仓库补充说明,保持 meta 仓库不复制文档正文。