Back to Details

optimize-agents-md

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Optimize AGENTS.md

优化AGENTS.md

Apply Boris Cherny's compression principles to AGENTS.md and rules files.
Target: ~2.5k tokens (most are 10k+ unnecessarily)
将Boris Cherny的压缩原则应用于AGENTS.md及规则文件。
目标: ~2.5k Token（多数文件不必要地超过10k Token）

When to Use

使用场景

  • User wants to improve their AGENTS.md or CLAUDE.md
  • Agent instructions feel verbose or redundant
  • Rules exist but lack verification patterns
  • Setting up a new project's agent configuration
  • 用户希望改进其AGENTS.md或CLAUDE.md
  • Agent指令冗长或冗余
  • 规则已存在但缺乏验证模式
  • 搭建新项目的Agent配置

Anti-Patterns to Fix

需修复的反模式

Anti-PatternProblemFix
Context stuffingRepeating info agents already knowDelete obvious instructions
Static memoryNo learnings sectionAdd 
## Learnings
with dates
Format driftInconsistent structureUse consistent headers
Missing verificationNo way to check workAdd 
*Verify:*
patterns to rules
Verbose rulesParagraphs instead of patternsCompress to pattern + verify + fix
反模式问题修复方案
上下文冗余填充重复Agent已熟知的信息删除显而易见的指令
静态记忆无经验总结章节添加带日期的
## Learnings
章节
格式漂移结构不一致使用统一的标题格式
缺失验证无法检查工作成果为规则添加
*Verify:*
模式
规则冗长用段落而非模式表述压缩为“模式 + 验证 + 修复”结构

Workflow

工作流

Phase 1: Analyze Current State

阶段1：分析当前状态

bash
undefined
bash
undefined

Count tokens (rough estimate: words × 1.3)

统计Token数（粗略估算：单词数 × 1.3）

wc -w AGENTS.md
wc -w AGENTS.md

Find redundancy with project files

查找与项目文件的冗余内容

grep -l "bun test" AGENTS.md package.json

Look for:
- Instructions duplicating package.json scripts
- Explanations of common tools (git, npm, bun)
- Verbose descriptions that could be tables
- Rules without verification patterns
grep -l "bun test" AGENTS.md package.json

检查以下内容：
- 与package.json脚本重复的指令
- 对常用工具（git、npm、bun）的解释
- 可转换为表格的冗长描述
- 无验证模式的规则

Phase 2: Compress AGENTS.md

阶段2：压缩AGENTS.md

Structure target:
markdown
undefined
目标结构:
markdown
undefined

AGENTS.md

AGENTS.md

Overview

概述

[1-2 sentences: what this project is]
[1-2句话：项目简介]

Capabilities

能力

[Bullet list of key features/commands]
[关键功能/命令的项目符号列表]

Structure

结构

[Brief file tree of key paths]
[关键路径的简要文件树]

Commands

命令

[Essential commands only - not everything in package.json]
[仅保留必要命令 - 无需包含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

Learnings

[Dated entries from actual issues encountered]

**Compression techniques:**
- Tables over paragraphs
- Bullets over sentences
- Delete anything in package.json
- Delete tool explanations (agents know git, npm, bun)
- Merge related sections
[记录实际遇到问题的带日期条目]

**压缩技巧**:
- 用表格替代段落
- 用项目符号替代长句
- 删除package.json中已有的内容
- 删除对工具的解释（Agent知晓git、npm、bun）
- 合并相关章节

Phase 3: Optimize Rules

阶段3：优化规则

Transform verbose rules into verification patterns:
Before (verbose):
markdown
undefined
将冗长的规则转换为验证模式：
优化前（冗长版）:
markdown
undefined

Type Aliases Over Interfaces

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 }

**After (compressed with verification):**
```markdown
**Type over interface** - `type User = {` instead of `interface User {`
*Verify:* `grep 'interface [A-Z]' src/`
*Fix:* Replace `interface X {` with `type X = {`
Pattern format:
**Rule name** - Brief description with example
*Verify:* Command or tool to check compliance
*Fix:* How to resolve violations
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 }

**优化后（带验证的压缩版）**:
```markdown
**优先使用type而非interface** - `type User = {` 替代 `interface User {`
*Verify:* `grep 'interface [A-Z]' src/`
*Fix:* 将`interface X {`替换为`type X = {`
模式格式:
**规则名称** - 带示例的简要描述
*Verify:* 用于检查合规性的命令或工具
*Fix:* 违规问题的修复方式

Phase 4: Add Living Document Features

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

Learnings section:
markdown
undefined
Learnings章节:
markdown
undefined

Learnings

Learnings

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

**Update trigger:** Add learnings when:
- A mistake required correction
- A pattern was discovered
- A constraint was clarified
  • 2024-01-15: Skills使用CLI工具，切勿重复逻辑
  • 2024-01-20: 规则需包含验证模式以实现自我检查

**更新触发条件**: 当出现以下情况时添加Learnings条目：
- 错误需要修正时
- 发现新的模式时
- 约束条件被明确时

Verification

验证

After optimization:
  1. Token count: 
    wc -w AGENTS.md
    × 1.3 ≈ tokens (target: <2.5k)
  2. No redundancy: 
    grep
    for duplicated info in package.json
  3. Rules have patterns: Each rule has 
    *Verify:*
    line
  4. Learnings exist: 
    ## Learnings
    section present
优化完成后：
  1. Token数: 
    wc -w AGENTS.md
    × 1.3 ≈ Token数（目标：<2.5k）
  2. 无冗余: 用
    grep
    检查与package.json重复的内容
  3. 规则含模式: 每条规则均包含
    *Verify:*
    行
  4. 存在Learnings章节: 已添加
    ## Learnings
    章节

Example Transformations

示例转换

Commands Section

命令章节

Before (340 words):
markdown
undefined
优化前（340词）:
markdown
undefined

Development Commands

Development Commands

To install dependencies, run the following command... [lengthy explanation of bun install]
To run tests, you can use... [explanation of test runner]

**After (40 words):**
```markdown
To install dependencies, run the following command... [关于bun install的冗长解释]
To run tests, you can use... [关于测试运行器的解释]

**优化后（40词）**:
```markdown

Commands

命令

bash
bun install    # Setup
bun run check  # Lint/format
bun test       # Unit tests
undefined
bash
bun install    # 环境搭建
bun run check  # 代码检查/格式化
bun test       # 单元测试
undefined

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.
After:
markdown
**LSP** (`lsp-*`): Type-aware hover, symbol search, references, batch analysis
优化前:
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.
优化后:
markdown
**LSP** (`lsp-*`): 类型感知悬停、符号搜索、引用定位、批量文件分析

Related Skills

相关技能

  • scaffold-rules - Install optimized rules with verification patterns
  • validate-skill - Validate skill structure
  • scaffold-rules - 安装带验证模式的优化规则
  • validate-skill - 验证技能结构