normalize-agent-for-claude

每项改写决策都必须以 Claude Code 的 Agent 运行时为依据。

不可妥协的规则：

1. 在规划或改写前，先阅读 references/claude-agent-runtime.md。
2. 默认使用 --mode plan，除非用户明确要求立即改写。
3. 保持正文精简，因为完整的 Markdown 正文会成为 Agent 系统提示词。
4. 添加更多正文前，先使用 frontmatter 设置运行时控制项。
5. 除非大型技能已精简且有充分理由，否则绝不要在 Agent frontmatter 中预加载。
6. 绝不要向 Agent 添加仅适用于技能的 frontmatter。allowed-tools、argument-hint、arguments、when_to_use、disable-model-invocation、user-invocable、context、agent、shell 和 paths 属于技能，而非 Agent。

为 Claude 规范化 Agent

输入

• $target：Agent 目录或 AGENT.md 的直接路径
• $mode：可选。plan 或 rewrite。默认值：plan

目标

生成经过 Claude Code 优化的 Agent，使其角色身份和约束清晰，合理使用 frontmatter，并避免将本应放在技能或共享规则中的大量流程内容塞进提示词，浪费提示词预算。

步骤 1：解析目标

1. 接受 Agent 目录或 AGENT.md 的直接路径。
2. 规范化为 Agent 根目录，并确认 AGENT.md 存在。
3. 确定模式：
   • --mode rewrite 表示先规划，再在同一次运行中改写
   • 未指定模式时使用 plan
4. 检查当前 Agent：
   • AGENT.md 的行数
   • 现有的 frontmatter 字段
   • 正文的章节结构
   • 明显重复的全局策略或庞大的知识目录

成功标准：明确目标 Agent、目标模式以及当前提示词结构的风险。

步骤 2：加载 Claude Code Agent 运行时参考

在提出任何建议前，完整阅读 references/claude-agent-runtime.md。

从参考文档中提取以下约束：

• Agent 的 description 会成为 whenToUse
• 整个 Markdown 正文会成为系统提示词
• 与大多数自定义 Agent 相比，Claude 支持更丰富的 Agent frontmatter
• Agent 的 skills: 会预加载完整的技能内容
• 工具允许和拒绝列表会在运行时强制执行
• 仓库范围的项目规则已有单独的指令层级
• Agent 改写只能使用 Agent 原生 frontmatter，不能使用技能原生标头

如果此仓库包含 claude-code-source/，请使用参考文档中列出的确切源文件，核实异常的 frontmatter 或隔离决策。

成功标准：每项计划中的更改都有具体的 Claude 运行时行为作为依据。

步骤 3：根据 Claude 的运行时审查当前 Agent

使用以下检查清单评估目标 Agent：

1. 身份与流程
   • 哪些内容属于真实的角色身份？（角色定义、专业知识要点、决策启发式、领域知识、特质）
   • 哪些内容实际上属于工作流，应该放入技能中？（分步流程、shell 命令、模板、检查清单）
   • 角色专属的专业知识列表和决策启发式属于 IDENTITY——应保留在正文中。只有流程才应移入技能或参考资料。
2. 提示词体量
   • 哪些较大的章节之所以存在，只是因为当前 Agent 在弥补技能或共享规则的缺失？
3. Frontmatter 优化机会
   • disallowedTools、skills、initialPrompt、hooks、permissionMode、maxTurns、background、memory 或 isolation 是否能改善运行时行为？
   • 是否有必须删除或明确避免使用的、仅适用于技能的标头？
4. 工具范围
   • 工具列表是否超出了该角色的实际需求？
5. 技能预加载风险
   • 如果在 frontmatter 中添加技能，是否会因技能过大而导致提示词膨胀？
6. 指令重复
   • 是否重复写入了项目范围的规则，而 Claude 已通过单独加载项目记忆获取了这些规则？

对每个问题进行分类：

• PROMPT：正文过长或包含了不适合的内容
• RUNTIME：Claude frontmatter 缺失或使用不当
• TOOLS：工具暴露范围过广或定义过于模糊
• DUPLICATION：Agent 正文中重复了项目策略
• EXTRACTION：内容应移入技能或参考资料

成功标准：对哪些内容应保留、迁移或精简，给出有依据且具体的说明。

步骤 4：编写每个 Agent 的 DAG 计划

创建以下两份产物：

• .ulpi/plans/agents/<agent-name>-normalize-for-claude.md
• .ulpi/plans/agents/<agent-name>-normalize-for-claude.json

计划必须包含：

1. 当前状态
   • 行数
   • 当前 frontmatter
   • 过大的章节
   • 重复的全局策略
2. Claude 运行时审查结果
   • 将每项发现映射到 references/claude-agent-runtime.md 中的源引用
3. 目标状态
   • 最终 frontmatter 结构
   • 正文中要保留、删除或迁移的章节
   • Agent 应改为依赖的技能或参考资料
4. DAG 任务
   • 重写 frontmatter
   • 精简提示词正文
   • 将流程提取到技能或参考资料中
   • 收紧工具范围
   • 验证
5. 护栏
   • 必须保留的身份内容
   • 必须移出的内容
   • 不得预加载的内容
6. 验证
   • 用于确认最终 Agent 结构健全的具体检查

每项 DAG 任务应包含：

• id
• title
• rationale
• filesToModify
• filesToCreate
• dependencies
• validation

成功标准：Markdown 计划与 JSON 计划描述相同的安全工作顺序。

步骤 5：仅在需要时重写

如果模式为 plan，写完 DAG 文件后即停止。

如果模式为 rewrite：

1. 首先重写 frontmatter。
2. 将正文精简为：
   • 角色与专长（具体领域知识和能力声明）
   • 范围
   • 决策启发式（如何在不同方案间做出选择）
   • 失败边界
   • 输出约定
   • 简要的技能交接指导
3. 将重复的流程和大型示例移出 Agent。保留角色专长要点和决策启发式——它们体现的是身份，而非流程。
4. 仅在能够实质性改变运行时行为时，才添加 Claude 原生 frontmatter。
5. 保持角色专属，而非泛泛而谈。

优先考虑的重写结果：

• Agent 的 description 更明确地说明何时使用（whenToUse）
• 正文精简许多，并更聚焦于身份
• 在适当情况下使用 disallowedTools，并缩减 tools 的范围
• 谨慎使用 skills:，且仅用于已经精简的技能
• 从正文中移除重复的项目规则
• 重写后的 Agent 中不引入仅适用于技能的标题

成功标准：重写后的 Agent 更精简、更准确，并且与 Claude 的运行时模型更加契合。

步骤 6：验证结果

规划或重写后：

1. 重新阅读最终的 AGENT.md。
2. 确认 frontmatter 反映了真实的运行时决策。
3. 确认正文主要包含身份、范围、启发式和边界。
4. 确认没有引入仅适用于技能的标题。
5. 确认大型流程内容已移除或明确移出。
6. 确认摘要指出了推动主要变更的 Claude 源锚点。

成功标准：输出可立即使用，无需再次解读结构调整的原因。

输出约定

始终报告：

1. Agent: 目标路径和规范化后的根目录
2. Mode: plan 或 rewrite
3. Top runtime issues: 最重要的 Claude 不匹配项
4. Artifacts: 确切的计划或重写文件路径
5. Guardrails applied: 3 至 5 条与 Claude 运行时行为相关的要点

如果使用了重写模式，还需报告：

• 移除或移出的章节
• 添加、移除或有意省略的 frontmatter 字段