repair-agent

Agent 修复

依据黄金标准审查并改进现有的 Claude Code Agent。与从零生成 Agent 的 create-agent 不同，此技能会诊断违规项并识别缺失项——哪些内容有问题、缺少什么，以及哪些方面可以提升质量。输出是一份结构化的改进计划，涵盖 Agent 设计的所有维度。

阶段 1：加载 Agent

$ARGUMENTS 中的 Agent 文件会以内联方式加载：

@$ARGUMENTS

注意 $ARGUMENTS 中的目录，以确认文件位于 agents/（而非 skills/）中。找出上方 frontmatter 中列出的任何 skills: 预加载项。

如果文件是 SKILL.md 或位于 skills/ 目录中，请拒绝处理，并告知用户改用 repair-skill。如果路径缺失或不明确，请使用 AskUserQuestion 确认后再继续。

在阶段 2 前加载以下参考文件：

1. ${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/references/agent-anatomy.md——系统提示词结构、语气规范、大小不变量、命名、skills: 预加载模式和差距分析清单的黄金标准。维度 3、5、6 和 7 必须使用此文件。
2. ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md——完整的 frontmatter 字段目录、有效值、工具选择框架、颜色语义和执行修饰符。维度 1 和 2 必须使用此文件。

继续阶段 2 的条件：确认 Agent 文件属于处理范围，且已加载参考文件。

阶段 2：审查

分别检查每个维度。针对每项发现，记录：维度代码、存在的问题或缺失的内容、违反的原则或未达到的黄金标准，以及需要进行的具体更改。评估完全部 7 个维度后，继续阶段 3。

发现类型：

• 违规项——现有内容与规则相矛盾
• 缺失项——缺少的内容；补充后可使 Agent 更符合黄金标准
• 改进项——当前有效，但仍可显著优化

严重程度：

• 严重——导致 Agent 无法触发，或每次调用时都会出现故障
• 主要——降低触发准确性、系统提示词可靠性或自主运行安全性
• 次要——润色；Agent 可以工作，但仍有提升空间

---

维度 1 — 描述质量

路由模型会读取描述，以决定何时启动此 Agent。它是主要的触发机制，并且始终处于上下文中。审查违规项和缺失项。

违规项：

• 措辞：是否以 “Use this agent when...” 开头？如果不正确，严重。
• 描述冗长：描述应为简洁的 > 折叠标量，长度为 50–70 个 token。不要使用 <example> 块——它们会浪费上下文，且无助于路由。如果包含示例或描述超过约 80 个 token，则为主要问题。
• 标量类型：应使用 >（折叠标量）。如果使用 | 且没有 XML 块，则为次要问题。
• 缺少主动触发提示：对于会在事件发生后触发的 Agent，描述中是否包含 “Recommended PROACTIVELY after...” 如果有主动触发意图，却没有此提示，则为次要问题。

缺失项：

• 负向触发条件：如果存在职责范围重叠的相邻 Agent，描述是否说明哪些情况下不应触发？如果存在相邻 Agent，却没有进行区分，则为次要问题。

---

维度 2 — Frontmatter 修饰符

完整的字段目录、工具选择框架和颜色语义请参阅 agent-frontmatter.md。默认值适用时，省略字段并非错误——请审查是否存在不匹配项（违规）以及可提升 Agent 能力但缺失的配置（缺口）。

违规：

• 对于不需要完整 Shell 访问权限的 Agent，tools 是否包含未限定范围的 Bash？Agent 会在没有人工介入的情况下自主运行——不受限制的 Bash 是影响范围最大的授权。重大。
• 对于 sonnet 能处理的任务，是否设置了 model: opus？成本会随着每次启动直接增加。重大。
• 是否设置了 isolation: worktree，但 Agent 并不需要修改 git 状态？不必要的隔离会增加开销。轻微。
• disallowedTools 是否禁用了系统提示词要求使用的工具？严重。

缺口：

• 是否缺少 color？在 UI 中设置视觉标识有助于用户在多 Agent 工作流中追踪当前活动的 Agent。轻微。
• 对于只读分析 Agent，是否缺少 tools？最小权限原则要求为自主运行的 Agent 显式设置允许列表——省略该字段会授予完整访问权限，而有限访问权限本已足够。对仅用于分析的 Agent 来说属于重大缺口。
• 对于完成时间可预测的任务，是否缺少 maxTurns？无界 Agent 可能会在面对含糊输入时陷入循环。对有明确边界的任务来说属于轻微缺口。
• 对于有领域专属知识需求的 Agent，是否缺少 skills？将领域参考资料直接嵌入系统提示词会增加每次启动的负担；skills: 可延迟加载这些资料。如果系统提示词嵌入的参考资料超过 300 行，则属于重大缺口。
• 对于会修改工作树中文件的 Agent，是否缺少 isolation: worktree？没有隔离时，修改会在运行期间立即生效且不可撤销。重大。
• 对于能从跨会话学习中受益的 Agent，是否缺少 memory？审查代码、审核模式或积累项目知识的 Agent 应使用持久化记忆（建议默认设为 project）。如果设置了 memory，系统提示词中是否包含记忆维护说明？没有这些说明，Agent 就不会主动更新其知识库。如果 Agent 的领域涉及模式积累，则属于重大缺口。
• 对于注重成本或复杂度各异的 Agent，是否缺少 effort？快速分类任务适合使用 effort: low；深度推理任务则适合使用 effort: high。轻微。
• 对于设计为通过 --agent 使用的会话模式 Agent，是否缺少 initialPrompt？没有该字段，Agent 会等待用户输入，而不会自行启动。如适用，则属于轻微缺口。

---

维度 3 — 系统提示词的语气

Agent 文件的 Markdown 正文就是其系统提示词。语气、角色设定和结构惯例决定了 Agent 的行为是专家型还是通用助手型。 关于语气惯例和黄金标准结构，请参阅 agent-anatomy.md。

违规项：

• 第一人称措辞： 正文是否包含 “I will”、“I'll”、“I am” 或任何第一人称表达？严重——系统提示词是对 Agent 发出的指令；第一人称读起来像是 Agent 在叙述自己的计划，而不是遵循指令。第二人称（“You will analyze...”）和流程步骤中的直接祈使句（“Analyze...”）都是正确的惯例——只有第一人称会破坏约定。
• 第三人称自我描述： 正文是否以第三人称提及 Agent（“This agent will analyze...”、“The agent should...”）？重大——正文必须直接对 Agent 发出指令，而不是从外部描述它。
• 缺少角色设定： 第一句是否确立了角色和领域？没有这句话，Agent 就没有能影响后续决策的专家身份。重大。
• 缺少编号流程步骤： 缺乏结构的文字指令会导致每次调用的行为不一致。缺乏结构时属重大问题。
• 缺少输出格式： 是否有 Output Format 章节？调用方（无论是人还是编排技能）都需要可预测的结构来使用结果。缺少时属重大问题。

不足之处：

• 缺少边界情况： 预先定义处理方式可避免任务中途失败，减少重试。常见情况：未提供输入、输入模糊、缺少目标、结果为空。轻微。
• 判断步骤缺少标准： 例如“分析情况”或“评估质量”等步骤，未明确说明应考虑哪些因素，以及怎样才算达到良好结果。 每个未覆盖的判断步骤都属重大问题。

---

维度 4 — Agentic 与确定性任务的划分

审计此维度前，先加载 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md。 相同的五种信号模式也适用于 Agent。

Agent 会结合大模型引导的推理（Agentic）和确定性操作。两者的划分应经过审慎设计——请参阅 agent-anatomy.md 中的自由度表。

违规项：

• 将确定性代码内嵌： 每次调用都会以相同方式重新生成的代码块应放在 scripts/ 中，而不是系统提示词中。重大。
• 脚本引用含糊： 例如“必要时运行验证脚本”——没有路径、触发条件或输出解读说明。轻微。

不足之处——对每个流程步骤应用五种信号模式：

• 信号 1（重复生成）： 结构相同、参数不同 → 使用脚本。重大。
• 信号 2（工具选择不明确）： 易出错的多工具顺序 → 将该流程编写为脚本。重大。
• 信号 3（严格约定）： 此步骤是否可以编写 --help？→ 可考虑 CLI。轻微。
• 信号 4（双重用途）： 在 Agent 之外也有用 → 设计为规范的 CLI。轻微。
• 信号 5（一致性至关重要）： 必须生成完全相同的输出 → 使用脚本，而非大模型。重大。

---

维度 5 — 系统提示词效率

Agent 正文中的每一行都会在每次启动 Agent 时加载到上下文中。领域参考数据和查找表应放在 skills: 预加载中，而非直接嵌入正文。请参阅 agent-anatomy.md 中的大小不变量，以校准严重程度。

违规项：

• 含糊措辞：“You might want to consider”“generally speaking”“you could try”。请改用直接的祈使句。每处为轻微问题。
• **正文中的路由指引：**任何说明何时触发 Agent 的章节都应放在 description 字段中。正文只会在触发后加载——其中的路由指引不会影响触发决策，却会在每次启动时占用上下文。严重问题。
• **嵌入超过 100 行的领域参考内容：**仅特定步骤需要的查找表、选项目录和字段定义会增加每次调用的开销。请改用 skills: 预加载。严重问题。
• **系统提示词超过约 400 行：**这表明正文嵌入了本应放在 skills: 预加载中的内容。严重问题。

缺口：

• **skills: 能否缩短系统提示词？**找出仅在特定子任务中需要的章节。如果系统提示词超过 300 行且有可提取的内容，则为严重问题。

---

维度 6 — 流程完整性

完整的 Agent 流程应按顺序执行，包含明确步骤，并定义每一步达到什么状态才算“完成”。审核流程是否存在缺陷，以及是否缺少有助于完善流程的结构。

违规项：

• **没有编号步骤：**仅用散文描述流程，没有标注步骤编号——Agent 无法跟踪进度，也不知道当前处于哪一步。严重问题。
• **步骤没有退出条件：**多步骤流程需要为每一步明确完成标准。若缺少这些标准，Agent 可能会循环执行或过早跳过步骤。缺少时为严重问题。
• **步骤缺乏明确内容：**阶段只描述意图，却没有说明操作或评估标准。每个未明确的步骤均为严重问题。
• **未说明如何处理输入：**如果输入缺失、含糊或格式错误，Agent 应如何处理？未说明时为轻微问题。

缺口：

• **没有输出格式章节：**调用方无法可靠地使用隐含的输出结构。如果 Agent 返回结构化数据，则为严重问题。
• **没有验证清单：**在流程结束时进行自检，可以发现散文式指令可能遗漏的错误。轻微问题。

---

维度 7 — 架构完整性

Agent 通常是单个文件，但其生态还包括 skills: 预加载和可选的配套脚本。本维度用于检查已声明的结构是否满足需求。

对于每个缺失的元素，请参阅 agent-anatomy.md 中的缺口分析清单。

违规项：

• **在 frontmatter 中列出 skills:，但流程中未引用：**无用的预加载会在每次启动时增加上下文开销，却没有实际用途。轻微问题。
• **命名不符合规范：**使用通用词语（helper、assistant、agent）、下划线、超过 50 个字符，或以连字符开头／结尾。轻微问题。

缺口：

• **领域密集型 Agent 没有 skills: 预加载：**系统提示词中嵌入了大量可外置的参考目录。如果正文超过 300 行，则为严重问题。
• **一致性要求关键步骤没有配套脚本：**流程中包含在输入相同时必须生成相同输出的步骤。严重问题。
• **未设置 color：**在多 Agent UI 环境中缺少视觉标识。轻微问题。
• **需要积累模式的 Agent 没有 memory：**Agent 会审查代码、审核质量或积累项目知识，却没有配置持久记忆。如果 Agent 的价值会随着上下文积累而提升，则为严重问题。

---

阶段 3：改进报告

将发现整理成结构化报告。将违规项与缺漏项分开列出。完整的报告格式示例和修复前后会话示例，请参见 ${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/examples/sample-repair.md。

AGENT IMPROVEMENT REPORT: <agent-name>
System prompt: [N] lines | Description: [N] tokens | Tools: [listed / unrestricted]

VIOLATIONS
──────────
CRITICAL
  [D1] Description does not start with "Use this agent when..." — routing model cannot
       match. Fix: rewrite opening as "Use this agent when [trigger conditions]."

MAJOR
  [D3] Body uses first-person throughout ("I will analyze...") — system prompt must be
       second-person because it is an address to the agent, not a narration of intent.
       Fix: rewrite as "Analyze the input and identify..." throughout.
  [D2] `tools` omitted for a read-only analysis agent — omission grants full tool access;
       least-privilege for autonomous agents requires an explicit allowlist.
       Fix: add tools block sequence (Read, Grep, Glob)

MINOR
  [D2] `color` not set — no visual identity in multi-agent UI.
       Fix: add color: blue (analysis/review semantic).

GAPS (what would improve this agent)
─────────────────────────────────────
MAJOR
  [D7] System prompt is 380 lines of embedded domain reference. Extract to a skill file
       and preload via `skills:` frontmatter to reduce per-spawn context cost.

MINOR
  [D6] No edge cases section — what happens when the agent receives no input?
       Improvement: add "Edge Cases: No input provided — ask the user to share the target."

先按严重程度对违规项分组，再按严重程度对缺漏项分组。对于每一项，请说明：维度代码、问题或缺失内容、未达到的原则，以及确切的修复方法。

询问：“要应用所有严重和主要问题吗？还是选择特定问题？”

用户说明要应用哪些项目后，继续执行阶段 4。

---

阶段 4：应用改进

按以下顺序应用已确认的项目：严重违规项 → 主要违规项 → 主要缺漏项 → 轻微违规项 → 轻微缺漏项。

对于每一项：

• 说明要修改的内容及原因（引用原则，而不只是说“你要求的”）
• 执行编辑
• 确认修改与周围内容一致

说明你的选择

应用完成后：

• 修改了什么以及原因 — 引用原则：“将正文改写为第二人称，因为系统提示词是对 Agent 的指示；第一人称会破坏遵循指令的约定”
• 添加了什么以及原因 — “添加了 tools 块序列（Read、Grep、Glob），因为这是一个只读 Agent，而自主执行的最小权限原则要求明确列出允许使用的工具”
• 哪些内容保持不变以及原因 — “未设置 maxTurns — 任务时限没有明确上限”
• 用户还需处理的事项 — 需要领域知识才能填写的内容

应用所有已确认的项目、说明修改情况并通过验证清单后，阶段 4 即完成。

---

验证

应用所有改进后：

1. 运行结构验证器：

   python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/validate_agent.py \
     <agent-file> --output json
   

   退出码为 0 = 结构无误。退出码为 1 = 解析 errors 数组；在交付最终结果前，报告每个条目的 field、message 和 severity。

2. 加载 ${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/references/quality-checklist.md， 先执行质量标准检查，再逐项运行检查清单。在交付最终结果前，报告所有未通过的项目。