SKILL.md
readonly只读
name
agent-md-refactor
description
重构臃肿的 AGENTS.md、CLAUDE.md 或类似的智能体指令文件，遵循渐进式披露原则。将单一文件拆分为有组织的、相互链接的文档。
Agent MD Refactor
重构臃肿的智能体指令文件（AGENTS.md、CLAUDE.md、COPILOT.md 等），遵循渐进式披露原则——将核心内容保留在根文件，其余内容组织到分类链接文件中。
触发条件
在以下情况下使用此技能：
- "重构我的 AGENTS.md" / "重构我的 CLAUDE.md"
- "拆分我的智能体指令"
- "整理我的 CLAUDE.md 文件"
- "我的 AGENTS.md 太长了"
- "对我的指令进行渐进式披露"
- "清理我的智能体配置"
快速参考
| 阶段 | 操作 | 输出 |
|---|---|---|
| 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 项目中） | 智能体已知 |
| 过于模糊 | “编写干净的代码” | 不可操作 |
| 过于明显 | “不要引入错误” | 浪费上下文 |
| 默认行为 | “使用描述性变量名” | 标准实践 |
| 过时 | 引用已弃用的 API | 不再适用 |
输出格式：
## 标记删除
| 指令 | 原因 |
|------|------|
| “编写干净、可维护的代码” | 过于模糊，不可操作 |
| “使用 TypeScript” | 冗余——项目已经是 TS |
| “不要提交密钥” | 智能体已知 |
| “遵循最佳实践” | 没有具体内容则无意义 |
执行检查清单
[ ] 阶段 1：所有矛盾已识别并解决
[ ] 阶段 2：根文件仅包含核心内容
[ ] 阶段 3：所有剩余指令已分类
[ ] 阶段 4：文件结构已创建，链接正确
[ ] 阶段 5：冗余/模糊指令已移除
[ ] 验证：每个链接文件自包含
[ ] 验证：根文件少于 50 行
[ ] 验证：所有链接正常工作
反模式
| 避免 | 原因 | 替代方案 |
|---|---|---|
| 将所有内容保留在根文件 | 臃肿，难以维护 | 拆分为链接文件 |
| 类别过多 | 碎片化 | 合并相关主题 |
| 模糊指令 | 浪费 token，无价值 | 具体说明或删除 |
| 重复默认设置 | 智能体已知 | 仅在需要时覆盖 |
| 深层嵌套 | 难以导航 | 扁平结构加链接 |
示例
之前（臃肿的根文件）
# 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 行，仅包含通用信息
- 链接有效 - 所有引用的文件存在
- 无矛盾 - 指令一致
- 内容可操作 - 每条指令具体明确
- 覆盖完整 - 没有指令丢失（除非标记删除）
- 文件自包含 - 每个链接文件独立成文
