docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docs

文档

Keep the repo legible to humans and agents.

确保仓库对人类和Agent都具备可读性。

Principles

原则

Docs rot silently — every code change is a possible doc change
Routing docs stay short; depth lives in
```
docs/
```
No duplication when a pointer will do
Use repo-relative links for in-repo docs; external links are fine in sources and references
Doc drift is a real failure, not polish debt

文档会悄然过时——每一处代码变更都可能需要同步更新文档
导航类文档保持简洁；详细内容放在
```
docs/
```
目录中
能用链接指向的内容就不重复编写
仓库内文档使用相对路径链接；外部链接可用于来源和参考部分
文档漂移是实际的故障，而非可延后处理的优化问题

Handoffs

交接场景

Missing boot, smoke, e2e, logs, or agent-readiness infrastructure → use
```
agent-readiness
```
Need to judge existing code, a diff, branch, or PR with evidence → use
```
review
```
Need to validate your own completed change on the real surface → use
```
verify
```

缺少启动、冒烟测试、端到端测试、日志或agent-readiness相关基础设施 → 使用
```
agent-readiness
```
流程
需要基于证据评估现有代码、差异、分支或PR → 使用
```
review
```
流程
需要在真实环境中验证已完成的变更 → 使用
```
verify
```
流程

Workflow

工作流

1. Audit the doc surface

1. 审计文档范围

Check the files humans and agents actually rely on:

```
AGENTS.md
```
```
CLAUDE.md
```
```
README.md
```
```
CONTRIBUTING.md
```
```
SECURITY.md
```
```
docs/
```
plans, specs, runbooks, decision docs

Flag stale commands, dead paths, duplicated guidance, and routing failures.

检查人类和Agent实际依赖的文件：

```
AGENTS.md
```
```
CLAUDE.md
```
```
README.md
```
```
CONTRIBUTING.md
```
```
SECURITY.md
```
```
docs/
```
目录
计划、规格说明、运行手册、决策文档

标记过时命令、无效路径、重复指南和导航失效问题。

2. Update routing docs

2. 更新导航类文档

Keep top-level docs terse and navigational.

```
AGENTS.md
```
should be a table of contents, not a wiki
If the repo uses
```
AGENTS.md
```
, keep
```
CLAUDE.md
```
at the same level as a symlink to
```
AGENTS.md
```
instead of maintaining a second authored file
```
README.md
```
should lead with value and the fastest path to use the project
```
CONTRIBUTING.md
```
should hold contributor setup, validation, and workflow
```
SECURITY.md
```
should hold private-first vulnerability reporting guidance
Push detail downward instead of bloating top-level files
Use the concrete top-level split and section order in references/documentation.md instead of inventing a new shape every time
Prefer terse routing over narrative sprawl, for example
```
README.md
```
should link to deeper docs instead of re-explaining them inline

保持顶层文档简洁，仅作导航用途。

```
AGENTS.md
```
应作为目录，而非维基百科式文档
如果仓库使用
```
AGENTS.md
```
，将
```
CLAUDE.md
```
设为指向
```
AGENTS.md
```
的符号链接，而非维护一份独立编写的文件
```
README.md
```
应首先展示项目价值和最快使用路径
```
CONTRIBUTING.md
```
应包含贡献者的设置、验证和工作流说明
```
SECURITY.md
```
应包含以隐私优先的漏洞上报指南
将详细内容下移，避免顶层文件臃肿
使用references/documentation.md中明确的顶层拆分和章节顺序，而非每次都自定义结构
优先选择简洁导航而非冗长叙述，例如
```
README.md
```
应链接到深层文档，而非在内部重复解释内容

3. Update deep docs and specs

3. 更新深层文档与规格说明

Refresh the detailed documents that actually carry the knowledge.

architecture and API docs
task guides and runbooks
feature specs, plans, and decision records
readiness infrastructure docs after agent-readiness changes

For new features, use the directory layout and templates in references/structuring.md — specs, plans, and decisions each have their own shape.

刷新承载实际知识的详细文档。

架构和API文档
任务指南和运行手册
功能规格、计划和决策记录
agent-readiness变更后的就绪基础设施文档

对于新功能，使用references/structuring.md中的目录结构和模板——规格说明、计划和决策各有其专属格式。

4. Clean up drift

4. 清理文档漂移

deduplicate repeated facts
delete or archive stale docs
fix cross-links and moved paths
keep naming and commands consistent across files

Example — fixing a stale path after a rename:

diff

 # AGENTS.md
-- Run `scripts/bootstrap.sh` to set up the dev environment.
+- Run `scripts/setup.sh` to set up the dev environment.

去重重复内容
删除或归档过时文档
修复交叉链接和已移动的路径
保持各文件中的命名和命令一致

示例——重命名后修复过时路径：

diff

 # AGENTS.md
-- Run `scripts/bootstrap.sh` to set up the dev environment.
+- Run `scripts/setup.sh` to set up the dev environment.

5. Validate reality

5. 验证真实性

Do not trust prose. Check that commands, file paths, and entry points still match the repo.

Concrete checks:

rg -n "old/path|stale-command" AGENTS.md CLAUDE.md README.md docs/

when paths or commands moved

```
test -e <path-from-docs>
```
before keeping a file reference

test ! -e AGENTS.md || { test -L CLAUDE.md && test "$(readlink CLAUDE.md)" = "AGENTS.md"; }

when normalizing agent entrypoints

不要仅依赖文字描述。检查命令、文件路径和入口点是否与仓库实际情况匹配。

具体检查项：

当路径或命令变更时，执行

rg -n "old/path|stale-command" AGENTS.md CLAUDE.md README.md docs/

在保留文件引用前，执行
```
test -e <path-from-docs>
```
验证路径存在

标准化Agent入口点时，执行

test ! -e AGENTS.md || { test -L CLAUDE.md && test "$(readlink CLAUDE.md)" = "AGENTS.md"; }

Output

输出

After docs work, report:

files updated
stale or duplicated docs removed or rewritten
commands or paths verified
remaining doc gaps
any handoff needed to
```
agent-readiness
```
,
```
review
```
, or
```
verify
```

文档工作完成后，需报告：

更新的文件
已移除或重写的过时/重复文档
已验证的命令或路径
剩余的文档缺口
是否需要交接给
```
agent-readiness
```
、
```
review
```
或
```
verify
```
流程

References

参考资料

references/documentation.md — AGENTS.md shape, scoped rules, README patterns, doc hygiene
references/specifications.md — feature specs, conformance tests, spec drift, SDD trade-offs
references/structuring.md — directory layout, templates, and naming for specs, plans, and decisions

references/documentation.md — AGENTS.md格式、范围规则、README模式、文档卫生规范
references/specifications.md — 功能规格、一致性测试、规格漂移、SDD权衡
references/structuring.md — 规格说明、计划和决策的目录结构、模板及命名规范