SuperClaude Framework Self Review Agent 实战指南：实现后自检、证据校验与 Reflexion 错误学习-平芜编程栈

SuperClaude Framework Self Review Agent 实战指南：实现后自检、证据校验与 Reflexion 错误学习

【免费下载链接】SuperClaude_FrameworkA configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies.项目地址: https://gitcode.com/gh_mirrors/su/SuperClaude_Framework

本指南以 SuperClaude Framework 的 Self Review Agent（位于 plugins/superclaude/agents/self-review.md，源码同版位于 src/superclaude/agents/self-review.md）为核心，讲解如何在每次实现波次（implementation wave）结束后，用四项强制自检问题确认交付物是否达到生产就绪标准，并通过 Reflexion 模式沉淀错误经验防止复发。读完本文，你将掌握一套可复制的"实现后验证 + 教训沉淀"闭环流程，以及它在框架源码（SelfCheckProtocol、ReflexionPattern）与 pytest 插件中的落地实现。

Self Review Agent 的角色定位

在 SuperClaude Framework 中，Self Review Agent 是一个post-implementation validation and reflexion partner（实现后验证与反思伙伴），类别归属为quality。它的触发时机非常明确：在一次实现波次（implementation wave）结束后立即启用，用于确认结果是否生产就绪（production-ready），并捕获本次实现产生的经验教训。

它与 PM Agent（见 plugins/superclaude/agents/pm-agent.md）形成互补：PM Agent 负责把实现过程中的模式、决策与错误沉淀为知识库，而 Self Review Agent 专注于验收环节——核实 SuperClaude Agent 声称完成的测试与工具链结果，输出简洁的清单式报告，并把残余风险与后续动作交还给 SuperClaude Agent 进行最终用户回复。

核心职责一：核实测试与工具链证据

Self Review Agent 的首要职责是Verify tests and tooling reported by the SuperClaude Agent，即逐条核对 SuperClaude Agent 上报的测试和工具执行结果，而不是照单全收。

这里的核心理念是"证据优先"：一个声称"测试通过"的结论，必须附带实际的命令与输出，否则不能视为有效证据。这一要求在框架源码中被硬编码为校验规则（详见下文"源码级支撑"一节），SelfCheckProtocol._check_tests_passing()会同时要求tests_passed=True与test_output非空，且输出中必须包含passed、OK、✓、✅等通过标志；仅有断言而无真实输出时，直接判定为不通过。

核心职责二：运行四项强制自检问题

这是 Self Review Agent 的方法论骨架。在原文档 plugins/superclaude/agents/self-review.md 中规定了四项强制问题，它们与源码 src/superclaude/pm_agent/self_check.py 中SelfCheckProtocol注释里记载的 "The Four Questions" 一一对应，但在表述上略有差异（Agent 文档侧重验收视角，源码侧重防幻觉视角）：

维度	Agent 文档的四问	源码`SelfCheckProtocol`的四问
测试	Tests/validation executed?（附带命令与结果）	Are all tests passing?（要求展示真实结果）
边界	Edge cases covered?（列出有意遗漏项）	No assumptions without verification?（假设必须核对官方文档）
需求	Requirements matched?（回连验收标准）	Are all requirements met?（逐条对比 ✅/❌）
收尾	Follow-up or rollback steps needed?	Is there evidence?（测试结果、代码变更、lint/类型检查）

从源码结构看，这四项问题被映射为validate()中的四次独立检查：

# 摘自 src/superclaude/pm_agent/self_check.py#L64-L107（结构示意） issues = [] # Question 1: Tests passing? if not self._check_tests_passing(implementation): issues.append("❌ Tests not passing - implementation incomplete") # Question 2: Requirements met? unmet = self._check_requirements_met(implementation) if unmet: issues.append(f"❌ Requirements not fully met: {', '.join(unmet)}") # Question 3: Assumptions verified? unverified = self._check_assumptions_verified(implementation) if unverified: issues.append(f"❌ Unverified assumptions: {', '.join(unverified)}") # Question 4: Evidence provided? missing_evidence = self._check_evidence_exists(implementation) if missing_evidence: issues.append(f"❌ Missing evidence: {', '.join(missing_evidence)}")

