cr-logaf-review

Code Review 流水线的第三道门控：LOGAF Checklist 全面评审子 Agent。 由 spec-driven-dev 的 code_review 阶段在 cr-code-gate 通过或 WARN 后调用。 执行 8 个维度的综合性代码评审，输出可操作的分级反馈，并给出最终合并裁决。

---

调用契约

输入（由 Orchestrator 注入上下文）

字段	类型	说明
us_id	string	用户故事 ID
iter_id	string	当前迭代 ID
git_diff	string	git diff main...HEAD 的完整输出
us_file_path	string	requirements/US/{us_id}.md，用于核对验收标准（CR-03）
architecture_path	string	requirements/{us_id}/docs/architecture.md，用于设计评审（CR-01、CR-04）
test_report_path	string	requirements/{us_id}/docs/reports/test-{us_id}-report.md，用于测试质量评审（CR-02）
code_gate_findings	object[]	门控二 cr-code-gate 传入的 m/l 级发现列表（避免重复报告）

Orchestrator 调用示例（OpenCode Sub-Agent 格式）：

invoke_skill: cr-logaf-review
with:
  us_id: "US042"
  iter_id: "iter_003"
  git_diff: "<diff output>"
  us_file_path: "requirements/US042/docs/US042.md"
  architecture_path: "requirements/US042/docs/architecture.md"
  test_report_path: "requirements/US042/docs/reports/test-US042-report.md"
  code_gate_findings: [{ "id": "GK-07", "logaf": "m", … }]

输出（写回 Orchestrator）

{
  "agent": "cr-logaf-review",
  "verdict": "APPROVED | APPROVED_WITH_NOTES | REQUEST_CHANGES",
  "h_count": 0,
  "m_count": 0,
  "l_count": 0,
  "findings": [
    {
      "id": "CR-01",
      "logaf": "m",
      "verdict": "PASS | WARN | FAIL",
      "file": "src/foo.py:12",
      "description": "…",
      "suggestion": "…"
    }
  ],
  "summary": "…"
}

---

执行协议

Step 0 — 发出启动检查点

[AGENT:cr-logaf-review] START  us_id={us_id}  iter_id={iter_id}

Step 1 — 读取上下文

1. 解析 git_diff 获取所有变更文件和代码块。
2. 读取 US042.md 提取验收标准清单（用于 CR-03）。
3. 读取 architecture.md 获取组件职责和接口约定（用于 CR-01、CR-04）。
4. 读取 test-{us_id}-report.md 获取覆盖率和测试失败摘要（用于 CR-02）。
5. 接收 code_gate_findings 避免在 CR-05/CR-06 中重复 m/l 发现。

Step 2 — 执行 8 维度 Checklist

---

LOGAF Checklist

LOGAF 三级标注：

• h（high）— 必须在合并前解决，否则裁决 REQUEST_CHANGES
• m（medium）— 应当修复，但不强制阻塞，裁决 APPROVED_WITH_NOTES
• l（low）— 可选改进，不影响合并裁决

---

CR-01 · 设计合理性

评审问题：

• 各模块的交互是否符合 architecture.md 中定义的组件职责和接口约定？
• 新增方法是否具备足够的通用性，可以提升为模块级工具函数？
• 是否存在"只需传入对象属性，却传入了整个对象"的过度耦合？
• 新增的抽象层是否必要，还是增加了不必要的间接性？

LOGAF 定级参考：

• h：新代码违反了 architecture.md 中明确定义的模块边界
• m：可提升为模块级方法，但当前实现仍可工作
• l：轻微耦合，可在后续迭代重构

---

CR-02 · 测试质量

评审问题：

• 测试是否覆盖了 US 验收标准中的每一条可验证条件？
• 测试是否覆盖了缺陷修复路径（如有 bugfix 阶段）？
• 测试是否避免了不必要的 if/for 分支（防止测试代码自身引入 bug）？
• 是否存在模拟真实用户调用 API 的功能性端到端测试？
• 权限和访问控制逻辑是否有专门的测试用例（正向 + 越权拒绝）？

LOGAF 定级参考：

• h：验收标准中有条件完全未被任何测试覆盖
• m：测试覆盖存在盲区但核心路径已覆盖；或测试中存在可能掩盖 bug 的分支
• l：可补充边界情况测试，但不影响主要验证

---

CR-03 · 预期行为验证

评审问题：

• 代码变更是否真实满足了 US{us_id}.md 中定义的全部验收标准？
• PR/迭代描述是否充分解释了"做了什么"以及"为什么这样做"？
• 是否解释了探索过但未采用的替代方案（防止 reviewer 重走同样的弯路）？

LOGAF 定级参考：

• h：有验收标准明确未被代码实现满足
• m：验收标准语义模糊，需要澄清才能确认是否满足
• l：迭代摘要描述不够清晰，但实现正确

---

CR-04 · 长期影响评估

评审问题：

• 是否引入了大型重构、DB Schema 变更、新框架依赖，或可能永久影响性能特性的行为？
• 以上情形是否已在 current_iter.md 中记录了 senior 确认？
• 新增的行为是否可能在未来成为技术债（例如过度定制的解决方案）？

LOGAF 定级参考：

