第 5 章 · 02 八个示例代理

第 5 章 · 02 八个示例代理

本节摘要:原书八个生产级子代理,按角色分三类。审查类:code-reviewer(先 git diff 再按安全→性能→质量→测试→设计模式审查,Severity/Category/Location/Issue/Fix/Impact 输出,含 N+1 查询审查示例)、clean-code-reviewer(Clean Code 执行者:函数 <20 行/≤3 参数/无 flag 参数,严重级别量化,金句"代码被阅读的次数是写作的 10 倍")、secure-reviewer(只读最小权限范例:Read+Grep,明确禁止执行代码/修改文件)。实现类:implementation-agent(端到端+完成清单)、debugger(根因分析五步)、test-engineer(覆盖率 80%/关键路径 100%)。专用类:data-scientist(唯一指定 sonnet)、documentation-writer(按实际代码验证文档)。共同规律:工具集=职责边界。

学习目标

阅读完本节,你应当能够:

1. 说出三类代理的划分与各自代表。
2. 复述 secure-reviewer 的最小权限设计及其理由。
3. 复述 debugger 的根因分析五步与 test-engineer 的覆盖率标准。
4. 总结"工具集=职责边界"的规律。

一、审查类

code-reviewer:工具 Read/Grep/Glob/Bash,模型 inherit。流程:先 git diff;审查优先级:安全→性能→质量→测试覆盖→设计模式;输出按 Severity/Category/Location/Issue/Fix/Impact 组织,Critical→Warnings→Suggestions。示例:N+1 查询 → High/Performance/src/user-service.ts:45 → JOIN 或批量查询。

clean-code-reviewer:Robert C. Martin Clean Code 原则执行者。检查命名(意图/可发音/可搜索)、函数 <20 行/≤3 参数/无 flag 参数/不返回 null、注释(删除注释代码)、结构(避免上帝类)、SOLID、DRY/KISS/YAGNI、错误处理。严重级别量化:Critical=函数>50 行/≥5 参数/≥4 层嵌套;输出含 Summary 行 Files: n | Critical: n | ...。核心理念:"代码被阅读的次数是写作的 10 倍"。

secure-reviewer:工具仅 Read, Grep(最小权限,只读),明确"不能执行代码、不能修改文件、不能运行测试"——确保审查过程不破坏任何东西(最小权限设计范例)。五类重点:认证/授权/数据暴露/注入(SQL、命令、XSS、LDAP)/配置问题;附 grep 搜索模式(硬编码密钥、SQL 注入、exec(/os.system)。

二、实现类

implementation-agent:工具全量(Read/Write/Edit/Bash/Grep/Glob)。流程:理解需求→分析现有模式→制定方案→逐步实现→边做边测→清理重构;输出 Files Created/Modified、Tests Added、Build Status、Notes;完成清单:规范/测试/构建/lint/边界/错误处理。

debugger:工具 Read/Edit/Bash/Grep/Glob。根因分析五步:分析错误与堆栈→检查最近变更(git diff)→提出并测试假设→隔离故障(最小复现)→最小修复+回归检查;输出 Error/Root Cause/Evidence/Fix/Testing/Prevention;常用命令 git diff HEAD~3、grep -r "error" --include="*.log"。

test-engineer:工具 Read/Write/Bash/Grep。策略:单元→集成→E2E→边界→错误;要求:用项目现有框架、setup/teardown、mock 外部依赖;覆盖率:最低 80%,关键路径(认证/支付/数据处理)100%;输出 File/Tests/Coverage/Critical Paths;附 Jest describe/it 结构示例。

三、专用类

data-scientist:工具 Bash/Read/Write,模型 sonnet(八个代理中唯一不 inherit 的——数据分析重推理)。SQL/BigQuery 专家(bq query --use_legacy_sql=false);分析类型:探索性/统计/报告;输出 Objective/Query/Results/Insights/Recommendations;附月活跃用户趋势 SQL 示例。

documentation-writer:工具 Read/Write/Grep。文档类型:API/用户指南/架构/Changelog/注释改进;标准:清晰/示例/完整/结构/准确(按实际代码验证);输出 Type/File/Sections/Examples;附 GET /api/users/:id 完整文档示例。

四、共同规律

八个代理共同示范一条设计规律:工具集 = 职责边界——审查者只读(甚至只读+Grep 子集)、实现者全量、分析者带执行能力。权限的"够用就好"既降低风险,也让代理的注意力更聚焦。

小结

审查类示范"输出结构化报告",实现类示范"流程+完成清单",专用类示范"领域专家+定制模型"。写自己的代理时,先定角色(审查/实现/分析),再按角色配工具,最后把专家标准写进 prompt。下一节是设计方法论:三原则与上下文管理。