update-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update docs — sync documentation with the current diff

更新文档 — 将文档与当前代码差异同步

Scan the repo for documentation that references behavior touched by the current branch, and either update it in place or flag it for human review.

扫描仓库中引用当前分支所修改行为的文档，要么直接就地更新，要么标记出来供人工审核。

Before You Start

开始之前

```
principles/04-file-references-over-snippets.md
```
— why snippets go stale and file references don't.
```
CLAUDE.md
```
at root and at every subdirectory — ambient docs most likely to drift.
```
docs/
```
,
```
README.md
```
,
```
CONTRIBUTING.md
```
, inline
```
*.md
```
files across the repo.

```
principles/04-file-references-over-snippets.md
```
— 为什么代码片段会过时，而文件引用不会。
根目录及每个子目录下的
```
CLAUDE.md
```
— 最容易出现偏差的环境文档。
```
docs/
```
、
```
README.md
```
、
```
CONTRIBUTING.md
```
、仓库中所有内联
```
*.md
```
文件。

Step 1: collect what changed

步骤1：收集变更内容

bash

git diff origin/main...HEAD --name-only > /tmp/changed-files.txt
git diff origin/main...HEAD --stat

bash

git diff origin/main...HEAD --name-only > /tmp/changed-files.txt
git diff origin/main...HEAD --stat

What symbols / functions / endpoints changed? Harder — look at the diff itself.

哪些符号/函数/端点发生了变更？需要进一步查看差异内容。


Note:

- New files added.
- Removed files.
- Renamed symbols or moved files (these break every doc that referenced the old path).
- Changed function signatures or behavior.
- New or removed config options.


注意：

- 新增的文件。
- 删除的文件。
- 重命名的符号或移动的文件（这些会破坏所有引用旧路径的文档）。
- 变更的函数签名或行为。
- 新增或移除的配置选项。

Step 2: find docs that reference the changed code

步骤2：查找引用变更代码的文档

bash

undefined

bash

undefined

Find every markdown file that mentions a changed file path or symbol

查找所有提及变更文件路径或符号的markdown文件