• h：重大架构变更无任何审批记录
• m：有潜在的技术债，但当前迭代范围内合理
• l：微小的长期影响，已在注释中说明

---

CR-05 · 代码复杂度

评审问题：

• 是否存在可显著减少 LOC 的等价简化方案？（参考 Sentry 原则：LOC 与 bug 数正相关）
• for 循环是否可替换为标准库方法（find、filter、map、reduce）？
• 条件嵌套层数是否超过 3 层，可否提前 return 展平？
• 是否存在重复代码块可抽取为函数？

LOGAF 定级参考：

• h：代码逻辑极度复杂，严重影响可维护性
• m：存在明显的简化机会，改动后可读性显著提升
• l：轻微的风格偏好差异，可选改进

---

CR-06 · 编码规范执行

评审问题：

• 变量、函数、文件、指标、logger 命名是否语义化、可读，并与现有代码库风格一致？
• 是否存在不应提交的冗余代码、调试语句、或过期注释？
• 数据库迁移文件是否附有部署计划（up/down 脚本、回滚策略）？
• 是否遵循了 coding_standards.md 中项目特定的规范约定？

注意：若 cr-code-gate 的 code_gate_findings 中已包含 GK-09/GK-10 的同类发现，此处不再重复报告，只做引用。

LOGAF 定级参考：

• h：命名导致语义歧义，影响团队理解和维护
• m：命名不一致，但语义清晰
• l：纯风格偏好，不影响功能

---

CR-07 · 变更范围聚焦

评审问题：

• 本次迭代是否只包含一个功能或行为变更？
• 是否有无关的代码重构、格式调整或其他改动混入本次变更？
• 若涉及多个团队/模块，是否考虑拆分为独立的迭代？

LOGAF 定级参考：

• h：无关变更掩盖了核心变更，导致评审困难
• m：包含少量无关改动，但可识别
• l：微小的顺手修复，不影响理解

---

CR-08 · 知识共享价值

评审问题：

• 关键业务逻辑是否有充分的注释，使其他人能够在无上下文的情况下理解意图？
• 复杂算法或非直觉性实现是否有说明"为什么这样做"而不只是"做了什么"？
• 新增的公开接口是否有完整的 docstring / JSDoc / godoc 等文档？

LOGAF 定级参考：

• h：核心业务逻辑完全无注释，严重影响知识传承
• m：注释不足，但可以通过阅读代码理解
• l：可补充的说明性注释，非必须

---

Step 3 — 输出逐条发现

每条发现使用统一格式：

[{logaf}] {CR-ID} | 文件: {path}:{line_or_N/A} | 问题: {描述} | 建议: {可操作方案}

示例：

[h] CR-03 | 文件: N/A                          | 问题: 验收标准"Session 24h 过期"无任何代码实现 | 建议: 在 JWT 签发时设置 exp = now + 86400s
[m] CR-01 | 文件: src/auth/service.py:34       | 问题: validate_token() 逻辑可提升为模块级工具函数 | 建议: 移至 src/utils/jwt.py 并复用
[m] CR-02 | 文件: tests/test_auth.py            | 问题: 缺少 token 过期场景的测试用例 | 建议: 新增 test_expired_token_returns_401
[l] CR-08 | 文件: src/auth/handler.py:78        | 问题: callback 处理逻辑无注释说明状态机转换意图 | 建议: 添加注释解释 state 参数的 CSRF 防护作用

Step 4 — 返回结构化结果并生成摘要

{
  "agent": "cr-logaf-review",
  "verdict": "REQUEST_CHANGES",
  "h_count": 1,
  "m_count": 2,
  "l_count": 1,
  "findings": [
    {
      "id": "CR-03", "logaf": "h", "verdict": "FAIL",
      "file": "N/A",
      "description": "验收标准 'Session 24h 过期' 无实现",
      "suggestion": "在 JWT 签发时设置 exp = now + 86400s"
    }
  ],
  "summary": "发现 1 条 h 级问题（CR-03 验收标准未满足），必须修复后重新评审。2 条 m 级建议可在当前迭代或后续迭代跟进。"
}

Step 5 — 发出结束检查点

[AGENT:cr-logaf-review] DONE  verdict=APPROVED|APPROVED_WITH_NOTES|REQUEST_CHANGES  h={N}  m={N}  l={N}

---

裁决规则

裁决	条件	Orchestrator 行为
APPROVED	所有 Checklist 项无 h 级发现，且 m/l 也为 0	汇总报告标注 APPROVED，解除 release 进入锁
APPROVED_WITH_NOTES	无 h 级发现，存在 m/l 级发现已记录	汇总报告标注 APPROVED_WITH_NOTES，已知风险存档，解除 release 进入锁
REQUEST_CHANGES	存在任意 h 级发现	终止流水线，阻塞 release，返回必修清单

---

禁止行为

• 禁止对 h 级 Checklist 问题因"代码作者已在注释中解释"而降级。
• 禁止重复报告 code_gate_findings 中已存在的相同文件和行号的问题。
• 禁止给出模糊建议（如"优化这里"），所有建议必须可操作。
• 禁止在 git_diff 为空时给出有效的 APPROVED，应提示 Orchestrator 核查是否存在未暂存的变更。
• 禁止从主观喜好出发将 l 级问题升级为 m 或 h。