optimize-agents-md

优化 AGENTS.md

将 Boris Cherny 的压缩原则应用于 AGENTS.md 和规则文件。

目标：约 2.5k 个 token（大多数文件不必要地超过 10k）

适用场景

• 用户想改进自己的 AGENTS.md 或 CLAUDE.md
• Agent 指令显得冗长或重复
• 已有规则，但缺少验证模式
• 为新项目配置 Agent

需要修正的反模式

反模式	问题	修正方法
塞入过多上下文	重复 Agent 已知的信息	删除显而易见的指令
静态记忆	没有经验总结部分	添加带日期的 ## Learnings
格式漂移	结构不一致	使用统一的标题
缺少验证	无法检查工作成果	在规则中添加 *Verify:* 模式
规则冗长	用段落代替模式	压缩为模式 + 验证 + 修正

工作流

阶段 1：分析当前状态

# Count tokens (rough estimate: words × 1.3)
wc -w AGENTS.md

# Find redundancy with project files
grep -l "bun test" AGENTS.md package.json

检查以下内容：

• 与 package.json 脚本重复的指令
• 对常用工具（git、npm、bun）的解释
• 可改用表格呈现的冗长描述
• 缺少验证模式的规则

阶段 2：压缩 AGENTS.md

目标结构：

# AGENTS.md

## Overview
[1-2 sentences: what this project is]

## Capabilities  
[Bullet list of key features/commands]

## Structure
[Brief file tree of key paths]

## Commands
[Essential commands only - not everything in package.json]

## Verification
[How to check work is correct]

## Workflow
[Key constraints: plan first, verify incrementally]

## Rules
[Links to rule files or inline compressed rules]

## Learnings
[Dated entries from actual issues encountered]

压缩技巧：

• 优先使用表格，而非段落
• 优先使用项目符号，而非句子
• 删除 package.json 中已有的内容
• 删除工具说明（Agent 已了解 git、npm、bun）
• 合并相关部分

阶段 3：优化规则

将冗长的规则改写为验证模式：

改写前（冗长）：

## Type Aliases Over Interfaces

In this codebase, we prefer using TypeScript type aliases 
instead of interfaces. This provides better consistency 
and flexibility when working with unions and intersections.

Example:
// Good
type User = { name: string }

// Bad  
interface User { name: string }

改写后（压缩并包含验证）：

**Type over interface** - `type User = {` instead of `interface User {`
*Verify:* `grep 'interface [A-Z]' src/`
*Fix:* Replace `interface X {` with `type X = {`

模式格式：

**Rule name** - Brief description with example
*Verify:* Command or tool to check compliance
*Fix:* How to resolve violations

阶段 4：添加动态文档特性

经验总结部分：

## Learnings
- 2024-01-15: Skills use CLI tools, never duplicate logic
- 2024-01-20: Rules need verification patterns for self-checking

更新触发条件： 在以下情况下添加经验总结：

• 错误需要纠正
• 发现了某种模式
• 明确了某项约束

验证

优化后：

1. Token 数量：wc -w AGENTS.md × 1.3 ≈ token 数量（目标：<2.5k）
2. 无冗余：用 grep 查找 package.json 中重复的信息
3. 规则包含模式：每条规则都有 *Verify:* 行
4. 存在经验总结：包含 ## Learnings 部分

转换示例

命令部分

改写前（340 个词）：

## Development Commands

To install dependencies, run the following command...
[lengthy explanation of bun install]

To run tests, you can use...
[explanation of test runner]

改写后（40 个词）：

## Commands
```bash
bun install    # Setup
bun run check  # Lint/format
bun test       # Unit tests

### Capability Description

**Before:**
```markdown
This package provides TypeScript Language Server Protocol 
integration that allows you to get type information, find 
symbols across your workspace, locate references to symbols,
and perform batch analysis of files.

改写后：

**LSP** (`lsp-*`): Type-aware hover, symbol search, references, batch analysis

相关技能

• scaffold-rules - 安装包含验证模式的优化规则
• validate-skill - 验证技能结构