opc/harness_coding_docs

Fork 0

Files

T

chengma e9e6dede7a

Harness governance / validate (push) Has been cancelled

Details

docs(review): add risk-based read-only agent gates

2026-07-16 19:04:02 +08:00

12 KiB

Raw Blame History

任务文件（一任务一文件 · 默认任务管理方式）

本目录是项目任务的默认存放位置：每个任务一个文件 docs/tasks/T-<编号>.md，单 agent 与多 agent 并发通用。阶段划分、里程碑和待办池见路线图 ../06-tasks.md；路线图只读，不跟踪单任务状态。

为什么默认一任务一文件

单 agent：领任务只读一个文件就拿到完整上下文（背景、方案、验收、执行记录），不用在看板、进度流水、快照三个共享文件之间跳转同步；执行记录和任务绑定，审查时 git log -p 一个文件即可回放全程。
多 agent 并发：单个大看板 + 多写者 = 编辑竞争（读到旧版本、反复重读）、ID 撞号（全局递增号是共享计数器）、合并冲突（相邻行改动）。一任务一文件后：改哪个任务只动哪个文件，agent 之间互不抢占；ID 撞号在新建文件时当场暴露（文件已存在就换号）。
零迁移：项目从单 agent 长到多 agent，无需切换任何约定。

文件命名与 ID

文件名：docs/tasks/T-<编号>.md（如 docs/tasks/T-101.md）；同族细分用后缀 T-101a.md。
落实路线图建议任务时，沿用路线图 ../06-tasks.md 里的建议编号（如 T-101）。
路线图之外的新任务：取「路线图建议编号 + docs/tasks/ 现有文件」里最大的 T-###，+1。
建文件即防撞：若目标编号文件已存在（别的 agent 先建了），改用下一个号，不要覆盖别人的文件。
模板 _template.md 以下划线开头，不是真实任务、不参与编号扫描。

每个任务文件的结构（frontmatter + 正文）

---
id: T-101
title: 一句话任务名
phase: 1               # 所属阶段，沿用路线图的 Phase 编号
deps: [T-100]          # 依赖的任务 ID
status: TODO           # TODO | DOING | DONE | BLOCKED
created: 【日期】
issue: null            # Gitea Issue 编号；未启用 Gitea 时保持 null
context_ref: null      # 领取时默认分支提交 SHA
claim_branch: null
work_branch: null
write_paths:           # 允许修改的仓库相对路径
  - docs/tasks/T-101.md
  - 【path/to/module】
---

## 问题 / 背景
## 方案
## 验收要点
## 边界（不改什么）
## 协作约束
## 执行记录

领取 / 完成流程

状态：TODO · DOING · DONE · BLOCKED。每个 agent 同时最多一个活跃任务；项目可以并行多个写路径互不重叠的任务。
每个 agent 一次只领一个 status: TODO 且依赖全 DONE 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。
write_paths 必须在动手前写清。两个活跃任务路径相同，或一条是另一条的目录前缀，均视为冲突，不能并行。
做完自测、按「passing 需证据」把验证命令与结果写清、改 status: DONE。
执行记录写进本任务文件的 ## 执行记录 一节（改了什么、跑了什么验证、结果、决策）——不逐任务追加共享的 progress.md（可选历史归档）、也不逐任务覆盖 current-state.md（项目级快照，只在启动/验证路径、目录结构或 blocker 变化时更新）。
只改自己那个任务文件；不要编辑别人正在做的任务文件。

未启用 Gitea 时，在独立分支 / worktree 中把任务文件从 TODO 改为 DOING 即可。启用 Gitea 时，必须先按 ../gitea-collaboration.md 由 dispatcher 串行分配并创建 claims/T-<编号> 防御性标记；assignee、标签、读回和普通 create-branch API 都不能单独提供并发互斥。

与 Gitea Issue / PR 的映射（可选）