其中证据维度进一步细化为三类硬性要求（见_check_evidence_exists()，src/superclaude/pm_agent/self_check.py）：

test_results：测试实际输出；
code_changes：变更文件清单；
validation：lint、类型检查、构建等静态校验结果。

三者缺一即记为Missing evidence问题。测试夹具 tests/conftest.py 中的sample_implementation展示了满足全部四问的完整数据结构（含tests_passed、test_output、requirements、requirements_met、assumptions、assumptions_verified、evidence、status），而failing_implementation则演示了典型的失败形态（测试未过、需求仅完成 1/3、假设未全部核实、证据为空、状态却声称 complete）。

核心职责三：汇总残余风险与缓解思路

四项自检全部通过并不意味着零风险。Self Review Agent 还需Summarize residual risks and mitigation ideas——把"明知存在但不影响本次验收"的风险显式列出来，并给出缓解方向。例如原文档报告示例中的⚠️ Edge cases: concurrency behaviour not exercised就属于此类：并发行为未被覆盖，需要在后续迭代中补测。

这对应报告中的⚠️级条目，与✅级（已通过）和📓级（后续动作）共同构成三层状态标注。在源码侧，SelfCheckProtocol用🚨标注幻觉告警、❌标注硬性问题，见format_report()（src/superclaude/pm_agent/self_check.py），两者语义层级互补。

核心职责四：记录 Reflexion 模式，避免同类缺陷复发

当缺陷出现时，Self Review Agent 要Record reflexion patterns，让 SuperClaude Agent 后续不再重复犯错。这正是框架中ReflexionPattern类（src/superclaude/pm_agent/reflexion.py）的职责：把错误转化为可检索、可复用的知识。

ReflexionPattern的工作流程分为两条路径：

命中已知错误（0 token 成本）：构造错误签名（error_type | 去数字化的 error_message 前 100 字符 | test_name），先尝试 mindbase 语义检索（http://localhost:18003/api/search，相似度阈值 0.7，3 秒超时，失败自动降级），再回退到本地 JSONL 文件做词重叠匹配（默认阈值 0.7），见_search_mindbase()与_search_local_files()。

新错误（1-2K token 调研成本）：调用record_error()将错误信息追加写入docs/memory/solutions_learned.jsonl（追加式日志），若带root_cause或solution分析，还会生成结构化错误文档docs/mistakes/[test_name]-YYYY-MM-DD.md，见_create_mistake_doc()（src/superclaude/pm_agent/reflexion.py）。该文档固定包含七个板块：

## ❌ What Happened → 现象描述 ## 🔍 Root Cause → 根本原因 ## 🤔 Why Missed → 为何此前未被发现 ## ✅ Fix Applied → 实际修复方案 ## 🛡️ Prevention Checklist → 防复发清单 ## 💡 Lesson Learned → 经验教训

仓库中已有真实产出可对照：docs/memory/solutions_learned.jsonl（120 行 JSONL 记录，如{"error_type": "ConnectionError", "solution": "Ensure database is running and credentials are correct", "timestamp": "..."}）与 docs/mistakes/test_database_connection-2026-03-22.md（按上述模板生成的错误记录）。get_statistics()还能统计total_errors、errors_with_solutions与solution_reuse_rate，用于量化知识库的学习效果。

操作流程：How to Operate

原文档给出了四步操作法，这里结合框架源码补充每一步的落地细节：

Step 1：审查任务摘要与实现 diffSuperClaude Agent 会提交任务摘要（task summary）与实现差异（implementation diff），Self Review Agent 据此还原"声称做了什么"。

Step 2：确认测试证据，缺失则要求重跑这是"先证据后放行"的硬门槛。对应源码中_check_tests_passing()的两条规则：tests_passed必须为True，且test_output必须含真实通过标志。单测 tests/unit/test_self_check.py 中的test_check_tests_passing_with_output明确验证了"有输出通过 / 无输出判失败"两种分支。

Step 3：输出简短的清单式报告原文档报告模板原文如下，字段格式可照搬：

✅ Tests: uv run pytest -m unit (pass) ⚠️ Edge cases: concurrency behaviour not exercised ✅ Requirements: acceptance criteria met 📓 Follow-up: add load tests next sprint

在源码侧，format_report()提供程序化版本：通过时输出✅ Self-Check PASSED - Implementation complete with evidence；失败时逐条列出❌问题项。

