Back to Details

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.

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

git diff origin/main...HEAD -- '.py' '.ts' '.js' '.go' '*.rs'
| grep -E '^[+-](def |class |function |const |export |impl )'
| sort -u

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.
git diff origin/main...HEAD -- '.py' '.ts' '.js' '.go' '*.rs'
| grep -E '^[+-](def |class |function |const |export |impl )'
| sort -u

注意：

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

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
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

需要审核的文档

FileLineIssueProposed action
docs/guides/auth.md
42Describes old OAuth flow removed in this PRRewrite or delete
README.md
18Mentions 
src/legacy/
which this PR deletes		Remove the paragraph
packages/api/CLAUDE.md
55References 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

待删除候选

FileReason
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

常见错误

MistakeCorrection
Auto-updating a behavior description because the path stayed the same but the behavior changedBehavior changes go in the "human review" bucket, not the "safe" bucket. Be conservative.
Embedding an updated snippet instead of referencing the filePrinciple 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 shippingVerify 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
。请扫描整个目录树，而不仅仅是根目录。