agent-md-refactor

Agent MD 重构

重构臃肿的 Agent 指令文件（AGENTS.md、CLAUDE.md、COPILOT.md 等），使其遵循渐进式披露原则——将核心内容保留在根文件中，其余内容整理到相互链接、分类清晰的文件中。

---

触发条件

在以下情况使用此技能：

• “重构我的 AGENTS.md” / “重构我的 CLAUDE.md”
• “拆分我的 Agent 指令”
• “整理我的 CLAUDE.md 文件”
• “我的 AGENTS.md 太长了”
• “为我的指令实施渐进式披露”
• “清理我的 Agent 配置”

---

快速参考

阶段	操作	输出
1. 分析	查找矛盾	待解决的冲突列表
2. 提取	识别核心内容	根文件的核心指令
3. 分类	对剩余指令分组	逻辑类别
4. 结构化	创建文件层级	根文件 + 链接文件
5. 精简	标记待删除内容	冗余/含糊的指令

---

流程

阶段 1：查找矛盾

找出任何相互冲突的指令。

查找：

• 矛盾的风格指南（例如，“使用分号”与“不使用分号”）
• 冲突的工作流指令
• 不兼容的工具偏好
• 互斥的模式

对于发现的每个矛盾：

## Contradiction Found

**Instruction A:** [quote]
**Instruction B:** [quote]

**Question:** Which should take precedence, or should both be conditional?

请用户先解决矛盾，然后再继续。

---

阶段 2：识别核心内容

仅提取属于根 Agent 文件的内容。根文件应尽量精简——只包含适用于每一个任务的信息。

核心内容（保留在根文件中）：

类别	示例
项目描述	一句话：“一个用于分析的 React 仪表板”
包管理器	仅当不是 npm 时（例如，“使用 pnpm”）
非标准命令	自定义 build/test/typecheck 命令
关键覆盖	必须覆盖默认值的内容
通用规则	适用于 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	优化规则、缓存、懒加载

分组规则：

1. 每个文件应针对其主题自成一体
2. 目标为 3-8 个文件（既不过于零碎，也不过于宽泛）
3. 清晰命名文件：{topic}.md
4. 仅包含可执行的指令

---

阶段 4：创建文件结构

输出结构：

project-root/
├── CLAUDE.md (or AGENTS.md)     # Minimal root with links
└── .claude/                      # Or docs/agent-instructions/
    ├── typescript.md
    ├── testing.md
    ├── code-style.md
    ├── git-workflow.md
    └── architecture.md

根文件模板：

# Project Name

One-sentence description of the project.

## Quick Reference

- **Package Manager:** pnpm
- **Build:** `pnpm build`
- **Test:** `pnpm test`
- **Typecheck:** `pnpm typecheck`

## Detailed Instructions

For specific guidelines, see:
- [TypeScript Conventions](.claude/typescript.md)
- [Testing Guidelines](.claude/testing.md)
- [Code Style](.claude/code-style.md)
- [Git Workflow](.claude/git-workflow.md)
- [Architecture Patterns](.claude/architecture.md)

每个链接文件的模板：

# {Topic} Guidelines

## Overview
Brief context for when these guidelines apply.

## Rules

### Rule Category 1
- Specific, actionable instruction
- Another specific instruction

### Rule Category 2
- Specific, actionable instruction

## Examples

### Good
\`\`\`typescript
// Example of correct pattern
\`\`\`

### Avoid
\`\`\`typescript
// Example of what not to do
\`\`\`

---

阶段 5：标记待删除内容

找出应完全移除的指令。

在以下情况删除：

标准	示例	删除原因
冗余	“使用 TypeScript”（在 .ts 项目中）	Agent 已经知道
过于含糊	“编写干净的代码”	不可执行
过于显而易见	“不要引入 bug”	浪费上下文
默认行为	“使用描述性的变量名”	标准做法
过时	引用已弃用的 API	不再适用

输出格式：

## Flagged for Deletion

| Instruction | Reason |
|-------------|--------|
| "Write clean, maintainable code" | Too vague to be actionable |
| "Use TypeScript" | Redundant - project is already TS |
| "Don't commit secrets" | Agent already knows this |
| "Follow best practices" | Meaningless without specifics |

---

执行清单

[ ] Phase 1: All contradictions identified and resolved
[ ] Phase 2: Root file contains ONLY essentials
[ ] Phase 3: All remaining instructions categorized
[ ] Phase 4: File structure created with proper links
[ ] Phase 5: Redundant/vague instructions removed
[ ] Verify: Each linked file is self-contained
[ ] Verify: Root file is under 50 lines
[ ] Verify: All links work correctly

---

反模式

避免	原因	改为
将所有内容保留在根目录	臃肿，难以维护	拆分为互相链接的文件
分类过多	碎片化	合并相关主题
指令含糊	浪费 token，没有价值	具体说明或删除
重复默认内容	Agent 已经知道	仅在需要时覆盖
嵌套过深	难以浏览	使用带链接的扁平结构

---

示例

之前（臃肿的根文件）

# CLAUDE.md

This is a React project.

## Code Style
- Use 2 spaces
- Use semicolons
- Prefer const over let
- Use arrow functions
... (200 more lines)

## Testing
- Use Jest
- Coverage > 80%
... (100 more lines)

## TypeScript
- Enable strict mode
... (150 more lines)

之后（渐进式披露）

# CLAUDE.md

React dashboard for real-time analytics visualization.

## Commands
- `pnpm dev` - Start development server
- `pnpm test` - Run tests with coverage
- `pnpm build` - Production build

## Guidelines
- [Code Style](.claude/code-style.md)
- [Testing](.claude/testing.md)
- [TypeScript](.claude/typescript.md)

---

验证

重构后，验证：

1. 根文件保持精简 - 少于 50 行，仅包含通用信息
2. 链接有效 - 所有引用的文件都存在
3. 没有矛盾 - 指令保持一致
4. 内容可操作 - 每条指令都具体明确
5. 覆盖完整 - 没有丢失任何指令（除非已标记为删除）
6. 文件自包含 - 每个链接文件都可独立成立

---