mirror of
https://github.com/codestable/CodeStable.git
synced 2026-09-19 09:03:09 +08:00
docs: clarify task agent review rules
This commit is contained in:
dafang
@@ -43,7 +43,7 @@ description: 横切代码审查 gate——任何流程（feature / issue / refac
|
||||
- diff 涉及的人写代码文件和相邻关键调用点
|
||||
- spec 指向的 architecture / requirement / roadmap 相关文档（只读，判断改动是否会影响归并；feature 即 design 第 4 节）
|
||||
- goal / gate 模式下的 evidence pack、gate results、DoD results；缺失时回 implementation gate 补证据，不现场猜测
|
||||
- independent reviewer 输出（如果本轮启用了 Paseo 或其他外部 reviewer）
|
||||
- 独立 Task agent reviewer 输出（如果本轮启用了 Paseo 或其他 reviewer）
|
||||
|
||||
如果工作区有本轮范围外的既有 dirty 文件，先记录为 baseline/无关变更；审查结论只针对本轮可归因的改动。无法区分归因时写成 `residual-risk`，不要把不确定当通过。
|
||||
|
||||
@@ -63,7 +63,7 @@ description: 横切代码审查 gate——任何流程（feature / issue / refac
|
||||
|
||||
---
|
||||
|
||||
## 独立 reviewer（双环节）
|
||||
## 独立 Task agent reviewer（双环节）
|
||||
|
||||
本阶段是**双环节 review**，两个环节互补：
|
||||
|
||||
@@ -78,9 +78,9 @@ description: 横切代码审查 gate——任何流程（feature / issue / refac
|
||||
|
||||
### 环节 A：独立隔离上下文 agent review（gate 必需）
|
||||
|
||||
主 agent 按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动独立 reviewer：Paseo subagent 优先，否则用当前宿主的原生 Codex/Claude Task/Agent；都没有则记 `local-only`，不能伪装启动。gate 默认不放行，需用户明确降级（见 `reviewer` 字段）。
|
||||
主 agent 按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动独立 Task agent reviewer：Paseo subagent 优先，否则用当前宿主的原生 Codex/Claude Task/Agent；都没有则记 `local-only`，不能伪装启动。gate 默认不放行，需用户明确降级（见 `reviewer` 字段）。
|
||||
|
||||
独立 reviewer prompt（只给原始材料，不透露主 agent 的任何 review 结论）：
|
||||
独立 Task agent reviewer prompt（只给原始材料，不透露主 agent 的任何 review 结论）：
|
||||
|
||||
```text
|
||||
你是 CodeStable 本次改动的独立代码审查 agent。只读，不修改文件，不更新 checklist/design。
|
||||
@@ -208,9 +208,9 @@ gate 默认要求 `subagent` 或 `subagent+ocr`；`ocr` 和 `self` 需配 `CODES
|
||||
|
||||
- `passed`：没有 blocking；important 已修复、无重要项、或用户明确接受延后。
|
||||
- `changes-requested`：有 blocking，或 important 多到会影响验收可信度。
|
||||
- `blocked`：缺少关键输入、diff 归因无法判断、设计/实现状态不满足 review 前置条件，或本轮已启动 independent reviewer 但结果仍 pending / failed / blocked 且用户尚未确认降级。
|
||||
- `blocked`：缺少关键输入、diff 归因无法判断、设计/实现状态不满足 review 前置条件，或本轮已启动独立 Task agent reviewer 但结果仍 pending / failed / blocked 且用户尚未确认降级。
|
||||
|
||||
**`reviewer` 字段（gate 锚点）**：`{slug}-review.md` 的 frontmatter `reviewer` 决定下游 worktree / commit / finish gate 是否放行，按「独立 reviewer（双环节）」实际完成情况写 `subagent+ocr` / `subagent` / `ocr` / `self`（语义见上节表）。任一已启动环节仍 pending / failed / blocked 时不定稿 `passed`，也不写 `subagent`。
|
||||
**`reviewer` 字段（gate 锚点）**：`{slug}-review.md` 的 frontmatter `reviewer` 决定下游 worktree / commit / finish gate 是否放行，按「独立 Task agent reviewer（双环节）」实际完成情况写 `subagent+ocr` / `subagent` / `ocr` / `self`（语义见上节表）。任一已启动环节仍 pending / failed / blocked 时不定稿 `passed`，也不写 `subagent`。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -31,7 +31,7 @@ description: feature design 人工确认前的方案审查 gate。对照 {slug}-
|
||||
- design 第 4 节指向的 architecture 文档
|
||||
- 相关 compound 沉淀：用项目搜索工具按 feature 关键词检索 decision / learning / explore / trick
|
||||
- design 中引用到的关键代码位置、接口、类型、组件、命令、配置
|
||||
- independent reviewer 输出（如果本轮启用了 Paseo 或其他外部 reviewer）
|
||||
- 独立 Task agent reviewer 输出（如果本轮启用了 Paseo 或其他 reviewer）
|
||||
|
||||
没有代码引用时不强行扫全仓库；但 design 声称复用、修改、挂载或约束某个现有模块时，必须读对应代码或文档事实核验。
|
||||
|
||||
@@ -50,13 +50,13 @@ description: feature design 人工确认前的方案审查 gate。对照 {slug}-
|
||||
|
||||
---
|
||||
|
||||
## 独立 reviewer 增强项
|
||||
## 独立 Task agent reviewer 增强项
|
||||
|
||||
本阶段默认由当前 agent 做本地方案审查；独立 reviewer 是增强项，不是硬依赖。检测不到 Task agent、provider 未配置或用户明确要求快速完成时，可以继续本地 review，并在报告里记录 `Independent reviewer: local-only` / `skipped-by-user`。
|
||||
本阶段默认由当前 agent 做本地方案审查；独立 Task agent reviewer 是增强项，不是硬依赖。检测不到 Task agent、provider 未配置或用户明确要求快速完成时，可以继续本地 review，并在报告里记录 `Independent reviewer: local-only` / `skipped-by-user`。
|
||||
|
||||
但一旦本轮已经启动 independent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 independent reviewer 返回前定稿 `{slug}-design-review.md`、不能给出 `passed`、不能把 design 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。
|
||||
但一旦本轮已经启动独立 Task agent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 reviewer 返回前定稿 `{slug}-design-review.md`、不能给出 `passed`、不能把 design 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。
|
||||
|
||||
**检测由主 agent 在运行时自检自己的工具**，按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动独立 reviewer：Paseo subagent 优先，否则用当前宿主的原生 Codex/Claude Task/Agent。都没有则本地 review，记录 `local-only`，不要伪装启动。不要无限轮询运行中的 agent；若已启动但未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。
|
||||
**检测由主 agent 在运行时自检自己的工具**，按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动独立 Task agent reviewer：Paseo subagent 优先，否则用当前宿主的原生 Codex/Claude Task/Agent。都没有则本地 review，记录 `local-only`，并写入 `approval-report.md` 请 owner 授权降级；不要伪装启动。不要无限轮询运行中的 agent；若已启动但未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。
|
||||
|
||||
Task agent prompt 必须只给原始材料和边界，不透露本地 review 结论：
|
||||
|
||||
@@ -77,7 +77,7 @@ Task agent prompt 必须只给原始材料和边界，不透露本地 review 结
|
||||
不要写 {slug}-design-review.md；只把审查结果回传给主 agent。
|
||||
```
|
||||
|
||||
主 agent 仍是最终审查责任方：必须逐条核验 independent reviewer 的 finding，去重、定级、合并进 `{slug}-design-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。
|
||||
主 agent 仍是最终审查责任方：必须逐条核验 reviewer 的 finding，去重、定级、合并进 `{slug}-design-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。
|
||||
|
||||
---
|
||||
|
||||
@@ -96,7 +96,7 @@ Task agent prompt 必须只给原始材料和边界，不透露本地 review 结
|
||||
### 2. 独立审查合并
|
||||
|
||||
- 记录主 agent 自检结果：`paseo` / `native-agent` / `local-only`。
|
||||
- 没有启动 independent reviewer 时，记录原因，本地 review 可以定稿。
|
||||
- 没有启动独立 Task agent reviewer 时，记录原因，本地 review 可以定稿。
|
||||
- 启动 Task agent 后，最终 verdict 必须等 reviewer 返回。
|
||||
- reviewer 返回后逐条做本地事实核验；能用 design / checklist / 文档 / 代码证据支撑才合并。
|
||||
- reviewer 失败、权限阻塞、超时或仍在运行时，不要默默降级；报告 `status: blocked`。
|
||||
@@ -247,7 +247,7 @@ Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。
|
||||
## 7. Verdict
|
||||
|
||||
- Status: passed|changes-requested|blocked
|
||||
- Next: 交给用户整体 review | 回 `cs-feat-design` 修订后重跑 `cs-feat-design-review` | 等 independent reviewer 完成 / 用户确认降级后重跑
|
||||
- Next: 交给用户整体 review | 回 `cs-feat-design` 修订后重跑 `cs-feat-design-review` | 等独立 Task agent reviewer 完成 / 用户确认降级后重跑
|
||||
```
|
||||
|
||||
没有某类 finding 时写 `none`，不要删除章节；下一轮复审要能对比。
|
||||
@@ -259,8 +259,8 @@ Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。
|
||||
- [ ] 已读取 attention、design、checklist、相关 intent / brainstorm / roadmap / req / arch / compound。
|
||||
- [ ] 已按 design 声明核验必要代码、接口、类型、组件或命令事实。
|
||||
- [ ] 已确认 checklist 可解析，steps/checks 都可追溯。
|
||||
- [ ] 已运行 independent reviewer 检测，或记录为什么跳过。
|
||||
- [ ] 如果启动了 independent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。
|
||||
- [ ] 已运行独立 Task agent reviewer 检测，或记录为什么跳过。
|
||||
- [ ] 如果启动了独立 Task agent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。
|
||||
- [ ] 已审查需求边界、术语、名词层、编排层、挂载点、结构健康度、验收契约、steps/checks、基线、交付物、清洁度。
|
||||
- [ ] 已检查 Acceptance Coverage Matrix、Feature Design Review Invariants 和 Evidence Confidence Ledger。
|
||||
- [ ] 核心检查 H-only 时没有静默 passed。
|
||||
@@ -277,6 +277,6 @@ Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。
|
||||
- roadmap 起头时不检查接口契约，导致 feature 偷偷绕开 roadmap。
|
||||
- 现状段没读代码就放过，implement 阶段才发现设计站不住。
|
||||
- steps 出现"和 / 以及 / 同时"却不复查是否该拆。
|
||||
- 启动 independent reviewer 后结果还没回来，就把本地 review 定稿为 passed。
|
||||
- 启动独立 Task agent reviewer 后结果还没回来，就把本地 review 定稿为 passed。
|
||||
- 外部 reviewer 的结论没经本地事实核验就照抄。
|
||||
- review 报告没有落盘，导致用户 review 和后续实现没有可追溯输入。
|
||||
|
||||
+11
-11
@@ -30,7 +30,7 @@ description: roadmap 人工确认前的规划审查 gate。对照 roadmap 主文
|
||||
- 相关 compound 沉淀：用项目搜索工具按大需求关键词检索 decision / learning / explore / trick
|
||||
- items.yaml 中已存在 `feature` 字段的 feature design / acceptance（update 模式或复审时）
|
||||
- roadmap 中接口契约或模块拆分引用到的关键代码位置
|
||||
- independent reviewer 输出（如果本轮启用了 Paseo 或其他外部 reviewer）
|
||||
- 独立 Task agent reviewer 输出（如果本轮启用了 Paseo 或其他 reviewer）
|
||||
|
||||
没有代码引用时不强行扫全仓库；但 roadmap 声称复用现有模块、接口、命令、配置或数据结构时，必须读对应代码或文档事实核验。
|
||||
|
||||
@@ -49,13 +49,13 @@ description: roadmap 人工确认前的规划审查 gate。对照 roadmap 主文
|
||||
|
||||
---
|
||||
|
||||
## 独立 reviewer 增强项
|
||||
## 独立 Task agent reviewer 增强项
|
||||
|
||||
本阶段默认由当前 agent 做本地规划审查；独立 reviewer 是增强项，不是硬依赖。检测不到 Task agent、provider 未配置或用户明确要求快速完成时，可以继续本地 review，并在报告里记录 `Independent reviewer: local-only` / `skipped-by-user`。
|
||||
本阶段默认由当前 agent 做本地规划审查；独立 Task agent reviewer 是增强项，不是硬依赖。检测不到 Task agent、provider 未配置或用户明确要求快速完成时，可以继续本地 review，并在报告里记录 `Independent reviewer: local-only` / `skipped-by-user`。
|
||||
|
||||
但一旦本轮已经启动 independent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 independent reviewer 返回前定稿 `{slug}-roadmap-review.md`、不能给出 `passed`、不能把 roadmap 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。
|
||||
但一旦本轮已经启动独立 Task agent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 reviewer 返回前定稿 `{slug}-roadmap-review.md`、不能给出 `passed`、不能把 roadmap 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。
|
||||
|
||||
**检测由主 agent 在运行时自检自己的工具**，按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动独立 reviewer：Paseo subagent 优先，否则用当前宿主的原生 Codex/Claude Task/Agent。都没有则本地 review，记录 `local-only`，不要伪装启动。不要无限轮询运行中的 agent；若已启动但未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。
|
||||
**检测由主 agent 在运行时自检自己的工具**，按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动独立 Task agent reviewer：Paseo subagent 优先，否则用当前宿主的原生 Codex/Claude Task/Agent。都没有则本地 review，记录 `local-only`，并写入 `approval-report.md` 请 owner 授权降级；不要伪装启动。不要无限轮询运行中的 agent；若已启动但未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。
|
||||
|
||||
Task agent prompt 必须只给原始材料和边界，不透露本地 review 结论：
|
||||
|
||||
@@ -76,7 +76,7 @@ Task agent prompt 必须只给原始材料和边界，不透露本地 review 结
|
||||
不要写 {slug}-roadmap-review.md；只把审查结果回传给主 agent。
|
||||
```
|
||||
|
||||
主 agent 仍是最终审查责任方：必须逐条核验 independent reviewer 的 finding，去重、定级、合并进 `{slug}-roadmap-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。
|
||||
主 agent 仍是最终审查责任方：必须逐条核验 reviewer 的 finding，去重、定级、合并进 `{slug}-roadmap-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。
|
||||
|
||||
---
|
||||
|
||||
@@ -93,7 +93,7 @@ Task agent prompt 必须只给原始材料和边界，不透露本地 review 结
|
||||
### 2. 独立审查合并
|
||||
|
||||
- 记录主 agent 自检结果：`paseo` / `native-agent` / `local-only`。
|
||||
- 没有启动 independent reviewer 时，记录原因，本地 review 可以定稿。
|
||||
- 没有启动独立 Task agent reviewer 时，记录原因，本地 review 可以定稿。
|
||||
- 启动 Task agent 后，最终 verdict 必须等 reviewer 返回。
|
||||
- reviewer 返回后逐条做本地事实核验；能用文档 / 代码 / items 证据支撑才合并。
|
||||
- reviewer 失败、权限阻塞、超时或仍在运行时，不要默默降级；报告 `status: blocked`。
|
||||
@@ -239,7 +239,7 @@ Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。
|
||||
## 7. Verdict
|
||||
|
||||
- Status: passed|changes-requested|blocked
|
||||
- Next: 交给用户 review | 回 `cs-roadmap` 修订后重跑 `cs-roadmap-review` | 等 independent reviewer 完成 / 用户确认降级后重跑
|
||||
- Next: 交给用户 review | 回 `cs-roadmap` 修订后重跑 `cs-roadmap-review` | 等独立 Task agent reviewer 完成 / 用户确认降级后重跑
|
||||
```
|
||||
|
||||
没有某类 finding 时写 `none`，不要删除章节；下一轮复审要能对比。
|
||||
@@ -251,8 +251,8 @@ Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。
|
||||
- [ ] 已读取 attention、roadmap、items、相关 req / arch / compound / drafts。
|
||||
- [ ] 已按 roadmap 声明核验必要代码或命令事实。
|
||||
- [ ] 已确认 items.yaml 可解析，依赖图无未知节点；有问题已列 finding。
|
||||
- [ ] 已运行 independent reviewer 检测，或记录为什么跳过。
|
||||
- [ ] 如果启动了 independent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。
|
||||
- [ ] 已运行独立 Task agent reviewer 检测，或记录为什么跳过。
|
||||
- [ ] 如果启动了独立 Task agent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。
|
||||
- [ ] 已审查目标、范围、模块、接口、feature 原子性、依赖、最小闭环、验证、风险、知识回写。
|
||||
- [ ] 已检查 Granularity Gate、Goal Coverage Matrix 和 Roadmap Review Invariants。
|
||||
- [ ] 已写 Evidence Confidence Ledger；核心检查 H-only 时没有静默 passed。
|
||||
@@ -269,6 +269,6 @@ Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。
|
||||
- 不读 requirement / architecture，导致规划和现状冲突没发现。
|
||||
- 接口契约写着"待定"也放过，后续每条 feature 各自发明接口。
|
||||
- 子 feature 里塞多个可独立验收的交付，却只当一条。
|
||||
- 启动 independent reviewer 后结果还没回来，就把本地 review 定稿为 passed。
|
||||
- 启动独立 Task agent reviewer 后结果还没回来，就把本地 review 定稿为 passed。
|
||||
- 外部 reviewer 的结论没经本地事实核验就照抄。
|
||||
- review 报告没有落盘，导致用户 review 和后续 design 没有可追溯输入。
|
||||
|
||||
Reference in New Issue
Block a user