learned-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Learned Documentation Guide

Learned 文档指南

Overview:

docs/learned/

contains agent-focused documentation with:

YAML frontmatter for routing and discovery
Hierarchical category organization (categories listed in index below)
Index files for category navigation
Routing tables in AGENTS.md

概述：

docs/learned/

存放面向Agent的文档，包含以下特性：

用于路由和发现的YAML frontmatter
层级化分类组织（分类列表见下方索引）
用于分类导航的索引文件
存放在AGENTS.md中的路由表

Core Knowledge (ALWAYS Loaded)

核心知识（始终加载）

@learned-docs-core.md

Document Registry (Auto-Generated)

文档注册表（自动生成）

@docs/learned/index.md

Frontmatter Requirements

Frontmatter 要求

Every markdown file (except index.md) MUST have:

yaml

---
title: Document Title
read_when:
  - "first condition"
  - "second condition"
---

每个Markdown文件（index.md除外）都必须包含：

yaml

---
title: Document Title
read_when:
  - "first condition"
  - "second condition"
---

Required Fields

必填字段

Field	Type	Purpose
`title`	string	Human-readable title for index tables
`read_when`	list[string]	Conditions when agent should read this doc

字段	类型	用途
`title`	字符串	索引表中展示的可读标题
`read_when`	字符串列表	Agent需要读取该文档的触发条件

Writing Effective read_when Values

编写有效的read_when值

Use gerund phrases: "creating a plan", "styling CLI output"
Be specific: "fixing merge conflicts in tests" not "tests"
Include 2-4 conditions covering primary use cases
Think: "An agent should read this when they are..."

Good:

yaml

read_when:
  - "creating or closing plans"
  - "understanding plan states"
  - "working with .erk/impl-context/ directories"

Bad:

yaml

read_when:
  - "plans" # Too vague
  - "the user asks" # Not descriptive

使用动名词短语："creating a plan", "styling CLI output"
尽量具体："fixing merge conflicts in tests" 而不是 "tests"
包含2-4个覆盖主要使用场景的条件
遵循思路："当Agent正在____时应该读取该文档"

正确示例：

yaml

read_when:
  - "creating or closing plans"
  - "understanding plan states"
  - "working with .erk/impl-context/ directories"

错误示例：

yaml

read_when:
  - "plans" # 过于模糊
  - "the user asks" # 没有描述性

Documentation Structure

文档结构

Read the master index for current categories and documents:

docs/learned/index.md

The index contains:

All category paths and descriptions
Root-level documents
Document listings with "Read when..." conditions

请读取主索引了解当前的分类和文档清单：

docs/learned/index.md

索引包含：

所有分类路径和说明
根级文档
附带"Read when..."触发条件的文档列表

Category Placement Guidelines

分类放置指南

Match by topic - Does the doc clearly fit one category? (see index above for categories)
Match by related docs - Are similar docs already in a category?
When unclear - Place at root level; categorize later when patterns emerge
Create new category - When 3+ related docs exist at root level

按主题匹配 - 文档是否明确适配某个分类？（分类列表见上方索引）
按关联文档匹配 - 同类文档是否已经放在某个分类下？
分类不明确时 - 先放在根目录，待后续出现明确模式后再归类
创建新分类 - 当根目录下出现3篇及以上相关文档时可创建新分类

Distinguishing cli/ vs architecture/

区分cli/和architecture/目录

This is the most common confusion:

cli/: Patterns for building CLI commands - how users interact with the tool
- Fast-path patterns (skipping expensive ops)
- Output formatting and styling
- Script mode behavior
- Command organization
architecture/: Internal implementation patterns - how the code works
- Gateway ABCs and dependency injection
- Dry-run via wrapper classes
- Shell integration constraints
- Protocol vs ABC decisions

这是最常见的混淆点：

