jsonlee12138 Agent SOP
契约
主 Agent 持有 Goal Contract，负责范围与风险判断、能力路由、真实验证、证据综合、返工和 Completion Oracle。Subagent 只完成有边界的阶段并返回证据，不更新 Linear/VibeRig 状态、不操作 PR、不作最终验收决定。
不要把整个任务外包后等待。只有 recommended / optional 能力缺失时主 Agent 才可直接完成并记录原因；required 独立 Gate 缺少可用 Subagent 或 dispatch 失败时必须 BLOCKED。保护无关用户改动，只修改任务范围。
输入与输出
输入：具体开发目标、仓库、AC/TC 或其他可判定结果；可选 Issue、架构契约、风险、日志、PR 和项目 Gate。
输出：范围与风险等级、测试策略、使用的阶段/能力、改动、验证与审核结果、跳过项、残余风险，以及 PASS、REWORK 或 BLOCKED 综合结论。
基本规则
- 显式记录会影响实现方向的假设；只有缺失信息会改变方案或扩大风险时才询问用户。
- 发现需求、架构或代码冲突时停止猜测，指出冲突与取舍。
- 优先简单、局部、可回滚的实现，不做顺手重构。
- Subagent 自述不是证据；主 Agent 必须读取 diff 和真实命令输出。
- 不为所有任务强制新增测试，但必须有明确验证决策和 Evidence。
- Skill 切换、一次验证失败和可模拟配置缺失不是人工 Gate；返回
execute继续循环。 - Subagent 先按 capability 匹配，再由
subagent-routing选择 model/reasoning；便宜模型只能在质量与安全约束之后优化。 - 每次委派保留 route observation；没有真实 token、耗时或 provider 价格时写
null/unknown，不得回忆性补数。 - 每次真实委派另存 dispatch receipt；route observation 记录“为什么这样路由”，receipt 证明“调用确实发生”。
测试范围
VibeRig Issue 优先从 test-cases.json 与 traceability.json 读取相关 TC：
automation: required的新行为先取得 RED 证据，再 GREEN、REFACTOR；Bug 修复先复现失败。issue_local执行受影响用例；pr_ci由当前 commit 的 CI 产生权威证据。milestone、owner_uat、post_release或manual只交接，不伪造 PASS。- 旧需求没有 TC 时进入
legacy mode，根据 AC、风险和现有测试模式作窄范围决策。
纯文档、静态内容、无行为配置可不新增测试，但仍执行适当静态检查并记录理由。
测试配置或外部依赖缺失时读取 execute/references/test-environment-broker.md，自动建立充分保真的 fake、stub、ephemeral dependency 或 sandbox。不得把“没有 .env.test”直接变成人工阻塞。
风险与审核路由
| 风险 | 默认审核 |
|---|---|
| 低 | 主 Agent 检查；纯文档/静态改动可跳过独立 Code Review |
| 标准 | 非简单代码改动必须 Code Review；覆盖复杂时增加 Test Review |
| 高 | Code、Security、Test 独立审核；性能敏感时增加 Performance Review |
权限、鉴权、外部输入、敏感数据、不可逆迁移、支付、核心链路和外部契约不得判为低风险。通过 subagent-routing 按能力选择 Reviewer，不硬编码名称；需要多个审核时并行发出 Brief。
“必须”表示 required Gate：Reviewer invocation 必须不同于实现 invocation，receipt 必须绑定当前 artifact fingerprint。审核后代码变化使对应 receipt 失效并要求重审。
执行流程
- 分析：确定目标、范围、相关 AC/TC、架构约束、风险、未知项和 Gate。
- 测试准备：由当前实现者按相关 TC 做 TDD；仅在复杂/高风险自动化、Bug 复现需要独立所有权时，单独委派
test_engineer编写批准的 TC。测试范围不清时使用qa / test_review审核，不让test_engineer从零设计产品测试策略。 - 实现：L0 默认主 Agent 直接完成；L1 根据隔离价值选择主 Agent 或一个
implementation；L2/L3 优先让实现与审核分离。Brief 只含相关范围、TC、契约和风险；禁止无关修改。 - 主 Agent 定向验证：读取 diff，执行受影响 TC、项目快速 Gate 和必要 Smoke；记录命令、结果、commit/工作区与跳过原因。
- 风险审核：按风险表执行
code_review、qa / test_review、security_auditor / code_security_review、reliability_engineer / operational_review，要求结构化 Findings 与 Verdict，不让 Reviewer 修改代码。 - CI 门禁：Linear/PR 任务读取当前 commit 的 Required Checks；相同 commit、环境和测试定义的成功证据直接复用。
- 证据综合：主 Agent综合 TC、Gate、Review 和 CI，给出
PASS、REWORK或BLOCKED。REWORK返回execute下一轮；只有真实 Gate 或连续三次无进展才BLOCKED。不再额外委派一个重复的 Final QA。
每个发生 Subagent 路由的步骤都将 pending observation 更新为实际 outcome。模型导致的返工、Agent prompt 不匹配、上下文缺失、环境故障和 oracle 缺陷分开分类；不要把所有失败都归因于模型。
Reviewer 输出
| Reviewer | 输出 |
|---|---|
| Code | APPROVE / REQUEST CHANGES；Correctness、Maintainability、Architecture、Evidence Findings 与专业审核触发信号 |
| Test | PASS / REWORK；AC/TC 覆盖、断言质量、边界、回归价值和缺口 |
| Security | Critical/High/Medium/Low/Info Findings；Critical 附可复现说明 |
| Performance | 预算、测量证据、退化风险与结论 |
任一 Critical 阻塞交付；Important/High 必须修复或作为显式残余风险报告。
证据有效性
证据仅在 commit、要求环境和测试定义未变化时复用。以下变化使相关证据失效：
- 新 commit 或合入最新 main 影响相关代码；
- 测试、Fixture、配置或外部依赖变化；
- local 证据被用于要求 CI/staging/production-like 的 TC；
- CI Job 与当前 commit 不一致。
无法判断影响时采用保守范围，不用重复运行掩盖 flaky test。
返工
把失败返回给产生该问题的阶段。返工 Brief 只包含失败证据、期望修正、相关文件/命令、保护范围和返回证据。
同族问题默认最多三轮；同一偏差第二次出现时必须改变假设、工具、测试层级或实现策略。连续三次没有新增证据或状态进展，或需要业务决策/权限/不可模拟外部状态时停止并升级。每轮修复后只重跑失败 TC、直接依赖 TC 和失效 Gate。
红线
- 固定为每个任务启动测试编写、Test QA、Final QA、Code/Security/Test Review 全套角色。
- 没读取 VibeRig 已批准 TC 就从零发明另一套测试范围。
- Reviewer 或实现 Subagent 更新 Linear、Proof Packet、PR 或终态。
- required Gate 缺失时由主 Agent 自审替代，或伪造 dispatch receipt。
- 主 Agent未读取真实输出就接受 Subagent 的 PASS。
- 人工/里程碑/发布 TC 在 Issue 阶段被标为 PASS。
- Critical Finding 未解决仍交付。
- 失败后无代码变化却反复执行同一命令碰运气。
验证与报告
- 范围、风险和测试决策有明确结论。
- Required TC 已通过，或在正确的后续阶段待办；没有静默跳过。
- 主 Agent检查 diff 并执行了真实验证。
- Reviewer 与 CI 按风险和项目策略执行，证据对应当前 commit。
- required 独立 Gate 的 receipt 有效且与实现 invocation 不同。
- 综合结论、跳过项和残余风险完整。
最终报告只保留改动、TC/Gate/Review 结果、失败摘要、跳过原因和残余风险，不输出冗长内部讨论。