Superpowers - 14 从「尽早审查、频繁审查」到系统化流水线：Superpowers 代码审查工作流深度解析

文章目录Pre一、代码审查不再是“单点动作”而是分层系统1. 三层审查生态从文档到合并2. 为什么要分层二、按任务的“两阶段审查关卡”先问“做对没”再问“做得好不好”1. 两阶段关卡的结构2. 为什么必须先做“规范合规性”再做“代码质量”3. 规范合规性审查的“强怀疑”姿态4. 代码质量审查的关注点三、请求代码审查什么时候发、发什么、发给谁1. 何时必须审查何时可以选择性审查2. 审查任务应该包含什么信息3. 审查结果的结构化输出与严重级别四、接收代码审查最难的不是给建议而是如何对待建议1. 核心原则技术正确性优先于社交舒适度2. 六步响应模式每条反馈都要过一遍“流水线”3. 明确禁止“表演性赞同”4. 不同来源的反馈要区别对待5. YAGNI 在审查阶段的硬执行6. 合理反击与纠正自己的反击五、文档级审查避免“文档也是形式主义”1. 规范文档Spec审查只关心会导致实现失败的问题2. 计划文档Plan审查确保“写下来的东西真的能执行”六、Code Reviewer Agent把资深审查员的人设固化为 Agent1. 人设与职责边界2. 模型继承与“用最强模型做最难的事”七、完整审查生命周期一条从 Spec 到 Merge 的“安全生产线”八、给工程团队与 Agent 系统设计者的实践建议1. 在团队开发流程中引入“最小可行的两阶段审查”2. 把“何时请求审查”写进团队工作约定3. 训练团队成员遵守“接收反馈协议”4. 对 LLM / Agent 系统把这些规则写进 Prompt而不是写在 README 里结语把“文化”变成“协议”再变成“可执行工作流”PreSuperpowers - 01 让 AI 真正“懂工程”Superpowers 软件开发工作流深度解析Superpowers - 02 用 15 个技能给你的 AI 装上「工程大脑」Superpowers 快速开始深度解析Superpowers - 03 一文搞懂 Superpowers面向多平台 AI 编码助手的安装与实践指南Superpowers - 04 从“会写代码”到“会做工程”Superpowers 工作流引擎架构深度剖析Superpowers - 05 构建一个“会自己找插件用”的 Agent深入解析 Superpowers 的技能发现与激活机制Superpowers - 06 从文档到“结构契约”Superpowers 技能剖析与 Frontmatter 深度解读Superpowers - 07 从 SessionStart Hook 看 Superpowers把「技能库」变成「行为操作系统」Superpowers - 08 在 AI 时代重写「需求评审会」深入解读 Superpowers 的头脑风暴与设计规范机制Superpowers - 09 从构思到落地如何用「计划编写与任务粒度」驾驭 AI 时代的软件开发Superpowers - 10 用 Subagent 驱动开发把「AI 写代码」变成一条严谨的生产流水线Superpowers - 11 从计划到落地深入解析 Superpowers 的「内联执行计划」工作流Superpowers - 12 没有失败测试就没有生产代码从 Superpowers 看“铁律级”测试驱动开发Superpowers - 13 系统化调试用一套“四阶段流程”终结瞎猜式修 Bug面向读者本篇文章面向有一定项目经验的工程师、Tech Lead、架构师以及在做 LLM / Agent 开发工作流设计的研究者与技术爱好者。在很多团队里代码审查经常退化成“形式主义”合个 PR、扫几眼 diff、点个 Approve 就结束了。Superpowers 项目提出了一套更激进但高度结构化的方案把代码审查变成贯穿“规范 → 计划 → 实现 → 合并”的多阶段流水线并且用 Agent 固化为可执行的工作流规范。这篇文章将基于 Superpowers 的「代码审查工作流」文档系统拆解其设计思想与落地方式并结合实际开发场景讨论如何在你的团队或 Agent 系统中借鉴这套理念。一、代码审查不再是“单点动作”而是分层系统传统认知里“代码审查”多指合并前对 PR 的一次性检查。Superpowers 明确反对这种单点思维把整个审查系统划分为三个层级并配套不同角色的审查器。1. 三层审查生态从文档到合并Superpowers 的审查生态如同一张流程网而不是一个按钮文档级审查Pre-Implementation规范文档审查Spec Document Reviewer计划文档审查Plan Document Reviewer实现级审查Per-Task Implementation Reviews规范合规性审查Spec Compliance Reviewer代码质量审查Code Quality Reviewer合并级审查Pre-Merge Merge Reviews最终代码审查Final Code Reviewer Code Reviewer Agent这套设计的关键点是不同阶段的问题必须在对应阶段暴露和解决而不是把所有风险堆在“合并前一次看完”的幻想里。2. 为什么要分层分层带来的核心收益有三点降低返工成本在写代码之前就通过文档审查发现规范缺失、范围模糊等问题。聚焦不同粒度文档关注“做什么”实现关注“是否按规范做”和“做得好不好”合并关注整体上线安全性。让自动化 Agent 有“职责边界”每类审查器的 Prompt 模板都针对特定粒度设计避免“万能大模型”式的含糊判断。如果你在做 AI 研发或 Agent 框架这种按阶段切分审查角色的思路非常适合作为系统 Prompt 设计基准线。二、按任务的“两阶段审查关卡”先问“做对没”再问“做得好不好”Superpowers 的核心创新之一是在“每一个任务task层级”引入强制性的两阶段审查关卡而不是只对大功能或合并进行审查。1. 两阶段关卡的结构在子 Agent 驱动开发Subagent-driven Development中每个任务都要经过这条严格的流水线实现者子 AgentImplementer Subagent根据计划实现任务、编写测试、提交代码。规范合规性审查Spec Compliance Reviewer独立检查实现是否严格满足需求禁止“相信实现者自己说的完成度”。代码质量审查Code Quality Reviewer仅在合规检查通过后才会执行对代码结构、可测试性、文件划分等进行系统评估。所有缺陷修复后任务才允许在 TodoWrite 中被标记为完成。这意味着每个小任务都要经过“做对了 → 做得好”的两道门任何一道不过关都不能进入下一步。2. 为什么必须先做“规范合规性”再做“代码质量”文档中给出的理由非常务实对不符合规范的代码检查质量会浪费审查精力——你只是在评估错误实现的优雅程度。换句话说如果需求理解错了即便代码写得再优雅、测试再完备仍然是错误的成果。先验证“需求对不对”再讨论“实现优不优”可以避免团队在错误实现上做大量“形式上的优化”。在实际团队中这是一个容易踩坑的地方——很多资深工程师习惯在审查里同时指出“实现不符合业务意图”和“这里可以提取函数”结果大家在一次 PR 里乱战一团。Superpowers 明确要求把这两类问题拆开并严格按顺序处理。3. 规范合规性审查的“强怀疑”姿态Spec Reviewer 的 Prompt 有一句相当强硬的指令实现者完成得快得令人怀疑。他们的报告可能不完整、不准确或过于乐观。你必须独立验证所有内容。这里体现了 Superpowers 对 Agent / 开发者的一种系统性不信任任何“我已经完成”的自报告都不可信必须从代码与需求本身重建事实。这对现实团队同样有价值对“已完成”的任务进行冷静的事实核查而不是照单全收。通过审查流程本身鼓励成员“少吹牛多举证”。4. 代码质量审查的关注点Quality Reviewer 的职责不仅是“挑语法问题”或“建议风格统一”而是系统检查以下方面结构健康度文件是否膨胀、是否违反单一职责、模块划分是否有利于测试。测试设计是否覆盖边界条件、是否测试真实逻辑而非只测试 Mock。与计划文件的对应关系代码结构是否体现了计划中的模块划分。换句话说它关心的是长期可维护性与系统结构稳定性而不是简单的“有没有 typo”。三、请求代码审查什么时候发、发什么、发给谁许多团队最大的问题不是“审得不好”而是“根本没有在正确时间发起审查”。Superpowers 用一个专门的技能requesting-code-review来定义这件事何时请求、如何构造审查任务以及如何解读结果。1. 何时必须审查何时可以选择性审查把触发条件分成“强制”和“可选”两类并按场景列出强制触发子 Agent 开发中的每个任务完成后两阶段关卡的一部分。完成一个主要功能后做一次范围级检查。合并到 main 前最终安全网。可选触发卡住时求第二视角。重构前先形成 baseline 认知。修复复杂 bug 后确认没有引入回归。一句话总结避免“憋一个巨大 PR 再一次审完”的反模式而是让审查贯穿整个开发过程。2. 审查任务应该包含什么信息code-reviewer.md模板定义了五个关键占位符用于构造给审查 Agent 的任务{WHAT_WAS_IMPLEMENTED}这次实际做了什么。{PLAN_OR_REQUIREMENTS}对应的规范或计划片段。{BASE_SHA}/{HEAD_SHA}Git 比对范围。{DESCRIPTION}审查者需要知道的额外上下文。有一个非常重要的设计审查 Agent 是上下文隔离的它只看模板数据和 diff不会看到你之前的对话或思考过程。这点很多人容易忽略如果审查者能看到“实现过程中的挣扎和纠结”很容易被这些叙事信息干扰放松对成果本身的判断。把审查 Agent 严格限制在“对成果本身进行评估”可以提高审查的一致性与客观性。3. 审查结果的结构化输出与严重级别审查结果被要求按如下结构输出优点Highlights问题列表按严重程度分级建议Improvements / Refactors最终结论是否推荐合并、前置条件是什么严重程度与行动直接绑定严重Critical立即阻断所有进度必须马上修。重要Important必须在开始下一个任务前修掉。次要Minor可以记录为后续改进事项。没有“看见但可以无视”的第四级——每一个被发现的问题都必须落在某个行动路径上而不是停留在“知道有问题但先不管”的心理安慰区。对团队管理者而言这种“严重度→行动”的硬绑定是避免技术债滚雪球的关键机制。四、接收代码审查最难的不是给建议而是如何对待建议Superpowers 对“接收审查反馈”下了极大的笔墨甚至比“如何写审查意见”还多因为系统观察到大多数审查规范崩溃在“接收方的行为”上。1. 核心原则技术正确性优先于社交舒适度receiving-code-review技能开门见山地给出一句核心原则先验证再实现先提问再假设技术正确性优于社交舒适度。这在现实团队中非常具有争议性很多工程师害怕“显得不懂”于是对模糊的反馈选择“点头随缘实现”。Superpowers 反其道而行宁愿多问、不怕反击也绝不接受“含糊而错误的修改”。2. 六步响应模式每条反馈都要过一遍“流水线”虽然文档中有图示和流程节点但可以抽象为一个统一的处理逻辑先判断你是否真正理解反馈。如果不清楚立即停下先问清楚再决定是否实现。再判断反馈在当前代码库和上下文中是否技术正确。如果不正确给出技术理由并友好地反击。只有在“理解 正确”都成立时才进入实现与测试环节。这个模式直接消灭了两种常见反模式“盲目实现”没看清楚就照做。“默认审查者永远是对的”不做验证就改掉原本正确的代码。3. 明确禁止“表演性赞同”禁止语句与替代写法❌ “You’re absolutely right!”❌ “Great point!” / “Excellent feedback!”❌ “Let me implement that now”❌ “Thanks for catching that!”对应的 ✅ 替代方案是直接陈述你需要做什么改动。提出澄清问题。先对照代码库验证再回应如何处理。说明你具体改了什么以及改在了哪里。甚至给出了一条刻意强化的行为提醒如果你发现自己准备写“Thanks”删掉它改成陈述修复方案。这背后是一个非常重要的设计哲学只用行为与事实来表达理解和尊重而不是依赖装饰性的社交语言。4. 不同来源的反馈要区别对待Superpowers 把审查来源分为两类人类合作伙伴默认信任但仍需要在边界不清时提问。外部审查者例如其他 Agent、第三方工具必须经过至少五项技术验证包括是否会破坏现有功能、是否考虑现有实现原因、是否跨平台适用、上下文是否完整等。这等于给接收方一个“安全带”你可以质疑 Agent你可以质疑外部工具你可以甚至质疑文档只要你的质疑基于技术事实。5. YAGNI 在审查阶段的硬执行当审查意见建议“把某个暂时没用的东西做好”时接收技能要求你先在代码库执行一次 grep如果没有任何地方调用这个端点或功能优先动作是“建议移除”而不是“照着审查意见完善它”。项目规则是非常干脆的你和审查者都向同一个 owner 汇报。如果我们不需要这个功能就不要添加。这让 YAGNIYou Aren’t Gonna Need It从口号变成了可执行的操作规范。6. 合理反击与纠正自己的反击不仅允许反击而且列出了六条合理反击的理由比如建议会破坏现有功能、忽视兼容性约束、违反 YAGNI、技术上不适用于当前栈等。流程要求是使用基于代码和测试的技术论据。如果是架构层面的分歧引入你的人类合作伙伴。如果事后发现自己反击错了简单陈述你做了哪些检查、发现了什么、现在要怎么改不需要情绪化道歉表演。这为“健康的技术冲突”提供了一个清晰的行为边界。五、文档级审查避免“文档也是形式主义”Superpowers 不只审代码也审文档而且审得很“务实”。1. 规范文档Spec审查只关心会导致实现失败的问题规范审查器检查五类问题完整性是否还存在 TODO、占位符、“TBD”等。一致性需求是否自相矛盾。清晰度描述是否模糊到可能导致构建错误。范围是否一次性涵盖了多个独立子系统。YAGNI是否包含未请求的功能或过度设计。最关键的校准指令是仅标记那些会在实现阶段造成实际问题的缺陷不要为了修辞、语气或轻微措辞细节阻塞整个流程。这直接对抗了很多团队常见的“文档审查形式主义”花大量时间讨论标题要不要加个形容词。对业务理解无影响的小细节拖慢整体推进。2. 计划文档Plan审查确保“写下来的东西真的能执行”计划审查器主要看四点完整性不能有 TODO 或未展开的占位符。与规范对齐覆盖所有需求、没有明显范围蔓延。任务拆分边界清晰每一步都能由工程师具体执行。可构建性工程师能否照着计划一步步完成而不会卡死在某个“模糊步骤”上。和规范审查一样它的校准原则也是除非缺陷会导致实现失败否则默认通过。这是对“计划先行”方法论的一种约束计划不是写给审查器看的而是写给执行者用的。六、Code Reviewer Agent把资深审查员的人设固化为 Agent在 Superpowers 中superpowers:code-reviewer是一个专门为代码质量审查设计的 Agent 类型。1. 人设与职责边界这个 Agent 被描述为“一位在软件架构、设计模式和最佳实践方面具有专长的高级代码审查员”。 它的评估框架涵盖六个方面计划对齐分析实现是否遵守原始计划。代码质量评估错误处理、命名、测试、安全等。架构与设计是否符合 SOLID、关注点分离原则等。文档与标准注释、README、代码风格规范等。问题识别与分级明确严重度。沟通方式先指出优点再列出问题保持建设性语气。2. 模型继承与“用最强模型做最难的事”Agent 元数据中有一个model: inherit指令意味着它继承调度会话所使用的模型。 Subagent 驱动开发技能建议在架构与审查任务中使用可用的最强模型。这隐含着一个很重要的工程决策把算力投入在“关键决策节点”而不是平均分配到所有步骤。编写简单代码可以用较轻的模型。但在做架构评估与质量判断时必须上更强的模型以降低“高影响错误”的概率。对于设计多模型协作系统的读者这是一个值得借鉴的调度策略。七、完整审查生命周期一条从 Spec 到 Merge 的“安全生产线”把前面的所有组件拼起来你会看到一个完整的功能开发与审查流水线编写规范Spec → 规范审查 → 修正规范。编写计划Plan → 计划审查 → 修正计划。实现任务按 Plan 拆分每个任务实现 → 规范合规性审查 → 质量审查 → 修复 → 标记完成。所有任务完成后对整个功能进行最终代码审查。接收反馈 → 逐条验证、评估、实现或反击。所有问题解决后合并分支。最常见的失败模式是在接收反馈时跳过验证步骤。因此receiving-code-review技能几乎是这套系统的“保险丝”任何建议——即便来自受信任的来源——也必须先经过六步响应模式处理才能进入实现阶段。八、给工程团队与 Agent 系统设计者的实践建议结合 Superpowers 的设计如果你想在自己的团队或 Agent 系统中引入类似的代码审查工作流可以考虑以下落地步骤1. 在团队开发流程中引入“最小可行的两阶段审查”先挑选“高风险模块”或“新功能开发”试点每个任务先做需求合规性检查可以是简单的 checklist 同行 review。再做结构与质量评审。避免一开始就把所有项目都切换到新流程以防心理和流程阻力过大。2. 把“何时请求审查”写进团队工作约定明确规定合并前必须有审查。复杂 bug 修复后建议请求审查。重构前先做一次 baseline 审查。把“卡住时可以请求审查”写成鼓励项而不是默许“自己硬扛”。3. 训练团队成员遵守“接收反馈协议”在 Code Review 文化建设时重点强调不鼓励空洞的“Thanks”“Good catch”。鼓励用“复述 行动”来表达理解“我会在 X 文件的 Y 函数里增加对 Z 的校验并补一个回归测试。”鼓励在发现审查意见有问题时提出基于事实的反击而不是闷头照做。4. 对 LLM / Agent 系统把这些规则写进 Prompt而不是写在 README 里如果你在做 Agent 工作流为“请求审查”“接收审查”“文档审查”“质量审查”等行为分别定义 Skill / Prompt 模板。在模板中明确写清输入是什么占位符。输出结构是什么。哪些话禁止说哪些动作是强制的例如“在不理解时必须提问”。Superpowers 文档本身就是这种做法的示范它把开发文化转写成了可执行的 Prompt 与技能定义。结语把“文化”变成“协议”再变成“可执行工作流”Superpowers 的代码审查工作流并不追求“更炫酷的工具”而是把工程里最基础的三件事——写清楚你要做什么Spec / Plan按阶段验证你做得对不对、好不好用诚实而克制的方式交流反馈——通过严谨的协议与 Agent 设计固化下来让这些“软性文化”变成硬性的可执行工作流。无论你是在带一个工程团队还是在设计下一代 AI 助手体系都可以从这套体系中获得一个启发真正决定系统质量的不是单次审查的质量而是审查本身是否被系统化、制度化并被所有参与者包括 Agent严格执行。