cli/：存放构建CLI命令的相关模式 - 即用户与工具的交互逻辑
- 快速路径模式（跳过高开销操作）
- 输出格式和样式
- 脚本模式行为
- 命令组织方式
architecture/：存放内部实现模式 - 即代码的运行逻辑
- 网关ABC和依赖注入
- 基于包装类的 dry-run 实现
- Shell集成约束
- Protocol与ABC的选型决策

Document Structure Template

文档结构模板

markdown

---
title: [Clear Document Title]
read_when:
  - "[first condition]"
  - "[second condition]"
---

markdown

---
title: [Clear Document Title]
read_when:
  - "[first condition]"
  - "[second condition]"
---

[Title Matching Frontmatter]

[1-2 sentence overview]

[Main Content Sections]

[Organized content with clear headers]

Index File Template

索引文件模板

Each category has an

index.md

following this pattern:

markdown

---
title: [Category] Documentation
read_when:
  - "[when to browse this category]"
---

每个分类下都有一个遵循以下格式的

index.md

：

markdown

---
title: [Category] Documentation
read_when:
  - "[when to browse this category]"
---

[Category] Documentation

[Category] 文档

[Brief category description]

[分类简要说明]

Quick Navigation

快速导航

When you need to...	Read this
[specific task]	doc.md

当你需要...	阅读该文档
[具体任务]	doc.md

Documents in This Category

该分类下的文档

[Document Title]

[文档标题]

File: doc.md

[1-2 sentence description]

文件： doc.md

[1-2句文档说明]

Reorganizing Documentation

重组文档

When moving files between categories:

在不同分类间移动文件时，请遵循以下步骤：

Step 1: Move Files with git mv

步骤1：使用git mv移动文件

bash

cd docs/learned
git mv old-location/doc.md new-category/doc.md

bash

cd docs/learned
git mv old-location/doc.md new-category/doc.md

Step 2: Update Cross-References

步骤2：更新交叉引用

Find all references to moved files:

bash

grep -r "old-filename.md" docs/learned/

Update relative links:

Same category:
```
[doc.md](doc.md)
```
Different category:
```
[doc.md](../category/doc.md)
```
To category index:
```
[Category](../category/)
```

查找所有对移动后文件的引用：

bash

grep -r "old-filename.md" docs/learned/

更新相对链接：

同分类下：
```
[doc.md](doc.md)
```
不同分类：
```
[doc.md](../category/doc.md)
```
指向分类索引：
```
[Category](../category/)
```

Step 3: Update Index Files

步骤3：更新索引文件

Update Quick Navigation tables in affected index files.

更新受影响的索引文件中的快速导航表格。

Step 4: Update AGENTS.md

步骤4：更新AGENTS.md

If the doc was in the routing table, update the path.

如果该文档在路由表中，更新其路径。

Step 5: Validate

步骤5：校验

Run

make fast-ci

to catch broken links and formatting issues.

运行

make fast-ci

排查失效链接和格式问题。

Updating Routing Tables

更新路由表

AGENTS.md contains the Quick Routing Table for agent navigation.

AGENTS.md包含供Agent导航使用的快速路由表。

When to Add Entries

何时添加路由条目

New category additions
High-frequency tasks
Tasks where wrong approach is common

新增分类时
高频使用的任务
容易使用错误方法的任务

Entry Format

条目格式

markdown

| [Task description] | → [Link or skill] |

Examples:

| Understand project architecture | → [Architecture](docs/learned/architecture/) |

```
| Write Python code | → Load \
```
dignified-python` skill FIRST |`

markdown

| [任务描述] | → [链接或skill] |

示例：

| 理解项目架构 | → [Architecture](docs/learned/architecture/) |

| 编写Python代码 | → 首先加载\

dignified-python` skill |`

Validation

校验

Run before committing:

bash

make fast-ci

This validates:

YAML frontmatter syntax
Required fields present
Markdown formatting (prettier)

提交前请运行：

bash

make fast-ci

该校验会检查：

YAML frontmatter语法
必填字段是否存在
Markdown格式（prettier规范）

