用子代理流水线维护 AI 代码审查插件：agentic-awesome-skills 中的 brooks-harness 编排器实战解析
【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills
brooks-harness 是 brooks-lint 代码审查插件家族中的"维护编排器"——它不是面向开发者的审查工具，而是面向插件自身维护的自动化流水线编排技能。它以顺序子代理管道（sequential subagent pipeline）为核心，把"新增/编辑技能 → 刷新评测套件 → 保持四份清单与 README/CHANGELOG/AGENTS/GEMINI 同步 → 触发器边界审计 → 发布"这一整套维护流程拆成有依赖顺序的阶段，并在每个阶段之间用 QA 门禁（gate）保证质量闭环。读完本文，你将掌握 brooks-harness 的完整流水线设计（Phase 0 到 Phase 3）、五类子代理的职责边界、请求分类矩阵、错误处理与回退策略，以及它是如何被组织进 agentic-awesome-skills 这一 2400+ 技能仓库中的。
一、brooks-harness 的定位：维护 brooks-lint 插件本身的编排器
在 agentic-awesome-skills 的 claude 插件集 中，brooks-前缀下挂着多个相互关联的技能：brooks-lint（以 12 本经典软件工程书籍为审查透镜的 AI 代码审查器）、brooks-audit（架构审计）、以及本文主角brooks-harness。
从 brooks-harness/SKILL.md 的元信息可以看出它的定位：
name: brooks-harness，description明确指出它是 "Maintenance orchestrator for the brooks-lint plugin itself"；risk: critical——它是插件维护流水线的总控，出错会直接影响插件自身的发布质量；- 源自社区仓库
hyhmrright/brooks-lint，MIT 许可。
与 brooks-lint/SKILL.md（面向代码审查、风险等级为safe）和 brooks-audit/SKILL.md（架构审计）不同，brooks-harness 的工作对象是 brooks-lint 仓库本身：新增技能、编辑指南、刷新评测、同步清单、审计触发边界、执行发布。它把"维护一个会被其他 Agent 调用的技能库"这件高风险工作，变成了一条有门禁、有回退、可追踪的流水线。
从文档结构可以推断，brooks-harness 假定存在配套的子代理定义目录.claude/agents/与工作区_workspace/brooks-harness/，这些是上游 brooks-lint 仓库的运行环境；本文以该 SKILL.md 所述约定为准进行讲解。
二、流水线总览：顺序子代理管道，而非并行团队
brooks-harness 最核心的设计决策是：管道（pipeline），不是并行团队。文档明确写到："Stages depend on each other in order, so this is a pipeline, not a parallel team."每一个阶段都是一个在.claude/agents/中定义的专用代理（agent），编排器通过Agent工具按顺序 spawn，并把subagent_type设为代理名、始终指定model: "opus"。
整体管道如下图所示：
[orchestrator] Phase 0 context check Phase 1 classify request → select stages Phase 2 run selected stages in order, with a QA loop-back: skill-author → eval-curator → consistency-qa ─(FAIL)→ back to author │ PASS ▼ trigger-boundary-auditor (only if a description changed) ▼ release-manager (only if release requested) Phase 3 report + collect feedback四个 Phase 各司其职：
| Phase | 职责 | 关键决策 |
|---|---|---|
| Phase 0 | 上下文检查 | 判定运行模式：initial run / new run / partial re-run |
| Phase 1 | 请求分类 | 依据请求类型选择最小阶段集合（QA 永不可跳过） |
| Phase 2 | 执行管道 | 按序 spawn 子代理，QA 失败则回退重试 |
| Phase 3 | 报告与反馈 | 汇总阶段、改动、QA 判定，收集维护者反馈 |
三、Phase 0 — 上下文检查：三种运行模式
任何操作之前，编排器必须先检查_workspace/brooks-harness/目录的状态来决定运行模式。这一设计的价值在于让流水线可断点续跑，避免重复劳动或状态混乱：
- partial re-run（部分重跑）：
_workspace/brooks-harness/存在 + 维护者要求重做上次运行的某一部分 → 只调用受影响的阶段，复用先前的工作笔记（notes）； - new run（全新运行）：
_workspace/brooks-harness/存在 + 全新请求 → 先把旧目录移动到_workspace/brooks-harness_prev/，再干净起步； - initial run（首次运行）：不存在该目录 → 创建它。
这里有一个重要的职责划分：_workspace/brooks-harness/只存放运行笔记和 QA 的 PASS/FAIL 判定；真正的产物是仓库文件本身。各代理直接编辑skills/、evals/、清单（manifests），_workspace/绝不充当产物的暂存区。这种"产物与过程分离"的设计，保证了即使运行笔记丢失，仓库内容依然是最新事实来源（source of truth）。
四、Phase 1 — 请求分类：选择最小阶段集合
编排器需要根据请求类型挑选最小的阶段集合，避免无谓开销。但有一条铁律：QA 阶段永不可跳过——任何变更都必须经过门禁。
| 请求类型 | author | eval | QA | trigger-audit | release |
|---|---|---|---|---|---|
| 新增技能 | ✓（走new-skill脚手架） | ✓ | ✓ | ✓ | — |
| 编辑技能/指南内容 | ✓ | 若代码变更 | ✓ | 若description变更 | — |
编辑_shared/框架 | ✓ | 若风险定义变更 | ✓ | — | — |
| 仅评测套件 | — | ✓ | ✓ | — | — |
| 修复触发器描述 | ✓ | — | ✓ | ✓ | — |
| 发布 | — | — | ✓ | — | ✓ |
| 全量：变更 + 发布 | ✓ | 按需 | ✓ | 若适用 | ✓ |
这张表格的价值在于按需裁剪：例如"仅评测套件"时不需要 author 阶段；"编辑_shared/框架"时只有风险定义（risk defs）变了才需要刷新评测；而"修复触发器描述"则必须带上 trigger-boundary-auditor，因为描述字段直接影响触发边界。
五、Phase 2 — 逐阶段执行：五个子代理的职责边界
Phase 2 按顺序 spawn 选中的阶段，每个代理收到两类输入：(a) 任务契约（task contract）和 (b) 前一阶段的总结（previous stage's summary）。代理把总结写入_workspace/brooks-harness/，编排器在阶段之间读取这些笔记，形成信息接力。
1. skill-author（技能作者）
创建/编辑技能内容。对于全新技能，它调用new-skill脚手架（scaffold）生成骨架。该阶段结束时要回报：改动的文件清单+ 与约定相关的选择，例如新的风险代码（risk codes）、新的 Step 编号、变更的description触发短语。这些信息是后续 eval-curator 和 trigger-boundary-auditor 的输入依据。
2. eval-curator（评测策展人）
条件执行：仅当skill-author报告出现了新增/变更的风险代码或模式（modes）时才启动。它的工作是为每个新风险代码配对两条评测场景：
- happy-path 场景：验证正确输入能被正确触发；
- false-positive 场景：验证无关输入不会被误触发。
完成后运行npm run evals确认评测套件可执行。
3. consistency-qa（一致性 QA，门禁，永不可跳过）
这是整条管道的质量闸门。它执行三层验证：
- 命令级验证：
npm run validate+npm test+npm run evals； - 跨文档同步检查：四份清单（manifests）、README 徽章（badge）、CHANGELOG、AGENTS/GEMINI 的书目计数（book count）、评测计数是否一致；
- 输出判定：写入 PASS/FAIL 结论。
失败回退机制：QA FAIL 时，按照判定中指明的代理（author 或 eval-curator）回退修复，然后重跑 QA；只允许重试一次，若仍然失败则停止流水线并向维护者报告——绝不静默跳过。
4. trigger-boundary-auditor（触发器边界审计，只读）
仅在description字段发生变更时执行。它以只读方式审计六个已发布技能的触发面（trigger surfaces），检查两类问题：
- false-triggering：描述变更是否会导致在其他无关场景下被误触发；
- routing collisions：是否会与 brooks-review/brooks-audit 等兄弟技能发生路由冲突。
如果发现真实的冲突，同样回退到 skill-author 修复。文档强调该代理是 read-only 的，与 consistency-qa 需要general-purpose能力（因为它要跑 npm 脚本）形成对比。
5. release-manager（发布经理）
仅在明确请求发布且QA 已 PASS后才执行，通过release技能完成发布裁剪（cut the release）。高风险 git 操作（--no-verify、--force、历史重写）必须获得维护者显式授权，否则 release-manager 会停下询问。
六、Phase 3 — 报告与反馈闭环
管道结束后，编排器汇报：运行了哪些阶段、改动哪些文件、QA 判定结果、trigger-audit 发现（如有）、发布 URL（如有）。随后主动向维护者开放反馈："Anything to adjust in the result, the agent roles, or the pipeline order?"（结果、代理角色或管道顺序是否有需要调整的？）并把被接受的修改记录进 CLAUDE.md 的 harness 变更日志表（change-log table）。这构成了流水线自身的持续改进机制——它不只维护技能库，也维护自己。
七、强制约定：brooks-harness 的纪律清单
文档列举了四条 harness 强制执行的约定，理解这些约定有助于掌握该插件维护方式的哲学：
- 所有
Agent调用必须model: "opus"——harness 的质量直接跟随代理的推理能力，固定高端模型是为保证审查与生成质量的一致性； - consistency-qa 必须是
general-purpose（因为它要运行 npm 脚本），而 trigger-boundary-auditor 是只读的——按能力需求分配代理权限，最小权限原则在代理层面的体现； - 不创建斜杠命令（slash commands）——短形式由 session-start 钩子自动安装；
- 直接推送 main（direct-to-main）——按仓库 CLAUDE.md 的约定，变更不经过 PR 直接推到 main；全局的 simplify→review→commit 门禁仍适用于非文档编辑，但技能/指南内容属于 markdown，走 validate 门禁即可。
最后一条约定值得注意：它区分了"代码改动"与"文档/技能内容改动"两套门禁，这与 brooks-harness 所服务的对象（大量 markdown 技能文件）高度契合。
八、错误处理策略：失败有界，绝不静默
| 规则 | 行为 |
|---|---|
| 单阶段失败 | 重试一次，并把该阶段的错误作为输入；第二次失败则停止管道并报告维护者 |
| QA FAIL | 永不进入 release；回退到判定指定的代理修复后重跑，最多一次 |
| 数据冲突 | 附带来源（provenance）报告，而不是删除 |
| 高风险 git 操作 | 需要维护者显式授权，release-manager 停下询问 |
这套策略的核心是"失败有界"：允许一次自动重试吸收偶发错误，但用二次失败止损，防止管道在错误状态里空转；同时把"谁该为失败负责"的判定交给 QA 输出，保证回退目标明确。
九、测试场景：两条可验证的端到端路径
正常流程——"新增一个 brooks-security 技能"
- Phase 1 选择 author + eval + QA + audit；
skill-author运行new-skill brooks-security，创建 SKILL.md（包含 sibling-carving 的"Do NOT trigger for:"条款，用于声明负向触发边界）+ 指南；eval-curator添加一个 S 码（S-code）happy-path 场景 + 一个 false-positive 场景；consistency-qa跑通门禁 → PASS；trigger-boundary-auditor确认与 brooks-review/audit 无冲突；- 报告列出改动文件 + PASS。
错误流程——QA FAIL 于书目计数漂移
维护者新增了第十三本书，但只编辑了source-coverage.md。consistency-qa的跨文档检查发现 README 仍写着"twelve"→ FAIL，归因到skill-author。编排器回退，skill-author同步更新 README/AGENTS/GEMINI 的措辞，QA 重跑 → PASS。因为未请求发布，管道在 Phase 3 结束。
这条错误场景生动展示了跨文档同步检查的实际价值：它把"README 里的书目数量"这种极易被遗漏的文档漂移变成了可自动拦截的 FAIL 条件，而不是发布后才发现。
十、局限性与使用前提
brooks-harness 并非万能，其 SKILL.md 明确列出了三条边界，这也是在 agentic-awesome-skills 中评估是否启用它的判断依据：
- 仅在任务明确匹配其上游来源与本地项目上下文时使用——它是一个针对 brooks-lint 仓库结构的专用编排器，套用到其他项目可能水土不服；
- 应用变更前必须验证命令、生成代码、依赖、凭据与外部服务行为；
- 不要把示例当作环境专属测试、安全审查或用户对破坏性/高成本操作的批准替代品——尤其是涉及发布与高风险 git 操作时。
结语
brooks-harness 展示了一种值得借鉴的"元技能"设计：用子代理流水线来维护承载技能的仓库自身。其要点可以概括为——顺序依赖而非并行、QA 门禁永不跳过、失败回退有界、产物与运行笔记分离、按能力分配代理类型、发布必须过闸。对于任何计划长期维护一个技能/插件仓库的团队，这条来自 brooks-lint 的维护管道都提供了可直接复用的工程范式。若要在 agentic-awesome-skills-claude 中上手，可以从阅读 brooks-harness/SKILL.md 开始，再对照 brooks-lint/SKILL.md 理解被维护对象，以及 brooks-audit/SKILL.md 中同源技能的配置方式，形成完整的插件家族认知。
【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
