SuperClaude Framework 实现后自审机制:Self Review Agent 与基于证据的验证协议

SuperClaude Framework 实现后自审机制:Self Review Agent 与基于证据的验证协议 SuperClaude Framework 实现后自审机制Self Review Agent 与基于证据的验证协议【免费下载链接】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自审代理展开讲解它在一次实现迭代implementation wave结束后如何对 SuperClaude Agent 的交付结果进行投产前确认production-ready confirmation并通过四道强制自查问题、证据校验和 Reflexion 错误模式记录把测试通过需求达成这类口头宣称变成可核验的工程事实。读完本文你将掌握该代理的完整操作流程、报告模板、底层SelfCheckProtocol的幻觉检测机制以及如何把它接入/sc:reflect、/sc:test等配套命令在团队或个人开发中建立一道低成本、可复制的质量闸门。一、Self Review Agent 是什么定位与触发时机在 SuperClaude Framework 的代理体系中Self Review Agent 被定义为实现后验证与反思伙伴Post-implementation validation and reflexion partner分类归属category: quality质量域与 quality-engineer.md 同属质量保证体系。其代理定义文件位于 src/superclaude/agents/self-review.md同时以插件形式镜像在 plugins/superclaude/agents/self-review.md。根据 src/superclaude/agents/README.md 的说明src/superclaude/agents/下的定义文件是为包分发而复制的副本更新时应先修改plugins/superclaude/agents/再同步到src/两侧保持一致——这是理解该文件双份存在的关键。触发时机文档明确要求在一次实现迭代结束后立即使用immediately after an implementation wave目的是确认交付结果已达到生产可用标准并沉淀经验教训。它与常规代码审查review code不同它审查的不是代码风格而是交付声明与证据之间的一致性——SuperClaude Agent 声称完成了什么、实际证据是否支持这个声明。核心职责Primary Responsibilities共四条核验测试与工具链验证 SuperClaude Agent 汇报的测试与工具执行结果是否真实运行四道强制自查问题测试/验证是否执行、边界情况是否覆盖、需求是否匹配、是否需要后续或回滚步骤汇总残余风险与缓解思路明确列出尚未消除的风险及其对策记录 Reflexion 模式当缺陷出现时记录反思模式帮助 SuperClaude Agent 未来避免重复犯错。二、四道强制自查问题验证协议的骨架Self Review Agent 的运行不依赖主观印象而是强制回答四个固定问题这是整个自审机制的灵魂#自查问题需要回答的内容反面信号未达标表现1Tests/validation executed?执行的具体命令 真实结果outcome只说测过了但拿不出命令与输出2Edge cases covered?已覆盖的边界情况以及有意排除的清单完全没提边界情况或避而不谈未覆盖项3Requirements matched?逐条回扣验收标准acceptance criteria需求与实现脱节无法对账4Follow-up or rollback steps needed?明确的后续动作或回滚预案声称全部完成却无任何后续计划第 2 问中列出任何有意留出的部分list anything intentionally left out非常关键——它把边界情况未覆盖从隐瞒项变成显式声明的风险项便于后续决策是否接受该残余风险。这套四问在代码层有直接对应实现。src/superclaude/pm_agent/self_check.py 中的SelfCheckProtocol将同样的问题表述为Are all tests passing?所有测试是否通过Are all requirements met?所有需求是否满足No assumptions without verification?是否存在未经核实的假设Is there evidence?是否有证据从源码结构看validate()方法self_check.py依次调用四个内部检查器分别对测试状态、需求覆盖、假设核验、证据完整性进行判定任何一项不满足都会累积为 issue 列表最终返回(passed, issues)二元组。四问之外还会追加执行_detect_hallucinations()幻觉检测见第四节。三、操作流程从交接材料到清单式报告Self Review Agent 的操作流程共四步文档给出了明确的顺序Step 1 — 审阅交接材料检查 SuperClaude Agent 提供的任务总结task summary与实现 diff。注意第 2 步要求审阅实现 diff即自审不是只看结论而是把结论与代码变更对起来看。Step 2 — 确认测试证据如果测试证据缺失必须在批准之前要求重跑request a rerun before approval。这是先证据、后放行的硬性门槛——没有测试证据的实现不得通过自审。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四个符号各有语义✅表示已满足并有证据⚠️表示存在残余风险此处为并发行为未测试属于有意留出项表示后续行动项下个迭代补充负载测试。这份模板把四道自查问题的答案压缩成一眼可读的状态面板。Step 4 — 定向补救而非推倒重来当发现问题时推荐给出针对性行动targeted actions而不是重新打开整个任务rather than reopening the entire task。这保证了自审的成本可控不会因为局部缺陷触发全局返工。流程收尾时Self Review Agent 保持答案简短、聚焦证据而非叙事focus on evidence, not storytelling并把结果交还给 SuperClaude Agent 用于最终的用户回复——它始终是验证者与证据把关者而非直接面向用户输出结果的执行者。四、源码级支撑SelfCheckProtocol 的幻觉检测与证据校验4.1 证据校验的三类硬性要求SelfCheckProtocol._check_tests_passing()self_check.py体现了测试通过必须附带真实输出的反幻觉约束要求tests_passed True要求test_output非空且包含passed、OK、✓、✅等通过指示词仅声明通过而缺少输出直接判定不通过。这与 Self Review Agent 第 2 步证据缺失要求重跑完全一致是同一原则在代码层的落地。_check_evidence_exists()self_check.py进一步规定证据必须包含三类test_results测试结果、code_changes变更文件清单、validationlint、类型检查、构建等静态验证结果。tests/unit/test_self_check.py中的test_check_evidence_exists用例验证了缺任意一项都会被列入 missing 列表。4.2 七个幻觉红旗HALLUCINATION_RED_FLAGS代码中显式定义了 7 种幻觉红旗self_check.py_detect_hallucinations()self_check.py对其进行自动化检测声称测试通过但不展示输出声称一切正常但没有证据测试失败却声称实现完成跳过错误信息skipping error messages忽略警告ignoring warnings隐藏失败hiding failures大概能行类不确定表述probably works statements。第 7 类通过扫描描述文本中的不确定性词汇probably、maybe、should work、might work实现第 46 类通过检查errors/warnings与status: complete的组合来判定——一旦存在未处理的错误或警告却声称完成即触发忽略错误/警告红旗。tests/unit/test_self_check.py中test_detect_hallucinations_*系列用例对每种红旗都有对应的失败场景测试如无输出通过声明、无证据声称完成、失败测试声称完成、忽略错误警告、不确定性语言。4.3 数据契约validate 方法的输入结构从validate()的 docstring 与 tests/conftest.py 中的sample_implementationfixture 可以看出一个合格实现的输入契约应包含{ tests_passed: True, test_output: ✅ 5 tests passed in 0.42s, requirements: [Feature A, Feature B, Feature C], requirements_met: [Feature A, Feature B, Feature C], assumptions: [API returns JSON, Database is PostgreSQL], assumptions_verified: [API returns JSON, Database is PostgreSQL], evidence: { test_results: ✅ All tests passing, code_changes: [file1.py, file2.py], validation: Linting passed, type checking passed, }, status: complete, }对照的failing_implementationfixtureconftest.py则展示了一份全面不合格的反例测试失败、无输出、需求仅部分满足、假设未全部核实、证据为空、存在错误却标记 complete。两个 fixture 一正一反可直接作为自审输入数据的模板。最终通过format_report()self_check.py生成 ✅ Self-Check PASSED 或逐条列出 ❌ Self-Check FAILED - Issues detected 的报告。五、缺陷复盘闭环ReflexionPattern 与经验沉淀Self Review Agent 第 4 条职责是记录 Reflexion 模式其底层实现是 src/superclaude/pm_agent/reflexion.py 中的ReflexionPattern类核心思想是从过去的错误中学习防止复发。5.1 双存储策略与查找流程ReflexionPattern的错误知识采用双存储策略见 reflexion.py 与__init__默认记忆目录为当前项目docs/memory/主存储docs/memory/solutions_learned.jsonl追加式 JSONL 日志次存储mindbase 语义检索可用时兜底基于 grep 的本地文本搜索。get_solution()reflexion.py的查找顺序是先用错误签名向 mindbase 语义搜索服务发起查询http://localhost:18003/api/search相似度阈值 0.7 才采纳超时或失败会优雅降级未命中则回退到本地 JSONL 文件做词重叠相似度比对_signatures_match()默认重叠阈值 0.7。5.2 错误记录与 Mistake 文档record_error()reflexion.py负责写入 JSONL 并附带时间戳当错误信息包含root_cause或solution时_create_mistake_doc()reflexion.py会在docs/mistakes/下生成[test_name]-YYYY-MM-DD.md格式的详细复盘文档固定结构包含What Happened发生了什么、Root Cause根因、Why Missed为何漏掉、Fix Applied修复方案、Prevention Checklist预防清单、Lesson Learned经验教训。仓库的 docs/mistakes/ 目录中已有真实产物可作参考例如test_database_connection-2025-11-11.md、test_reflexion_with_real_exception-2026-03-22.md等docs/memory/solutions_learned.jsonl 是实际累积的错误-解决方案知识库docs/memory/reflexion.jsonl.example 则给出了记录格式示例。tests/unit/test_reflexion.py中的test_reflexion_with_real_exception演示了真实异常场景下的标准用法捕获ZeroDivisionError→ 组装错误信息 →reflexion.record_error(...)。5.3 与自审的关系形成质量闭环Self Review Agent发现问题与 ReflexionPattern沉淀教训构成闭环自审发现的缺陷被记录为带解决方案的经验条目SuperClaude Agent 下次遇到相似错误签名时即可复用已知解法避免重复踩坑。这与文档中记录 reflexion 模式使 SuperClaude Agent 能避免重复avoid repeats的表述一一对应。六、配套命令与协同代理自审如何融入工作流Self Review Agent 并非孤立存在它与以下命令和代理协同构成完整的质量工作流6.1 /sc:reflect — 任务反思与验证命令src/superclaude/commands/reflect.md 提供reflect命令用法为/sc:reflect [--type task|session|completion] [--analyze] [--validate]它通过 Serena MCP 的反思工具think_about_task_adherence、think_about_collected_information、think_about_whether_you_are_done完成分析 → 验证 → 反思 → 记录 → 优化五步流程并用read_memory/write_memory实现跨会话持久化。其中--type completion模式专门评估任务完成标准与实际进展的匹配度与 Self Review Agent 的需求回扣验收标准直接呼应。6.2 /sc:test 与 /sc:analyze — 证据来源src/superclaude/commands/test.md 的/sc:test用于执行测试并产出覆盖率报告与质量指标[--type unit|integration|e2e|all]、[--coverage]、[--watch]、[--fix]等参数可支撑自审第 1 问测试证据从哪来src/superclaude/commands/analyze.md 的/sc:analyze提供质量/安全/性能/架构多域静态分析可补充自审报告中的validationlint、类型检查类证据。6.3 quality-engineer — 边界情况的前置防线src/superclaude/agents/quality-engineer.md 的思维定式是超越快乐路径发现隐藏失败模式其边界情况检测能力正好为自审第 2 问Edge cases covered?提供前置输入——质量工程师先行覆盖边界自审代理负责确认覆盖声明与证据一致。6.4 运行验证项目中的测试命令根据仓库根目录 AGENTS.md 的约定自审报告中的测试命令应以make test即uv run pytest为主开发期间可用uv run pytest -m unit限定单元测试范围涉及 CLI 或插件启动的变更还应补充 tests/integration/test_pytest_plugin.py 的集成覆盖。上述自审与 Reflexion 相关的单元测试位于 tests/unit/test_self_check.py 和 tests/unit/test_reflexion.py均可作为自审机制本身被测试的实证。七、落地实践把自审机制用起来场景一一次实现的收尾自审SuperClaude Agent 完成一次实现迭代后立即触发 Self Review Agent按四问逐一核验输出清单式报告并交还结果。核心纪律是测试证据缺失时绝不放行。场景二与 Reflexion 联动沉淀经验自审发现缺陷 → 用record_error记录错误签名与解决方案写入docs/memory/solutions_learned.jsonl必要时生成docs/mistakes/*.md复盘文档→ 下次get_solution命中即复用已知解法。场景三作为质量闸门嵌入开发节奏将自审固定在每个实现波次之后而非全部完成之后配合uv run pytest -m unit的快速反馈、/sc:analyze的静态检查证据和/sc:reflect --type completion的完成度核验形成实现 → 自审 → 沉淀 → 复用的循环。使用要点速览证据优先任何测试通过/实现完成的声明都必须附带真实输出与变更清单边界显式化未覆盖的边界情况要主动列出作为显式风险而非隐藏缺陷定向补救发现问题给出针对性行动避免推倒重来复盘沉淀缺陷必须落到 Reflexion 知识库让错误产生复利保持简短报告聚焦证据不做叙事性描述。结语Self Review Agent 是 SuperClaude Framework 中把AI 声称转化为工程事实的关键一环。它用四道强制自查问题框定验证范围用清单式报告压缩信息密度用SelfCheckProtocol的七个幻觉红旗拦截无证据声明用ReflexionPattern把每次缺陷转化为可复用的经验资产。无论你是单独使用代理定义还是将其纳入更大的质量工作流这套先证据、后放行边验证、边沉淀的方法论都值得直接复制到自己的 AI 辅助开发流程中。【免费下载链接】SuperClaude_FrameworkA configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies.项目地址: https://gitcode.com/gh_mirrors/su/SuperClaude_Framework创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考