⚠️ Generated Files - Do Not Edit Directly

⚠️ 生成文件 - 请勿直接编辑

The following files are auto-generated from frontmatter metadata:

File	Source
`docs/learned/index.md`	Frontmatter from all docs
`docs/learned/<category>/index.md`	Frontmatter from category
`docs/learned/<category>/tripwires.md`	`tripwires:` field in category docs
`docs/learned/tripwires-index.md`	Category tripwires with routing hints

Never edit these files directly. Changes will be overwritten.

以下文件是基于frontmatter元数据自动生成的：

文件	生成来源
`docs/learned/index.md`	所有文档的frontmatter
`docs/learned/<category>/index.md`	分类下所有文档的frontmatter
`docs/learned/<category>/tripwires.md`	分类文档中的 `tripwires:` 字段
`docs/learned/tripwires-index.md`	带有路由提示的分类tripwires

请勿直接编辑这些文件，修改会被覆盖。

Workflow for Changes

修改工作流

Edit the source frontmatter in the relevant documentation file(s)
Run sync:
```
erk docs sync
```
Verify changes in the generated files
Commit both the source and generated files

编辑对应文档源文件的frontmatter
运行同步命令：
```
erk docs sync
```
校验生成文件中的变更
同时提交源文件和生成文件

Adding a New Tripwire

添加新的Tripwire规则

To add a tripwire rule:

Add to the

tripwires:

field in the relevant doc's frontmatter:

yaml

tripwires:
  - action: "doing something dangerous"
    warning: "Do this instead."

Run
```
erk docs sync
```
to regenerate
```
tripwires.md
```

要添加tripwire规则，请按以下步骤操作：

在对应文档的frontmatter中添加

tripwires:

字段：

yaml

tripwires:
  - action: "doing something dangerous"
    warning: "Do this instead."

运行
```
erk docs sync
```
重新生成
```
tripwires.md
```

Quick Reference

快速参考

Full navigation: docs/learned/guide.md
Category index: docs/learned/index.md
Regenerate indexes:
```
erk docs sync
```
Run validation:
```
make fast-ci
```

完整导航：docs/learned/guide.md
分类索引：docs/learned/index.md
重新生成索引：
```
erk docs sync
```
运行校验：
```
make fast-ci
```

learned-docs

Original

Translation

Learned Documentation Guide

Learned 文档指南

Core Knowledge (ALWAYS Loaded)

核心知识（始终加载）

Document Registry (Auto-Generated)

文档注册表（自动生成）

Frontmatter Requirements

Frontmatter 要求

Required Fields

必填字段

Writing Effective read_when Values

编写有效的read_when值

Documentation Structure

文档结构

Category Placement Guidelines

分类放置指南

Distinguishing cli/ vs architecture/

区分cli/和architecture/目录

Document Structure Template

文档结构模板

[Title Matching Frontmatter]

[Title Matching Frontmatter]

[Main Content Sections]

[Main Content Sections]

Related Topics

相关主题

Index File Template

索引文件模板

[Category] Documentation

[Category] 文档

Quick Navigation

快速导航

Documents in This Category

该分类下的文档

[Document Title]

[文档标题]

Related Topics

相关主题

Reorganizing Documentation

重组文档

Step 1: Move Files with git mv

步骤1：使用git mv移动文件

Step 2: Update Cross-References

步骤2：更新交叉引用

Step 3: Update Index Files

步骤3：更新索引文件

Step 4: Update AGENTS.md

步骤4：更新AGENTS.md

Step 5: Validate

步骤5：校验

Updating Routing Tables

更新路由表

When to Add Entries

何时添加路由条目

Entry Format

条目格式

Validation

校验

⚠️ Generated Files - Do Not Edit Directly

⚠️ 生成文件 - 请勿直接编辑

Workflow for Changes

修改工作流

Adding a New Tripwire

添加新的Tripwire规则

Quick Reference

快速参考