用途
Agent MD Refactor 用于重构臃肿的智能体指令文件(如 AGENTS.md、CLAUDE.md、COPILOT.md 等),使其遵循渐进式披露原则——把必需信息保留在根文件,其余内容组织为带链接的分类文件。
典型触发场景包括:
- 「重构我的 AGENTS.md」/「重构我的 CLAUDE.md」
- 「拆分我的智能体指令」
- 「整理我的 CLAUDE.md 文件」
- 「我的 AGENTS.md 太长了」
- 「为我的指令做渐进式披露」
- 「清理我的智能体配置」
主要能力(五阶段流程)
资料将流程划分为五个阶段,并以表格给出阶段、动作与输出:
- 分析(Analyze):查找矛盾,输出待解决的冲突清单。
- 提取(Extract):识别核心要点,输出根文件所需的核心指令。
- 归类(Categorize):将其余指令分组,输出逻辑类别。
- 结构化(Structure):创建文件层级,输出根文件加链接文件。
- 修剪(Prune):标记待删除项,输出冗余/含糊的指令。
阶段 1:发现矛盾
识别彼此冲突的指令,查找的方向包括:矛盾风格准则(如「使用分号」对比「不使用分号」)、冲突的工作流指令、不兼容的工具偏好、互斥的模式。对每个矛盾给出:指令 A、指令 B、以及应优先采用哪一个或是否都设为条件式的问题,并在继续之前请用户解决。
阶段 2:识别核心要点
只提取属于根智能体文件的内容,根文件应保持最小化,仅包含适用于每一项任务的信息。
应保留在根文件中的内容:项目描述(一句话,如「一个用于分析的可视化 React 仪表盘」)、包管理器(仅在非 npm 时,如「使用 pnpm」)、非标准命令(自定义的构建/测试/类型检查命令)、关键覆盖项(必须覆盖默认值的内容)、通用规则(适用于 100% 任务的内容)。
不应保留(应移到链接文件):语言特定约定、测试准则、代码风格细节、框架模式、文档标准、Git 工作流细节。
阶段 3:对其余内容分组
将剩余指令组织为逻辑类别。资料给出的常见类别包括:typescript.md(TS 约定、类型模式、严格模式规则)、testing.md(测试框架、覆盖率、mock 模式)、code-style.md(格式、命名、注释、结构)、git-workflow.md(提交、分支、PR、评审)、architecture.md(模式、文件夹结构、依赖)、api-design.md(REST/GraphQL 约定、错误处理)、security.md(认证模式、输入校验、密钥)、performance.md(优化规则、缓存、懒加载)。
分组规则:每个文件对其主题自包含;目标为 3 到 8 个文件(既不过于细碎也不过于宽泛);文件命名清晰,为 {topic}.md;只包含可操作的指令。
阶段 4:创建文件结构
资料给出的输出结构示例:项目根目录下放置最小化的根文件(CLAUDE.md 或 AGENTS.md),并在 .claude/(或 docs/agent-instructions/)目录下放置各分类文件。
根文件模板包含:项目名、一句话项目描述、快速参考(包管理器、构建、测试、类型检查命令)、详细指令(指向各分类文件的链接)。
每个链接文件模板包含:主题名、概述(说明这些准则适用场景的简要背景)、规则(分组的、具体可操作的指令)、示例(正确模式与应避免模式的代码示例)。
阶段 5:标记删除
识别应完全移除的指令。符合以下标准的应删除:冗余(如在 .ts 项目中写「使用 TypeScript」)、过于含糊(如「写干净的代码」)、过于显然(如「不要引入 bug」)、默认行为(如「使用描述性变量名」)、过时(引用已弃用 API)。输出格式为一张表,列出指令与删除原因。
执行清单
- 阶段 1:所有矛盾已识别并解决
- 阶段 2:根文件只包含核心要点
- 阶段 3:其余所有指令已归类
- 阶段 4:文件结构已创建且链接正确
- 阶段 5:冗余/含糊指令已移除
- 验证:每个链接文件自包含
- 验证:根文件少于 50 行
- 验证:所有链接有效
反模式
资料列出的反模式及建议替代:把所有内容留在根文件(臃肿、难维护,应拆分为链接文件);类别过多(碎片化,应合并相关主题);含糊指令(浪费 token 且无价值,应具体化或删除);重复默认值(智能体已知,应仅在需要时覆盖);过深嵌套(难以浏览,应用带链接的扁平结构)。
使用方式与示例
资料通过「之前(臃肿的根文件)」与「之后(渐进式披露)」的对比展示效果:之前是一个包含代码风格、测试、TypeScript 等数百行内容的单体 CLAUDE.md;之后是仅含项目描述、命令(pnpm dev、pnpm test、pnpm build)以及指向 code-style.md、testing.md、typescript.md 的链接的精简根文件。
验证要求
重构后需验证:根文件最小化(少于 50 行,只含通用信息);链接有效(所有引用文件存在);无矛盾(指令一致);内容可操作(每条指令都具体);覆盖完整(除被标记删除者外无指令丢失);文件自包含(每个链接文件可独立阅读)。
限制
资料未提供该技能的安装命令、调用方式、运行平台、是否收费或价格等信息,暂未提供。