Agents 配置

概述

Agents 定义了专门的 AI 代理角色，用于执行特定类型的任务。Superpowers 使用代理系统来实现专业化的代码审查、实现等能力。

内置代理

code-reviewer

代码审查代理，用于审查已完成的项目步骤是否符合计划和编码标准。

触发场景：

• 完成主要项目步骤后
• 完成重要功能实现后
• 需要验证代码是否符合计划时

职责：

1. 计划对齐分析

   • 比较实现与原始计划文档
   • 识别偏差并评估是否合理
   • 验证所有计划功能是否实现

2. 代码质量评估

   • 检查代码规范和模式遵循
   • 评估错误处理和类型安全
   • 检查测试覆盖和质量

3. 架构和设计审查

   • 确保遵循 SOLID 原则
   • 检查关注点分离和松耦合
   • 评估可扩展性

4. 文档和标准

   • 验证注释和文档完整性
   • 检查编码规范遵循

5. 问题分类

   • Critical（严重）：必须修复
   • Important（重要）：应该修复
   • Suggestions（建议）：可选改进

代理文件格式

代理使用 Markdown 文件定义，包含 YAML frontmatter：

---
name: agent-name
description: |
  Use this agent when [trigger condition]. Examples:
  <example>Context: ... user: "..." assistant: "..."</example>
model: inherit
---

You are a [role description].

When [performing task], you will:

1. **[Task Category 1]**:
   - [Specific action]
   - [Specific action]

2. **[Task Category 2]**:
   - [Specific action]
...

Frontmatter 字段

字段	必需	说明
name	是	代理名称，用于引用
description	是	触发条件和示例，帮助 AI 决定何时使用
model	否	使用的模型，默认 inherit 继承父会话模型

创建自定义代理

步骤 1：创建代理文件

在 agents/ 目录下创建 my-agent.md：

---
name: security-auditor
description: |
  Use this agent when reviewing code for security vulnerabilities. Examples:
  <example>Context: User is about to deploy a new API endpoint.
  user: "I've added a new endpoint to handle file uploads"
  assistant: "Let me use the security-auditor agent to review this for potential vulnerabilities before deployment"</example>
model: inherit
---

You are a Security Auditor specializing in identifying vulnerabilities...

When auditing code, you will:

1. **Input Validation Review**:
   - Check for proper sanitization
   - Identify injection vulnerabilities
...

步骤 2：在技能中引用代理

在技能的 SKILL.md 中引用代理：

## 流程

1. 完成实现
2. 使用 `security-auditor` 代理进行安全审查
3. 修复发现的问题

配置文件位置

平台	内置代理位置	自定义代理位置
Claude Code	~/.claude/plugins/superpowers/agents/	~/.claude/agents/
Cursor	~/.cursor/plugins/superpowers/agents/	~/.cursor/agents/
Codex	~/.codex/superpowers/agents/	~/.agents/agents/
OpenCode	~/.config/opencode/superpowers/agents/	~/.config/opencode/agents/

使用代理

代理通常由技能自动调用，无需手动触发。例如：

• requesting-code-review 技能会调用 code-reviewer 代理
• subagent-driven-development 会使用代理进行代码审查

最佳实践

角色定义要具体

代理的角色描述应该清晰明确：

You are a Senior Code Reviewer with expertise in software architecture,
design patterns, and best practices.

提供触发示例

在 description 中包含具体的使用示例，帮助 AI 正确判断何时使用代理：

description: |
  Use this agent when a major project step has been completed.
  Examples:
  <example>Context: ... user: "I've finished implementing..." assistant: "..."</example>

避免重复职责

每个代理应有独特的职责范围，避免多个代理做同样的事情。

结构化输出

代理的输出应该是结构化的，便于后续处理：

Your output should be structured:
- **Critical Issues**: ...
- **Important Issues**: ...
- **Suggestions**: ...