Agents 参考
上游 spec-first 当前生成 51 个 agents。Claude Code 与 Codex 都会获得 host-specific agent runtime copies；源码与运行时副本需要分开理解。
Agents 是 workflow 可调用的专家能力，不是一次任务必须全部启动的固定队列。Spec-First 的调度原则是：先判断当前研发阶段，再根据文档内容、diff 文件、风险域、技术栈、证据缺口和宿主能力选择最小必要专家。
资产边界
| 层级 | 位置 | 当前核验 |
|---|---|---|
| Source agents | 上游 agents/ | 51 个 agent profiles |
| Claude runtime agents | .claude/agents | 51 个 generated agent files |
| Codex runtime agents | .codex/agents | 51 个 generated agent files |
调度总图
text
Spec / Plan document
|
v
spec-doc-review
|
+-- always-on: coherence + feasibility
+-- conditional: product / design / security / scope / adversarial
Code diff / PR
|
v
spec-code-review
|
+-- always-on: correctness + testing + maintainability
+-- always-on: project-standards + agent-native + learnings
+-- conditional: security / performance / API / migration / reliability / CLI / stack
Research / planning / debugging / knowledge
|
v
workflow-selected research agents
|
+-- repo / git history / sessions / Slack / issues / framework docs / best practices
UI / deployment / data safety
|
v
specialist agents
|
+-- design sync / design iteration / deployment checklist / schema drift / data integrity按研发阶段理解 agents
| 阶段 | 常见 agent 能力 | 典型触发 |
|---|---|---|
| Codebase | repo research、git history、sessions、learnings | 新项目接入、计划前 research、调试历史问题、复用过往经验 |
| Graph | graph provider 通常不是 agent；agent 负责解释和补证据 | graph degraded 后需要 bounded direct reads 或历史解释 |
| Spec | spec-spec-flow-analyzer、product lens、design lens、security lens、web / issue research | 需求不清、用户流缺失、外部 prior art 或安全边界未确认 |
| Plan | coherence、feasibility、scope、architecture、framework docs | 计划要落地、技术方案需要审查、依赖或架构风险较高 |
| Tasks | doc-review personas 复核 task pack 是否忠于 source plan | task pack 可能扩 scope、依赖不清、同 wave 文件重叠 |
| Code | worker/explorer 子任务、stack specialists、design / performance / security specialists | 执行实现、调试、优化、UI 打磨 |
| Review | always-on reviewers + conditional reviewers | PR / diff 质量门 |
| Knowledge | session historian、Slack researcher、learnings researcher、related docs finder 类能力 | 复盘、知识沉淀、刷新 stale docs |
spec-doc-review 专家选择
spec-doc-review 审 requirements、plans 和 task packs。它总是先判断文档类型，再决定 reviewer 组合。
| Agent | 调用条件 | 能力 |
|---|---|---|
spec-coherence-reviewer | always-on | 查内部矛盾、术语漂移、结构问题和会让读者分歧的歧义 |
spec-feasibility-reviewer | always-on | 查技术方案是否能落地、依赖是否缺失、迁移或实现风险是否被低估 |
spec-product-lens-reviewer | 文档包含可挑战的产品判断、优先级、目标或方向选择 | 从产品领导视角挑战前提、机会成本、定位和目标-工作错配 |
spec-design-lens-reviewer | 文档涉及 UI、用户流、交互、响应式或视觉设计 | 查信息架构、交互状态、AI slop 风险和设计决策缺口 |
spec-security-lens-reviewer | 文档涉及 auth、API、PII、payments、tokens 或第三方信任边界 | 在计划层面查安全假设、数据暴露、API 攻击面和 threat model 缺口 |
spec-scope-guardian-reviewer | 文档有多优先级、大量需求、stretch goals 或复杂度疑点 | 守住 scope，对过度抽象、过早框架和目标不匹配提出异议 |
spec-adversarial-document-reviewer | 文档超过 5 个需求 / 单元、有架构决策、高风险域或新抽象 | 压测前提和边界，主动寻找未声明假设和决策漏洞 |
spec-code-review 专家选择
spec-code-review 按 diff 选择 reviewer。小 diff 也会有 always-on 审查；高风险文件会增加条件 reviewer。
Always-on reviewers
| Agent | 能力 |
|---|---|
spec-correctness-reviewer | 通过执行路径推演查逻辑错误、边界条件、状态 bug、错误传播和实现意图偏差 |
spec-testing-reviewer | 查测试覆盖缺口、弱断言、脆弱测试和遗漏的边缘场景 |
spec-maintainability-reviewer | 查过早抽象、耦合、复杂度、命名遮蔽、死代码和维护债务 |
spec-project-standards-reviewer | 审查 AGENTS.md / CLAUDE.md 项目规则、frontmatter、引用、命名和可移植性 |
spec-agent-native-reviewer | 检查新增能力是否 agent-accessible，避免只为人类 UI 暴露操作 |
spec-learnings-researcher | 搜索 docs/solutions/，把过往 bug、模式和团队学习带入当前 PR |
Conditional reviewers
| Agent | 触发条件 | 能力 |
|---|---|---|
spec-security-reviewer | auth、public endpoints、用户输入、权限、敏感数据 | 查可利用漏洞、输入验证、auth/authz 和权限绕过 |
spec-performance-reviewer | DB query、数据转换、缓存、I/O、循环重路径 | 查 runtime 性能、复杂度、扩展性和缓存误用 |
spec-api-contract-reviewer | API routes、request/response types、serializers、exported signatures | 查破坏性 contract changes、版本化和兼容性风险 |
spec-data-migrations-reviewer | migrations、schema changes、backfills、data transforms | 查迁移安全、数据完整性和生产数据风险 |
spec-reliability-reviewer | error handling、retry、timeout、health check、background jobs、async handlers | 查生产失败模式、恢复、重试、超时和错误可观测性 |
spec-adversarial-reviewer | diff 较大或触及 auth、payments、data mutations、external APIs | 主动构造失败场景压测实现 |
spec-cli-readiness-reviewer | CLI command definitions、argument parsing、handler behavior | 查 CLI 是否适合 autonomous agents 使用，而不只是人类可用 |
spec-previous-comments-reviewer | PR 已有 review comments 或 threads | 检查旧反馈是否已被当前 diff 正确处理 |
spec-dhh-rails-reviewer | Rails 架构、service objects、session/auth、Hotwire-vs-SPA 边界 | 用 DHH / Rails 约定审查架构选择 |
spec-kieran-rails-reviewer | Rails application code | 用严格 Rails 清晰度、命名、约定和可维护性标准审查 |
spec-kieran-python-reviewer | Python modules、endpoints、scripts、services | 查 Pythonic clarity、type hints 和维护性 |
spec-kieran-typescript-reviewer | TypeScript components、services、hooks、utilities、shared types | 查 type safety、清晰度和维护性 |
spec-julik-frontend-races-reviewer | Stimulus/Turbo、DOM events、timers、animations、async UI | 查 UI race conditions、DOM timing 和卡顿失败模式 |
spec-swift-ios-reviewer | Swift、SwiftUI、UIKit、entitlements、privacy manifests、Core Data、SPM、Xcode project | 查 Swift/iOS 状态、并发、内存、Core Data threading 和 accessibility |
Data / release safety specialists
| Agent | 调用条件 | 能力 |
|---|---|---|
spec-schema-drift-detector | PR 包含 DB migrations | 对照 migrations 查 schema.rb 是否包含无关漂移 |
spec-deployment-verification-agent | PR 涉及生产数据、迁移或高风险发布 | 生成 Go/No-Go checklist、SQL verification queries、rollback 和 monitoring plan |
spec-data-migration-expert | ID mapping、column rename、enum conversion、schema changes、backfill | 对真实生产迁移和数据转换做可行性与安全验证 |
spec-data-integrity-guardian | 数据模型、持久化代码、事务、约束、隐私 | 查数据约束、transaction boundaries、privacy compliance 和持久化安全 |
Research 与 context agents
这些 agents 通常服务 spec-ideate、spec-brainstorm、spec-plan、spec-debug、spec-compound 或复杂 review。
| Agent | 能力 |
|---|---|
spec-repo-research-analyst | 研究 repo 结构、文档、约定和实现模式，适合新代码库 onboarding 或计划前探索 |
spec-git-history-analyzer | 从 git history 追溯代码演化、贡献者和模式出现原因 |
spec-session-historian | 搜索 Claude Code / Codex 历史会话，提取过往尝试、失败路径和关键决策 |
spec-slack-researcher | 搜索 Slack 组织上下文，明确 workspace identity 并输出解释型 digest |
spec-web-researcher | 做迭代 web research，产出 prior art、市场信号、竞品模式和跨领域类比 |
spec-issue-intelligence-analyst | 分析 GitHub issues，提炼用户痛点、严重度和重复主题 |
spec-best-practices-researcher | 汇总外部最佳实践、社区约定和实现指导 |
spec-framework-docs-researcher | 获取框架、库、依赖的官方文档、版本约束和实现模式 |
spec-spec-flow-analyzer | 从用户视角分析 spec / plan / feature description 的流程完整性、遗漏路径和需求问题 |
Architecture、simplicity 与 pattern agents
| Agent | 能力 |
|---|---|
spec-architecture-strategist | 从架构视角审查代码变更、服务边界、结构重构和设计完整性 |
spec-pattern-recognition-specialist | 识别设计模式、反模式、命名约定、重复和代码库一致性问题 |
spec-code-simplicity-reviewer | 实现完成后的 final simplicity pass，查 YAGNI、可删复杂度和过度设计 |
spec-cli-agent-readiness-reviewer | 深度审查 CLI source、plans 或 specs 的 AI agent readiness，比条件 reviewer 更适合专项评估 |
spec-agent-native-reviewer | 同时属于 review always-on，也可专项检查 UI、agent tools 或 prompts 的 agent-native parity |
UI 与设计 agents
| Agent | 能力 |
|---|---|
spec-design-implementation-reviewer | 对照 Figma 与 live UI，指出 HTML/CSS/React 实现的视觉差异 |
spec-design-iterator | 通过多轮 screenshot -> analyze -> improve 循环迭代 UI 设计 |
spec-figma-design-sync | 检测并修复 web implementation 与 Figma design 的视觉差异 |
spec-design-lens-reviewer | 在计划 / 文档层面查设计决策缺口；属于 doc-review conditional persona |
安全、性能与专项审计 agents
| Agent | 能力 |
|---|---|
spec-security-sentinel | 做安全审计，覆盖漏洞、输入验证、auth/authz、hardcoded secrets 和 OWASP |
spec-security-reviewer | code-review 条件 persona，聚焦 diff 中可利用安全问题 |
spec-security-lens-reviewer | doc-review 条件 persona，聚焦计划层安全缺口 |
spec-performance-oracle | 分析算法复杂度、DB queries、内存、scalability 和性能瓶颈 |
spec-performance-reviewer | code-review 条件 persona，聚焦 diff 中实际性能风险 |
文档与发布支持 agents
| Agent | 能力 |
|---|---|
spec-ankane-readme-writer | 按 Ankane 风格为 Ruby gems 创建或更新 README |
spec-pr-comment-resolver | 评估并解决相关 PR review threads，实施修复并生成回复文本 |
spec-product-lens-reviewer | 同时属于 doc-review persona，也可在战略性计划评估中提供产品视角 |
全量 agent catalog
| Agent | 主要能力 |
|---|---|
spec-adversarial-document-reviewer | 压测复杂文档的前提、架构决策和未声明假设 |
spec-adversarial-reviewer | 为大型或高风险 diff 构造失败场景 |
spec-agent-native-reviewer | 检查用户可做的动作是否也能被 agent 完成 |
spec-ankane-readme-writer | 编写或更新 Ankane 风格 Ruby gem README |
spec-api-contract-reviewer | 审查 API contract、类型签名、序列化和版本兼容 |
spec-architecture-strategist | 从架构和设计完整性角度分析变更 |
spec-best-practices-researcher | 研究外部最佳实践和社区约定 |
spec-cli-agent-readiness-reviewer | 专项评估 CLI 对 autonomous agents 的友好度 |
spec-cli-readiness-reviewer | 在 code-review 中审查 CLI diff 的 agent readiness |
spec-code-simplicity-reviewer | 做实现后的简化和 YAGNI 检查 |
spec-coherence-reviewer | 查文档内部一致性、术语和结构问题 |
spec-correctness-reviewer | 查逻辑、边界、状态和错误传播问题 |
spec-data-integrity-guardian | 审查持久化数据、事务、约束和隐私安全 |
spec-data-migration-expert | 验证生产数据迁移、backfill 和转换方案 |
spec-data-migrations-reviewer | 在 code-review 中审查 migrations 和数据转换 |
spec-deployment-verification-agent | 生成发布验证、回滚和监控 checklist |
spec-design-implementation-reviewer | 对照 Figma 检查 UI 实现差异 |
spec-design-iterator | 用截图分析循环迭代 UI |
spec-design-lens-reviewer | 查计划 / 文档中的设计决策缺口 |
spec-dhh-rails-reviewer | 用 DHH/Rails 视角审查 Rails 架构选择 |
spec-feasibility-reviewer | 查计划是否可落地、依赖和迁移风险 |
spec-figma-design-sync | 同步 web implementation 与 Figma 视觉规格 |
spec-framework-docs-researcher | 获取框架 / 库官方文档和版本约束 |
spec-git-history-analyzer | 从 git history 解释模式和演进原因 |
spec-issue-intelligence-analyst | 分析 GitHub issues 的主题、痛点和趋势 |
spec-julik-frontend-races-reviewer | 查前端异步、DOM timing 和 UI race |
spec-kieran-python-reviewer | 审查 Python 清晰度、类型和维护性 |
spec-kieran-rails-reviewer | 审查 Rails 约定、清晰度和维护性 |
spec-kieran-typescript-reviewer | 审查 TypeScript 类型安全和清晰度 |
spec-learnings-researcher | 检索 docs/solutions/ 中相关团队学习 |
spec-maintainability-reviewer | 查复杂度、耦合、命名和维护债务 |
spec-pattern-recognition-specialist | 查模式、反模式、重复和代码库一致性 |
spec-performance-oracle | 深入分析性能瓶颈和扩展性 |
spec-performance-reviewer | 在 code-review 中审查性能风险 |
spec-pr-comment-resolver | 处理 PR review threads 并生成回复 |
spec-previous-comments-reviewer | 检查既有 PR comments 是否已处理 |
spec-product-lens-reviewer | 以产品战略视角挑战目标、优先级和机会成本 |
spec-project-standards-reviewer | 审查项目级 AGENTS/CLAUDE 规范遵守情况 |
spec-reliability-reviewer | 查错误处理、重试、超时、后台任务和失败模式 |
spec-repo-research-analyst | 研究 repo 结构、约定和实现模式 |
spec-schema-drift-detector | 对照 migrations 检测 schema drift |
spec-scope-guardian-reviewer | 守住计划 scope，反对不必要复杂度 |
spec-security-lens-reviewer | 在计划层审查安全假设和 threat model |
spec-security-reviewer | 在 code-review 中查 exploitable vulnerabilities |
spec-security-sentinel | 做广义安全审计和 OWASP 检查 |
spec-session-historian | 搜索历史 agent sessions 并总结相关上下文 |
spec-slack-researcher | 搜索 Slack 决策和组织上下文 |
spec-spec-flow-analyzer | 分析 spec / plan 的用户流完整性和缺口 |
spec-swift-ios-reviewer | 审查 Swift/iOS 状态、并发、Core Data 和 accessibility |
spec-testing-reviewer | 查测试覆盖、断言质量和遗漏场景 |
spec-web-researcher | 做外部 web research、竞品和 prior art 分析 |
旧数字说明
旧官网曾写过 47 或 57 个 agents。这些数字不再作为当前事实使用；当前页面以上游 source agent scan 与 Codex runtime generation 交叉核验的 51 个 agents 为准。
阅读下一步
- Skills 参考：42 个 source skill 的能力分类与详情入口
- Code Review 指南：always-on 与条件 reviewer 如何调度
- 工作流总览：agents 在研发链路中的位置
spec-code-review契约：6 类 always-on personas 的具体职责