Step 4：剩余问题给出定向行动建议When issues remain, recommend targeted actions rather than reopening the entire task——只针对具体问题开处方，而不是推翻整个任务重来，这保证了修复成本可控。

源码级支撑：7 个幻觉红旗检测

SelfCheckProtocol除了四问校验，还内置了一套幻觉检测机制，这是它区别于普通 checklist 的关键。HALLUCINATION_RED_FLAGS常量与_detect_hallucinations()（src/superclaude/pm_agent/self_check.py）实现了 7 类红旗的自动识别：

声称"测试通过"但未附输出（tests_passed=True且test_output为空）；
声称"一切正常"但无任何证据（status=complete且evidence为空）；
测试失败却声称"实现完成"（status=complete且tests_passed=False）；
跳过错误信息（skip error messages）；
忽略警告（ignore warnings）——4、5、6 合并为"存在 errors/warnings 却标记 complete"；
隐瞒失败（hide failures）；
使用不确定措辞（描述中出现probably、maybe、should work、might work）。

对应单测覆盖齐全：tests/unit/test_self_check.py 中的test_detect_hallucinations_tests_without_output、test_detect_hallucinations_complete_without_evidence、test_detect_hallucinations_complete_with_failing_tests、test_detect_hallucinations_ignored_errors、test_detect_hallucinations_uncertainty_language分别验证上述场景。

测试与工具链集成：pytest 插件如何挂钩自审

框架通过 pytest 插件把自审与反思流程嵌入日常测试（src/superclaude/pytest_plugin.py，入口注册于 pyproject.toml 的pytest11）：

注册自定义 marker：self_check（要求证据的实现后验证）、reflexion（错误学习与预防）、confidence_check（执行前置信度评估）、complexity(level)；
提供 fixtures：self_check_protocol、reflexion_pattern、token_budget、pm_context等，测试中可直接注入使用；
pytest_runtest_makereport钩子：带reflexionmarker 的测试失败时，自动构造error_info（测试名、文件、异常类型、消息、traceback）并调用reflexion.record_error()，实现"测试失败即自动沉淀教训"。

集成测试示例可见 tests/unit/test_self_check.py 的test_self_check_marker_integration与 tests/unit/test_reflexion.py 的test_reflexion_marker_integration；tests/unit/test_reflexion.py 的test_reflexion_with_real_exception则演示了真实异常（如ZeroDivisionError）下的完整记录路径。运行示例命令为uv run pytest -m unit（uv 环境）或pytest（pip 环境，需先安装本项目）。

与相关 Agent / 命令的协作边界

Self Review Agent 并非孤立运作。在原文档约束下，它把结果"交还给 SuperClaude Agent 做最终用户回复"，即它只做验收与证据核验，不直接向用户汇报。与之配套的还有：

/sc:reflect命令（plugins/superclaude/commands/reflect.md）：提供--type task|session|completion三种反思模式，依赖 Serena MCP 的think_about_task_adherence、think_about_collected_information、think_about_whether_you_are_done等工具做任务贴合度、信息完整性与完成度评估，可作为 Self Review Agent 验证环节的深度分析后端；
PM Agent（plugins/superclaude/agents/pm-agent.md）：其 PDCA 周期中的 Check 阶段（think_about_whether_you_are_done）与 Act 阶段（错误沉淀到docs/mistakes/、成功模式沉淀到docs/patterns/）与 Self Review Agent 的 reflexion 记录职责形成互补。

最佳实践总结

结合原文档与源码，可将 Self Review Agent 的用法浓缩为以下要点：

时机固定：每次实现波次结束立即启用，不拖延、不跳步；
证据硬约束：测试必须附命令与输出，lint/类型检查等 validation 证据缺一不可，杜绝"凭感觉放行"；
四问全过才放行：测试、需求、假设、证据四项校验，任何一项缺失都标记为未完成；
主动暴露残余风险：用⚠️显式列出未覆盖的边界与缓解方向，而非隐藏；
错误即知识：缺陷出现时立即通过record_error()写入solutions_learned.jsonl与mistakes/文档，让错误签名在未来命中时零成本复用解决方案；
定向修复：剩余问题只给针对性动作，不整单重开，控制修复成本。