Back to Details

agent-md-refactor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent MD Refactor

Agent MD 重构

Refactor bloated agent instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.) to follow progressive disclosure principles - keeping essentials at root and organizing the rest into linked, categorized files.
重构臃肿的Agent说明文件（AGENTS.md、CLAUDE.md、COPILOT.md等），遵循渐进式披露原则——将核心内容保留在根文件中，其余内容整理为分类明确的关联文件。

Triggers

触发场景

Use this skill when:
  • "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"
在以下场景中使用此技能：
  • "重构我的AGENTS.md" / "重构我的CLAUDE.md"
  • "拆分我的Agent说明文档"
  • "整理我的CLAUDE.md文件"
  • "我的AGENTS.md太长了"
  • "为我的说明文档应用渐进式披露"
  • "清理我的Agent配置文档"

Quick Reference

快速参考

PhaseActionOutput
1. AnalyzeFind contradictionsList of conflicts to resolve
2. ExtractIdentify essentialsCore instructions for root file
3. CategorizeGroup remaining instructionsLogical categories
4. StructureCreate file hierarchyRoot + linked files
5. PruneFlag for deletionRedundant/vague instructions
阶段操作输出
1. 分析查找矛盾内容需要解决的冲突列表
2. 提取识别核心内容根文件的核心说明
3. 分类对剩余内容分组逻辑分类结果
4. 结构化创建文件层级根文件 + 关联子文件
5. 精简标记待删除内容冗余/模糊的说明内容

Process

流程

Phase 1: Find Contradictions

阶段1：查找矛盾内容

Identify any instructions that conflict with each other.
Look for:
  • Contradictory style guidelines (e.g., "use semicolons" vs "no semicolons")
  • Conflicting workflow instructions
  • Incompatible tool preferences
  • Mutually exclusive patterns
For each contradiction found:
markdown
undefined
识别所有相互冲突的说明。
需要关注：
  • 矛盾的风格指南（例如："使用分号" vs "不使用分号"）
  • 冲突的工作流说明
  • 不兼容的工具偏好
  • 互斥的模式
对于每个发现的矛盾：
markdown
undefined

Contradiction Found

发现矛盾内容

Instruction A: [quote] Instruction B: [quote]
Question: Which should take precedence, or should both be conditional?

Ask the user to resolve before proceeding.

---
说明A： [引用内容] 说明B： [引用内容]
问题： 哪一个应该优先，还是两者都应设置为条件性规则？

在继续前请询问用户解决这些矛盾。

---

Phase 2: Identify the Essentials

阶段2：识别核心内容

Extract ONLY what belongs in the root agent file. The root should be minimal - information that applies to every single task.
Essential content (keep in root):
CategoryExample
Project descriptionOne sentence: "A React dashboard for analytics"
Package managerOnly if not npm (e.g., "Uses pnpm")
Non-standard commandsCustom build/test/typecheck commands
Critical overridesThings that MUST override defaults
Universal rulesApplies to 100% of tasks
NOT essential (move to linked files):
  • Language-specific conventions
  • Testing guidelines
  • Code style details
  • Framework patterns
  • Documentation standards
  • Git workflow details
仅提取属于根Agent文件的内容。根文件应尽可能精简——仅包含适用于每一项任务的信息。
核心内容（保留在根文件中）：
分类示例
项目描述一句话描述："用于数据分析的React仪表盘"
包管理器仅当不是npm时（例如："使用pnpm"）
非标准命令自定义的构建/测试/类型检查命令
关键覆盖规则必须覆盖默认设置的内容
通用规则适用于100%任务的规则
非核心内容（移至关联文件）：
  • 特定语言的约定
  • 测试指南
  • 代码风格细节
  • 框架模式
  • 文档标准
  • Git工作流细节

Phase 3: Group the Rest

阶段3：对剩余内容分组

Organize remaining instructions into logical categories.
Common categories:
CategoryContents
typescript.md
TS conventions, type patterns, strict mode rules
testing.md
Test frameworks, coverage, mocking patterns
code-style.md
Formatting, naming, comments, structure
git-workflow.md
Commits, branches, PRs, reviews
architecture.md
Patterns, folder structure, dependencies
api-design.md
REST/GraphQL conventions, error handling
security.md
Auth patterns, input validation, secrets
performance.md
Optimization rules, caching, lazy loading
Grouping rules:
  1. Each file should be self-contained for its topic
  2. Aim for 3-8 files (not too granular, not too broad)
  3. Name files clearly: 
    {topic}.md
  4. Include only actionable instructions
将剩余说明整理为逻辑分类。
常见分类：
分类内容
typescript.md
TS约定、类型模式、严格模式规则
testing.md
测试框架、覆盖率、模拟模式
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. 仅包含可执行的说明

Phase 4: Create the File Structure

阶段4：创建文件结构

Output structure:
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
Root file template:
markdown
undefined
输出结构：
project-root/
├── CLAUDE.md (或 AGENTS.md)     # 精简的根文件，包含关联链接
└── .claude/                      # 或 docs/agent-instructions/
    ├── typescript.md
    ├── testing.md
    ├── code-style.md
    ├── git-workflow.md
    └── architecture.md
根文件模板：
markdown
undefined

Project Name

项目名称

One-sentence description of the project.
一句话描述项目。

Quick Reference

快速参考

  • Package Manager: pnpm
  • Build: 
    pnpm build
  • Test: 
    pnpm test
  • Typecheck: 
    pnpm typecheck
  • 包管理器： pnpm
  • 构建： 
    pnpm build
  • 测试： 
    pnpm test
  • 类型检查： 
    pnpm typecheck