一个任务文件对应一个主 Issue；Issue 负责实时领取、阻塞和评审状态，任务文件负责版本化规格和长期证据。
先把任务文件合入默认分支，再创建 Issue；随后把 Issue 编号回填任务文件并合入默认分支，最后才添加 status/todo。映射未完成的 Issue 不可领取。
Issue、claim 分支、工作分支和 PR 都携带同一个 T-<编号>；不得用一个 PR 顺带完成多个任务。
工作分支命名为 agent/<agent-id>/T-<编号>，每个 agent 使用独立 worktree。
MVP 由一个 dispatcher / 主 agent 串行分配任务，以此保证同一任务不被重复领取，并保证不同任务的 write_paths 不冲突。唯一 claim 分支只拦截顺序重试和常见旁路，不能替代 dispatcher 的互斥保证。
进入评审后 Issue 使用唯一 status/review；PR 合并且默认分支任务文件为 DONE 后，Issue 才能关闭并标记 status/done。
领取、结构化 claim 评论、过期锁回收和分支清理的完整规则见 ../gitea-collaboration.md。

单任务多角色评审（风险分级）

多角色评审仍然只处理一个任务，不增加第二个任务所有者。dispatcher / 主 Agent 负责选择评审级别和裁决结果；只有一个 writer 持有 claimed_by、工作分支和仓库写权限。

评审级别

`review_mode`	适用任务	必需角色
`none`	文案、链接、非敏感简单配置、无行为变化且自动校验充分	writer
`test`	普通功能、缺陷修复、行为或测试变化	writer + 只读测试评审
`dual`	登录、权限、Token、隐私、资金、删除 / 迁移、公共 API / Schema、核心架构、部署、外部平台集成	writer + 只读测试评审 + 只读安全/架构评审

项目可以提高某类任务的默认级别，但不得把高风险任务降为 none。评审安排写在任务文件 ## 协作约束；启用 Gitea 时同时写入 Issue。

角色权限

角色	可以做	不可以做
writer	修改允许路径、写测试、运行验证、提交和推送工作分支、回填执行记录	忽略必需评审、把自己的自测冒充独立评审
测试评审	读取任务、代码、候选 diff 和验证证据；提出测试矩阵、边界场景和缺失覆盖	修改文件、提交 Git、更新 Gitea、在共享工作区执行会产生文件或外部状态的命令
安全/架构评审	检查权限、秘密、数据风险、模块边界、公共接口、依赖和回滚	修改文件、提交 Git、更新 Gitea、替 writer 顺手修复
dispatcher / 主 Agent	分配角色、汇总结论、决定 `ACCEPT` / `REVISE` / `BLOCK`	在仍有未解决阻断或高风险发现时放行

评审角色不是任务领取者：不创建 claim、不创建工作分支、不成为 claimed_by。需要实际运行可能写缓存、数据库或外部系统的测试时，由 writer 执行，或使用一次性 worktree、容器 / 临时环境；“只读评审”不能只靠提示词约束。

执行顺序

dispatcher 根据任务风险确定 review_mode，并把角色写入 ## 协作约束。
test / dual 模式下，评审角色可在实现前只读任务规格，分别给出测试重点和风险清单；不得提前修改实现。
writer 完成实现和自测，先把验证证据写入任务文件，再产生候选提交；dispatcher / PR 记录该提交为 candidate_sha。不要把当前提交 SHA 写回同一个提交中的任务文件，避免自引用。
必需评审角色独立读取任务规格、context_ref、候选提交 SHA / diff 和验证证据；不能只读 writer 的总结。
每个评审输出结构化结论。dispatcher 汇总后决定：
- ACCEPT：该角色未发现阻断项；
- REVISE：存在必须由 writer 修复的问题；
- BLOCK：需求、架构、安全前提或验证环境存在根本阻塞。
writer 修复后产生新 SHA；此前针对旧 SHA 的结论不能直接复用，至少重新评审受影响内容。
启用 PR 时，最终必需评审的 reviewed_sha 必须等于待合并 PR head。未启用 PR 时，reviewed_sha 至少覆盖最后一个代码 / 配置变更提交；其后的提交只能更新当前任务文件中的评审证据，dispatcher 必须用 git diff <reviewed_sha>..HEAD 确认没有实现变化。
连续两轮仍为 BLOCK，或平台无法提供任务要求的独立评审角色时，把任务标为 BLOCKED 并请求维护者 / 用户裁决；不得由 writer 冒充评审或静默降低 review_mode。

