name: agent-md-refactor 描述: 重构臃肿的AGENTS.md、CLAUDE.md或类似代理指令文件，遵循渐进式披露原则。将单块文件拆分为有组织的、链接的文档。 license: MIT
代理MD重构
重构臃肿的代理指令文件（AGENTS.md、CLAUDE.md、COPILOT.md等）以遵循渐进式披露原则 - 将核心内容保留在根文件，其余组织成链接的分类文件。
触发条件
使用此技能当：
- “refactor my AGENTS.md” / “refactor my CLAUDE.md”
- “split my agent instructions”
- “organize my CLAUDE.md file”
- “my AGENTS.md is too long”
- “progressive disclosure for my instructions”
- “clean up my agent config”
快速参考
| 阶段 | 操作 | 输出 |
|---|---|---|
| 1. 分析 | 寻找矛盾 | 待解决的冲突列表 |
| 2. 提取 | 识别核心内容 | 根文件的核心指令 |
| 3. 分类 | 分组剩余指令 | 逻辑类别 |
| 4. 结构 | 创建文件层次结构 | 根文件 + 链接文件 |
| 5. 修剪 | 标记删除 | 冗余/模糊指令 |
流程
阶段1：寻找矛盾
识别相互冲突的指令。
寻找：
- 矛盾的风格指南（例如，“使用分号” vs “不使用分号”）
- 冲突的工作流程指令
- 不兼容的工具偏好
- 互斥的模式
对于每个发现的矛盾：
## 发现矛盾
**指令 A:** [引用]
**指令 B:** [引用]
**问题：** 哪个应优先，还是都应设为条件？
在继续之前询问用户解决。
阶段2：识别核心内容
仅提取属于根代理文件的内容。根文件应最小化 - 适用于每个任务的信息。
核心内容（保留在根文件中）：
| 类别 | 示例 |
|---|---|
| 项目描述 | 一句话：“用于分析的React仪表板” |
| 包管理器 | 仅当不是npm时（例如，“使用pnpm”） |
| 非标准命令 | 自定义构建/测试/类型检查命令 |
| 关键覆盖 | 必须覆盖默认值的内容 |
| 通用规则 | 适用于100%任务的规则 |
非核心内容（移动到链接文件）：
- 语言特定约定
- 测试指南
- 代码风格细节
- 框架模式
- 文档标准
- Git工作流程细节
阶段3：分组剩余内容
将剩余指令组织成逻辑类别。
常见类别：
| 类别 | 内容 |
|---|---|
typescript.md |
TS约定、类型模式、严格模式规则 |
testing.md |
测试框架、覆盖率、模拟模式 |
code-style.md |
格式化、命名、注释、结构 |
git-workflow.md |
提交、分支、PR、审查 |
architecture.md |
模式、文件夹结构、依赖项 |
api-design.md |
REST/GraphQL约定、错误处理 |
security.md |
认证模式、输入验证、密钥 |
performance.md |
优化规则、缓存、懒加载 |
分组规则：
- 每个文件应在其主题上自包含
- 目标为3-8个文件（不要太细，不要太宽）
- 文件命名清晰：
{topic}.md - 仅包括可操作的指令
阶段4：创建文件结构
输出结构：
project-root/
├── CLAUDE.md (或 AGENTS.md) # 最小化根文件带链接
└── .claude/ # 或 docs/agent-instructions/
├── typescript.md
├── testing.md
├── code-style.md
├── git-workflow.md
└── architecture.md
根文件模板：
# 项目名称
项目的一句话描述。
## 快速参考
- **包管理器：** pnpm
- **构建：** `pnpm build`
- **测试：** `pnpm test`
- **类型检查：** `pnpm typecheck`
## 详细指令
具体指南，请参见：
- [TypeScript约定](.claude/typescript.md)
- [测试指南](.claude/testing.md)
- [代码风格](.claude/code-style.md)
- [Git工作流程](.claude/git-workflow.md)
- [架构模式](.claude/architecture.md)
每个链接文件模板：
# {主题}指南
## 概述
应用这些指南的简要上下文。
## 规则
### 规则类别1
- 具体、可操作的指令
- 另一个具体指令
### 规则类别2
- 具体、可操作的指令
## 示例
### 好
\`\`\`typescript
// 正确模式的示例
\`\`\`
### 避免
\`\`\`typescript
// 不应做的示例
\`\`\`
阶段5：标记删除
识别应完全删除的指令。
如果符合以下条件则删除：
| 标准 | 示例 | 为什么删除 |
|---|---|---|
| 冗余 | “使用TypeScript”（在.ts项目中） | 代理已经知道 |
| 太模糊 | “写干净代码” | 不可操作 |
| 过于明显 | “不要引入bug” | 浪费上下文 |
| 默认行为 | “使用描述性变量名” | 标准实践 |
| 过时 | 引用已弃用API | 不再适用 |
输出格式：
## 标记删除
| 指令 | 原因 |
|-------------|--------|
| “写干净、可维护的代码” | 太模糊，不可操作 |
| “使用TypeScript” | 冗余 - 项目已经是TS |
| “不要提交密钥” | 代理已经知道这个 |
| “遵循最佳实践” | 没有具体内容无意义 |
执行清单
[ ] 阶段1：所有矛盾已识别并解决
[ ] 阶段2：根文件仅包含核心内容
[ ] 阶段3：所有剩余指令已分类
[ ] 阶段4：文件结构创建并带正确链接
[ ] 阶段5：冗余/模糊指令已删除
[ ] 验证：每个链接文件自包含
[ ] 验证：根文件少于50行
[ ] 验证：所有链接正常工作
反模式
| 避免 | 为什么 | 代替 |
|---|---|---|
| 将所有内容保留在根文件 | 臃肿、难以维护 | 拆分为链接文件 |
| 太多类别 | 碎片化 | 合并相关主题 |
| 模糊指令 | 浪费标记、无价值 | 具体化或删除 |
| 复制默认值 | 代理已经知道 | 仅在需要时覆盖 |
| 深层嵌套 | 难以导航 | 带有链接的扁平结构 |
示例
之前（臃肿的根文件）
# CLAUDE.md
这是一个React项目。
## 代码风格
- 使用2空格
- 使用分号
- 优先使用const而非let
- 使用箭头函数
... (200多行)
## 测试
- 使用Jest
- 覆盖率 > 80%
... (100多行)
## TypeScript
- 启用严格模式
... (150多行)
之后（渐进式披露）
# CLAUDE.md
用于实时分析可视化的React仪表板。
## 命令
- `pnpm dev` - 启动开发服务器
- `pnpm test` - 运行测试带覆盖率
- `pnpm build` - 生产构建
## 指南
- [代码风格](.claude/code-style.md)
- [测试](.claude/testing.md)
- [TypeScript](.claude/typescript.md)
验证
重构后验证：
- 根文件最小化 - 少于50行，仅通用信息
- 链接正常工作 - 所有引用的文件存在
- 无矛盾 - 指令一致
- 可操作内容 - 每个指令具体
- 完整覆盖 - 没有指令丢失（除非标记删除）
- 自包含文件 - 每个链接文件独立