optimize-agent-docs

Agent 知识优化器

将积累的文档转化为针对检索优化的知识系统。

核心原则

文件组织是人类关心的事。Agent 不会浏览，而是搜索和加载。优化以下方面：

• 发现：有哪些知识？
• 相关性：这项任务需要这些知识吗？
• 效率：需要加载的最少内容是什么？

工作流

阶段 1：提取知识

盘点所有 Agent 文档：

# Find all agent doc sources
find . -maxdepth 2 -name "*.md" -path "*/.claude/*" -o \
       -name "*.md" -path "*/.codex/*" -o \
       -name "*.md" -path "*/.cursor/*" -o \
       -name "CLAUDE.md" -o -name "AGENTS.md" -o -name "INSTRUCTIONS.md"

对于每个文件，提取：

• 离散事实（单条可执行信息）
• 指令（流程、规则、约束）
• 上下文触发条件（何时需要这些知识？）

阶段 2：分析知识块

将内容拆分为检索单元——能够独立表达完整含义的最小信息片段。

好的知识块：

## Adding API Endpoints
1. Create handler in src/handlers/
2. Register route in src/routes.rs
3. Add OpenAPI spec to docs/api.yaml

不好的知识块（耦合过多）：

See the API section for endpoint patterns, but first read the auth docs,
which reference the middleware guide...

对每个知识块进行评分：

• 是否自成一体？ Agent 无需加载更多内容就能据此采取行动吗？
• 是否针对特定任务？ 是否明确说明何时需要？
• 信息密度是否高？ 每个 token 的有效信息是否足够多？

阶段 3：构建知识清单

生成 .claude/KNOWLEDGE.md，作为 Agent 首先读取的轻量级索引：

# Knowledge Manifest

## Task → Knowledge Map

| When working on... | Load | Key terms |
|-------------------|------|-----------|
| API endpoints | references/api.md | route, handler, endpoint |
| Authentication | references/auth.md | token, session, login |
| Database changes | references/schema.md | migration, model, query |
| Testing | references/testing.md | spec, fixture, mock |
| Deployment | references/deploy.md | release, staging, prod |

## Quick Reference

### Build Commands
- `npm run dev` — Start dev server (port 3000)
- `npm test` — Run test suite
- `npm run build` — Production build

### Key Paths
- Handlers: `src/handlers/`
- Routes: `src/routes.ts`
- Tests: `tests/`

### Critical Rules
- Never commit .env files
- All PRs require tests
- Use conventional commits

清单包含：

1. 任务→知识映射：什么上下文需要加载什么内容
2. 快速参考：高频事实（无需加载文件）
3. 关键规则：必须了解的约束（始终适用）

阶段 4：编译优化后的资料

将冗长的源文档转换为精炼、针对 Agent 优化的版本。

压缩技巧：

源文档（冗长）	编译后（精炼）
"想要添加新端点时，首先应创建处理函数……"	新端点：处理函数 → 路由 → 规范
长篇文字段落	结构化表格
重复信息	单一事实来源
带有解释的示例	仅保留模式

输出结构：

.claude/
├── CLAUDE.md              # Human-readable, can stay verbose
├── KNOWLEDGE.md           # Agent manifest (generated)
└── compiled/              # Agent-optimized versions (generated)
    ├── api.md             # Dense API reference
    ├── patterns.md        # Code patterns as templates
    └── rules.md           # All constraints in one place

阶段 5：生成检索提示

在编译后的文档中添加便于 grep 搜索的标记：

## Adding Endpoints


## Authentication Flow


## Test Patterns

这些标记可用于：

# Find relevant sections for a task
grep -l "@task:new-endpoint" .claude/compiled/*.md

阶段 6：验证

测试优化后的系统：

1. 覆盖检查：源文档中的每条事实都存在于编译后的输出中
2. 检索测试：能否通过最少的加载内容完成常见任务？
3. 密度检查：编译后的版本是否比源文档更精简？

# Compare sizes
wc -l .claude/references/*.md    # Source
wc -l .claude/compiled/*.md       # Compiled (should be smaller)

清单格式

KNOWLEDGE.md 清单采用以下结构：

# Knowledge Manifest


## Task Context Map


| Context | Load | Search |
|---------|------|--------|
| [task description] | [file path] | [grep terms] |

## Always-Loaded Facts


### Commands
[Most-used commands as a table]

### Paths
[Key directories and their purposes]

### Rules
[Critical constraints that always apply]

## Chunk Index


| Topic | Location | Lines | Summary |
|-------|----------|-------|---------|
| [topic] | [file:line-range] | [count] | [one-line summary] |

信息密度原则

将文字转换为结构化内容

之前：

“身份验证系统使用存储在 httpOnly Cookie 中的 JWT 令牌。 用户登录时，服务器会对照数据库验证凭据， 生成一个有效期为 24 小时的令牌，并将其设为 Cookie……”

之后：

## Auth Flow
- Method: JWT in httpOnly cookie
- Expiry: 24h
- Flow: credentials → DB validate → token → cookie

消除冗余

如果同一信息出现在多个位置，请创建一个规范来源并在其他位置引用：

## Token Handling
See: [Auth Flow](#auth-flow) — tokens section

优先使用表格，而非列表

之前：

- The API endpoint for users is /api/users
- The API endpoint for posts is /api/posts
- The API endpoint for comments is /api/comments

之后：

| Resource | Endpoint |
|----------|----------|
| Users | /api/users |
| Posts | /api/posts |
| Comments | /api/comments |

使用模式，而非示例

之前：

To create a user handler:
```javascript
export async function createUser(req, res) {
  const { name, email } = req.body;
  const user = await db.users.create({ name, email });
  res.json(user);
}

之后：

Handler pattern: `export async function {action}{Resource}(req, res)`
Body: Extract params → DB operation → Return result

输出检查清单

优化完成后，验证以下内容：

• KNOWLEDGE.md 已创建且少于 100 行
• 任务→知识映射覆盖常见工作流
• 快速参考包含最常用的事实
• 编译后的文档比源文档更精炼
• 没有遗漏的知识（所有内容均已编入索引）
• 检索提示支持基于 grep 的发现
• 原始源文档未被修改（供人类参考）