Detailed Instructions

详细说明

For specific guidelines, see:
  • TypeScript Conventions
  • Testing Guidelines
  • Code Style
  • Git Workflow
  • Architecture Patterns

**Each linked file template:**
```markdown
如需特定指南，请查看：
  • TypeScript约定
  • 测试指南
  • 代码风格
  • Git工作流
  • 架构模式

**每个关联文件的模板：**
```markdown

{Topic} Guidelines

{主题} 指南

Overview

概述

Brief context for when these guidelines apply.
简要说明这些指南的适用场景。

Rules

规则

Rule Category 1

规则分类1

  • Specific, actionable instruction
  • Another specific instruction
  • 具体的可执行说明
  • 另一条具体说明

Rule Category 2

规则分类2

  • Specific, actionable instruction
  • 具体的可执行说明

Examples

示例

Good

正确示例

```typescript // Example of correct pattern ```
typescript
// 正确模式的示例

Avoid

避免示例

```typescript // Example of what not to do ```

---
typescript
// 应避免的示例

---

Phase 5: Flag for Deletion

阶段5：标记待删除内容

Identify instructions that should be removed entirely.
Delete if:
CriterionExampleWhy Delete
Redundant"Use TypeScript" (in a .ts project)Agent already knows
Too vague"Write clean code"Not actionable
Overly obvious"Don't introduce bugs"Wastes context
Default behavior"Use descriptive variable names"Standard practice
OutdatedReferences deprecated APIsNo longer applies
Output format:
markdown
undefined
识别应完全移除的说明。
符合以下条件则删除：
标准示例删除原因
冗余"使用TypeScript"（在.ts项目中）Agent已知晓此信息
过于模糊"编写干净的代码"不具备可执行性
过于明显"不要引入bug"浪费上下文信息
默认行为"使用描述性变量名"标准实践
过时引用已废弃的API不再适用
输出格式：
markdown
undefined

Flagged for Deletion

标记待删除内容

InstructionReason
"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

---
说明原因
"编写干净、可维护的代码"过于模糊，不具备可执行性
"使用TypeScript"冗余 - 项目已为TS项目
"不要提交密钥"Agent已知晓此信息
"遵循最佳实践"无具体内容，无意义

---

Execution Checklist

执行检查清单

[ ] 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
[ ] 阶段1：所有矛盾已识别并解决
[ ] 阶段2：根文件仅包含核心内容
[ ] 阶段3：所有剩余说明已完成分类
[ ] 阶段4：已创建带正确关联的文件结构
[ ] 阶段5：冗余/模糊说明已移除
[ ] 验证：每个关联文件独立成篇
[ ] 验证：根文件少于50行
[ ] 验证：所有链接可正常访问

Anti-Patterns

反模式

AvoidWhyInstead
Keeping everything in rootBloated, hard to maintainSplit into linked files
Too many categoriesFragmentationConsolidate related topics
Vague instructionsWastes tokens, no valueBe specific or delete
Duplicating defaultsAgent already knowsOnly override when needed
Deep nestingHard to navigateFlat structure with links
应避免原因替代方案
所有内容保留在根文件臃肿，难以维护拆分为关联文件
分类过多碎片化严重合并相关主题
模糊的说明浪费token，无价值具体化或删除
重复默认行为Agent已知晓仅在需要时覆盖默认设置
深层嵌套难以导航扁平化结构+关联链接

Examples

示例

Before (Bloated Root)

重构前（臃肿的根文件）

markdown
undefined
markdown
undefined

CLAUDE.md

CLAUDE.md

This is a React project.
这是一个React项目。

Code Style

代码风格

  • Use 2 spaces
  • Use semicolons
  • Prefer const over let
  • Use arrow functions ... (200 more lines)
  • 使用2个空格缩进
  • 使用分号
  • 优先使用const而非let
  • 使用箭头函数 ...（200多行）

Testing

测试

  • Use Jest
  • Coverage > 80% ... (100 more lines)
  • 使用Jest
  • 覆盖率>80% ...（100多行）

TypeScript

TypeScript

  • Enable strict mode ... (150 more lines)
undefined
  • 启用严格模式 ...（150多行）
undefined

After (Progressive Disclosure)

重构后（渐进式披露）

markdown
undefined
markdown
undefined

CLAUDE.md

CLAUDE.md

React dashboard for real-time analytics visualization.
用于实时数据分析可视化的React仪表盘。

Commands

命令

  • pnpm dev
    - Start development server
  • pnpm test
    - Run tests with coverage
  • pnpm build
    - Production build
  • pnpm dev
    - 启动开发服务器
  • pnpm test
    - 运行带覆盖率的测试
  • pnpm build
    - 生产构建

Guidelines

指南

  • Code Style
  • Testing
  • TypeScript

---
  • 代码风格
  • 测试
  • TypeScript

---

Verification

验证

After refactoring, verify:
  1. Root file is minimal - Under 50 lines, only universal info
  2. Links work - All referenced files exist
  3. No contradictions - Instructions are consistent
  4. Actionable content - Every instruction is specific
  5. Complete coverage - No instructions were lost (unless flagged for deletion)
  6. Self-contained files - Each linked file stands alone
重构完成后，验证以下内容：
  1. 根文件精简 - 少于50行，仅包含通用信息
  2. 链接可用 - 所有引用的文件均存在
  3. 无矛盾 - 说明内容一致
  4. 内容可执行 - 每条说明都具体明确
  5. 覆盖完整 - 无说明丢失（除非标记为待删除）
  6. 文件独立成篇 - 每个关联文件可单独使用