(Adapt the search terms based on step 1's findings.)

（根据步骤1的结果调整搜索关键词）

find . -type f ( -name '.md' -o -name '.mdx' )
-not -path './node_modules/' -not -path './.git/'
-not -path './.claude/worktrees/*'
| xargs grep -l -E '{changed-path-or-symbol}' 2>/dev/null


For each hit, open the file and assess:

| Situation | Action |
|---|---|
| The doc's claim is still accurate | Skip — no update needed. |
| The doc names a file/symbol that was renamed | Update the reference. |
| The doc embeds a snippet that no longer matches the source | Replace the snippet with a file reference (principle 04). |
| The doc describes old behavior | Rewrite to match the new behavior, OR flag and ask the user. |
| The doc is now irrelevant | Delete or merge into another doc. |

find . -type f ( -name '.md' -o -name '.mdx' )
-not -path './node_modules/' -not -path './.git/'
-not -path './.claude/worktrees/*'
| xargs grep -l -E '{changed-path-or-symbol}' 2>/dev/null


对于每个匹配结果，打开文件并评估：

| 场景 | 操作 |
|---|---|
| 文档描述仍然准确 | 跳过 — 无需更新。 |
| 文档中提及的文件/符号已被重命名 | 更新引用内容。 |
| 文档中嵌入的代码片段与源码不再匹配 | 用文件引用替换代码片段（参考原则04）。 |
| 文档描述的是旧行为 | 重写内容以匹配新行为，或标记出来询问用户。 |
| 文档已不再相关 | 删除或合并到其他文档中。 |

Step 3: classify each doc hit

步骤3：对每个匹配的文档进行分类

Put each doc in one of three buckets:

Safe to auto-update — rename updates, trivially corrected file paths. Apply the edit.
Needs human review — behavior changes, removed features, cross-doc inconsistencies. Flag; don't edit.
Delete candidate — the doc is about code that no longer exists. Flag; don't delete.

将每个文档归入以下三个类别之一：

可安全自动更新 — 重命名更新、可轻松修正的文件路径。直接应用修改。
需要人工审核 — 行为变更、功能移除、跨文档不一致。标记出来，不要直接编辑。
待删除候选 — 文档内容针对的代码已不存在。标记出来，不要直接删除。

Step 4: apply the safe updates

步骤4：应用安全更新

For each Safe item, use

Edit

to make the change. Prefer small, targeted edits — change one path or symbol at a time, not a wholesale rewrite.

After edits:

bash

undefined

对于每个可安全更新的项，使用

Edit

进行修改。优先进行小范围、针对性的修改 — 每次只修改一个路径或符号，不要全盘重写。

修改完成后：

bash

undefined

Lint markdown if the project does

如果项目有要求，对markdown进行格式检查

mdformat --check docs/ 2>/dev/null || true

Re-run the docs site build to catch broken links

重新运行文档站点构建以检测失效链接

(pull the command from CLAUDE.md Quick Reference)

（从CLAUDE.md的快速参考中获取命令）

pnpm docs:build OR mkdocs build --strict OR yarn build

pnpm docs:build 或 mkdocs build --strict 或 yarn build

undefined

undefined

Step 5: present the flag list

步骤5：展示标记列表

For everything in Needs human review and Delete candidate, print a table:

markdown

undefined

对于所有需要人工审核和待删除候选的项，打印表格：

markdown

undefined

Docs needing review

需要审核的文档

File	Line	Issue	Proposed action
`docs/guides/auth.md`	42	Describes old OAuth flow removed in this PR	Rewrite or delete
`README.md`	18	Mentions `src/legacy/` which this PR deletes	Remove the paragraph
`packages/api/CLAUDE.md`	55	References behavior of `OldClass` renamed to `NewClass`	Update references

文件	行号	问题	建议操作
`docs/guides/auth.md`	42	描述了此PR中已移除的旧OAuth流程	重写或删除
`README.md`	18	提及了此PR已删除的 `src/legacy/`	删除该段落
`packages/api/CLAUDE.md`	55	引用了已重命名为 `NewClass` 的 `OldClass` 的行为	更新引用内容

Delete candidates

待删除候选

File	Reason
`docs/tutorials/legacy-setup.md`	The "legacy-setup" path this documents is gone


The user picks actions; apply them next pass.

文件	原因
`docs/tutorials/legacy-setup.md`	文档描述的"legacy-setup"路径已不存在


用户选择操作后，在下一轮处理中应用。

Step 6: update

CLAUDE.md

"Things to Know" if a gotcha was resolved

步骤6：如果解决了某个陷阱问题，更新

CLAUDE.md

的“注意事项”部分

If this PR fixed or changed a documented gotcha in

CLAUDE.md

Fix made the gotcha obsolete → remove the entry.
Fix changed the gotcha → rewrite the entry.
This PR introduces a new gotcha → add it.

Validate after:

bash

undefined

如果此PR修复或变更了

CLAUDE.md

中记录的某个陷阱问题：

修复使陷阱问题不再存在 → 删除该条目。
修复改变了陷阱问题的内容 → 重写该条目。
此PR引入了新的陷阱问题 → 添加新条目。

验证完成后：

bash

undefined

Verify

验证

bash

undefined

bash

undefined

Every auto-updated doc still builds

所有自动更新的文档仍可正常构建

(project-specific build command)

（项目特定的构建命令）

No markdown file references a file that no longer exists

确保没有markdown文件引用已不存在的文件

for md in $(find . -type f -name '.md' -not -path './node_modules/' -not -path './.git/*'); do grep -oE '

[a-zA-Z_./-]+/[a-zA-Z_.-]+

' "$md" | tr -d '`' | while read p; do [ ! -e "$p" ] && echo "STALE: $md references missing $p" done done | sort -u | head -30

undefined

for md in $(find . -type f -name '.md' -not -path './node_modules/' -not -path './.git/*'); do grep -oE '

[a-zA-Z_./-]+/[a-zA-Z_.-]+

' "$md" | tr -d '`' | while read p; do [ ! -e "$p" ] && echo "STALE: $md references missing $p" done done | sort -u | head -30

undefined

Common Mistakes

常见错误

Mistake	Correction
Auto-updating a behavior description because the path stayed the same but the behavior changed	Behavior changes go in the "human review" bucket, not the "safe" bucket. Be conservative.
Embedding an updated snippet instead of referencing the file	Principle 04: replace snippets with file references. The snippet will rot again.
Deleting a doc because the current PR makes it look stale, when it describes behavior that's still shipping	Verify the current state of the code matches the doc's claim before declaring the doc stale.
Skipping subdirectory `CLAUDE.md` files	Every scope can have its own `CLAUDE.md` . Scan the full tree, not just root.

错误	修正方式
因为路径未变但行为已变更，就自动更新行为描述	行为变更属于“人工审核”类别，而非“安全更新”类别。请保持谨慎。
嵌入更新后的代码片段而非使用文件引用	参考原则04：用文件引用替换代码片段。否则代码片段会再次过时。
因为当前PR使文档看起来过时就删除文档，但该文档描述的是仍在交付的行为	在判定文档过时之前，先验证代码的当前状态是否与文档描述一致。
忽略子目录下的 `CLAUDE.md` 文件	每个范围都可以有自己的 `CLAUDE.md` 。请扫描整个目录树，而不仅仅是根目录。

update-doc

Original

Translation

Update docs — sync documentation with the current diff

更新文档 — 将文档与当前代码差异同步

Before You Start

开始之前

Step 1: collect what changed

步骤1：收集变更内容

What symbols / functions / endpoints changed? Harder — look at the diff itself.

哪些符号/函数/端点发生了变更？需要进一步查看差异内容。

Step 2: find docs that reference the changed code

步骤2：查找引用变更代码的文档

Find every markdown file that mentions a changed file path or symbol

查找所有提及变更文件路径或符号的markdown文件

(Adapt the search terms based on step 1's findings.)

（根据步骤1的结果调整搜索关键词）

Step 3: classify each doc hit

步骤3：对每个匹配的文档进行分类

Step 4: apply the safe updates

步骤4：应用安全更新

Lint markdown if the project does

如果项目有要求，对markdown进行格式检查

Re-run the docs site build to catch broken links

重新运行文档站点构建以检测失效链接

(pull the command from CLAUDE.md Quick Reference)

（从CLAUDE.md的快速参考中获取命令）

pnpm docs:build OR mkdocs build --strict OR yarn build

pnpm docs:build 或 mkdocs build --strict 或 yarn build

Step 5: present the flag list

步骤5：展示标记列表

Docs needing review

需要审核的文档

Delete candidates

待删除候选

Step 6: update CLAUDE.md "Things to Know" if a gotcha was resolved

步骤6：如果解决了某个陷阱问题，更新CLAUDE.md的“注意事项”部分

Verify

验证

Every auto-updated doc still builds

所有自动更新的文档仍可正常构建

(project-specific build command)

（项目特定的构建命令）

No markdown file references a file that no longer exists

确保没有markdown文件引用已不存在的文件

Common Mistakes

常见错误

Step 6: update
`CLAUDE.md`
"Things to Know" if a gotcha was resolved

步骤6：如果解决了某个陷阱问题，更新
`CLAUDE.md`
的“注意事项”部分