agents-md-optimizer

Agents-MD 优化器

通过应用可发现性筛选来优化 Agent 上下文文件（CLAUDE.md、AGENTS.md、.cursorrules 等）：删除 Agent 可以从代码中发现的信息，只保留不可发现的操作知识（易错点、陷阱、非标准约定），并从源代码中挖掘未记录的易错点。

研究表明，冗余上下文（目录树、数据流图）会使 Agent 性能降低 15-20%，而人工编写的操作知识可将运行时间缩短约 28%。

标志解析

解析 $ARGUMENTS 中的可选标志：

标志	效果
--dry-run	分析并显示差异，不修改文件
--report-only	仅输出统计信息和分类表
--path <path>	指定目标文件路径（见下文自动检测）
--help	显示用法并退出

如果存在 --help，显示可用标志和工作流的简要说明，然后停止。

工作流

阶段 0：设置

语言检测：根据对话历史检测用户所用语言。使用用户的语言呈现所有分析结果和消息。

目标文件解析（未指定 --path 时）：

按以下优先级顺序搜索第一个存在的文件：

1. AGENTS.md
2. CLAUDE.md
3. .cursorrules
4. CURSOR.md
5. .github/copilot-instructions.md
6. .windsurfrules
7. codex.md

如果均未找到，请让用户指定目标文件路径。

小文件检查：如果目标文件少于 20 行，告知用户该文件已经很精简，无需优化。除非用户明确要求继续，否则停止。

步骤 1：基线分析

读取目标文件。收集行数统计信息。

脚本位置：搜索行数统计脚本：

# Search in common skill installation paths
SCRIPT_PATH=$(find ~/.claude/skills ~/.codex/skills ~/.cursor/skills ~/skills 2>/dev/null -path "*/agents-md-optimizer/scripts/line-count.mjs" | head -1)
if [ -z "$SCRIPT_PATH" ]; then
  # Fallback: search in current directory
  SCRIPT_PATH=$(find . -path "*/agents-md-optimizer/scripts/line-count.mjs" 2>/dev/null | head -1)
fi

如果找到脚本，则运行：

node "$SCRIPT_PATH" '<TARGET_PATH>'

回退方案（未找到脚本时）：使用 Bash 手动统计行数：

wc -l '<TARGET_PATH>'
grep -c '^##' '<TARGET_PATH>'

然后将每个 ##/### 章节分为以下三类之一：

类别	含义	操作
discoverable	Agent 可在 10 秒内通过 Glob/Grep/Read 找到	删除
operational	不可发现、但在操作上具有重要意义	保留
verbose	操作知识，但过于详细	精简

分类时，实际读取每个章节引用的源文件。验证相关信息是否确实可发现。详细的分类标准见 references/methodology.md。

以表格形式呈现结果：

## Baseline Analysis — <filename>

Total: XXX lines (YY sections)

| Section | Lines | Category | Rationale |
|---------|-------|----------|-----------|
| Directory Structure | 63 | discoverable | Glob **/* reveals this instantly |
| Design Rules | 8 | operational | Non-standard constraints, not in code |
| Config & State | 24 | verbose | Operational but compressible to ~6 lines |

Removal candidates: XX lines (XX%)

如果使用 --report-only，则在此处停止。

步骤 2：挖掘易错点

扫描项目源代码，找出目标文件中缺失的非显而易见的操作知识。使用 references/gotcha-mining.md 中的系统检查清单。

在代码库中运行的关键 Grep 模式：

MUST|WARNING|HACK|TODO|FIXME          → developer-flagged gotchas
catch.*exit\(0\)|process\.exit        → error exit policies
setTimeout|setInterval|deadline       → timing constraints
=== null|== null|delete result        → implicit semantics
process\.platform|/proc/version       → platform detection quirks
cooldown|throttle|lastNotified        → rate limiting scope

呈现发现：

## Discovered Gotchas

| # | Category | Description | Source | Already documented? |
|---|----------|-------------|--------|---------------------|
| 1 | Timing | 5s→4s→2s budget | _common.mjs:21,52 | No → Add |
| 2 | Implicit | null = key deletion | config.mjs:157 | No → Add |

步骤 3：生成优化后的文件

使用 AskUserQuestion 在修改前征求确认：

根据分析结果：

• 删除：X 行可发现内容（Y 个章节）
• 精简：X 行 → 约 Y 行（Z 个章节）
• 添加：X 条新的易错点

选项：

1. 全部应用 — 删除可发现内容、精简冗长内容、添加易错点
2. 逐项处理 — 逐条审查每项更改
3. 取消 — 不做任何更改

使用 Edit 应用选定的更改（优先进行精准编辑，而非完全重写）。

如果使用 --dry-run，显示差异但不写入文件。

优化后文件的结构（建议的章节顺序）：

1. 项目说明（1-2 行）
2. 开发命令
3. 设计规则（不可妥协的约束）
4. 易错点与陷阱（按类别划分的小节）
5. 约定（项目中的非标准模式）
6. 版本/发布管理
7. 测试

references/anti-patterns.md 中提供了详细的反模式示例及优化前后对比。

第 4 步：验证

重新运行统计（使用第 1 步中的相同脚本或备用方法），并展示优化前后的对比：

## Optimization Results

| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Total lines | 182 | 90 | -51% |
| Discoverable lines | 80 | 0 | Removed |
| Operational lines | 60 | 55 | Kept |
| Gotcha items | 0 | 25 | Added |

Discoverability filter: all remaining lines pass "not discoverable from code" check.

参考文件

• references/methodology.md — 可发现性筛选决策树、分类标准、压缩技巧、效率研究数据
• references/anti-patterns.md — 6 种反模式目录，附有真实的优化前后示例
• references/gotcha-mining.md — 包含 Grep 模式和源代码分析技巧的 8 类问题挖掘清单