评审结果使用稳定格式：

REVIEW
role: test | risk
reviewed_sha: 【40 位提交 SHA】
verdict: ACCEPT | REVISE | BLOCK
findings:
  - severity: critical | high | medium | low
    evidence: 【文件、测试或行为证据】
    required_action: 【必须修复或说明的动作】

评审 Agent 只返回报告；writer 在 ## 执行记录 写自测、修复动作和评审链接，dispatcher 在 PR / Issue 记录精确的 reviewed_sha 与 verdict。若要把评审摘要复制进任务文件，必须先提交该变更，再让必需评审检查新的 PR head；评审 Agent 本身不直接写远端状态。

用户指令暗语（可选约定）

用户的工作流通常固定为：提 bug/需求 → 讨论定案 → 落成任务文件 → 提交 → 实现 → 提交。为减少重复输入，可约定以下触发词；agent 读到即按约定执行。默认值：不注明视角就是全栈工程师视角；每步产物默认提交 git（只提交本次相关文件）。

用户输入	agent 执行
`bug: <现象>` / `需求: <描述>`	先查代码再给分析和方案，只讨论不改代码
`grill: <方案>`	反方评审，逐点挑战该方案
`落task`	把已讨论定案落成 `docs/tasks/T-<编号>.md`（按上述规则查号防撞），只写文档不写代码，写完自动提交 git
`审 T-<编号>`	以 git 历史为准（`git log -p` 该任务文件找出最近改动），先核代码事实，再审核该改动是否合理、给缺口
`补`	把讨论新增的结论补进当前任务文件并提交 git
`做 T-<编号>`	实现该任务 + 跑任务内验证命令；验证全绿才提交（执行记录、状态 DONE、提交）；验证失败 → 报告、不提交、状态留 DOING 或标 BLOCKED 记原因
`记backlog: <一行>`	追加进待办池（`docs/06-tasks.md` Backlog）并提交，只记一行、不建任务文件

补充规则：

落task/补 可带参数（落task <主题>、补 T-<编号>）；新会话或无对话上下文时 agent 必须先问清指代对象，不得猜。
采用时把这套暗语同时写进项目的 AGENTS.md 工作规则，并声明 AGENTS.md 为唯一权威源（agent 记忆、模板副本仅为指针/种子）——多副本不声明权威源，改触发词时必然漂移。
触发词可按团队习惯改名，关键是「一个词 = 一个流程阶段 + 默认动作」。

看板视图

现阶段：ls docs/tasks/ + 看各文件 frontmatter 的 status/deps 挑任务。
可选：加一个脚本把所有任务文件的 frontmatter 汇总成一张只读看板表，agent 不手改看板。

与路线图和共享文件的关系

../06-tasks.md：只读路线图（Phase 划分、里程碑、Backlog、建议拆分清单）；未启用 Gitea 时以任务文件 frontmatter 为准，启用后以 Issue 为实时状态、合并后的任务文件为长期事实。
../../progress.md：可选工件，用作历史归档或项目级大事记；执行记录写各任务文件，不逐任务追加。
../current-state.md：项目级快照（启动/验证路径、目录要点、blocker）；任务状态不在此维护，可由脚本汇总 frontmatter 生成。
../gitea-collaboration.md：启用 Gitea 时的任务映射、串行分配、防重复 claim、写路径防撞和 PR 状态协议。

12 KiB Raw Blame History Unescape Escape