update-docs

更新文档

变更后的文档检查。将不易察觉的知识记录到合适的文档中，精简冗余内容，并在可能导致文档偏差的变更后，确保仓库各处文档保持一致。

适用情况

• 基础设施、配置、架构或运维发生变更后
• PR 合并、发布版本确定、功能发布或版本号更新后，且这些变更可能导致文档偏差
• 有人要求刷新文档、指令文件、运维手册、变更日志、API 文档、路线图或 README 内容时
• 会话中发现新的注意事项、设置步骤变更、外部行为变化或新增服务时
• API 契约、功能范围、迁移路径或发布／安装流程发生变更时
• 仓库文档明显不够完善，值得向用户建议启动最小化文档建设时

不适用情况

• 未经用户批准从头编写一整套文档
• 代码正确性或安全审查——使用 code-review 或 security-audit
• 代码质量、冗余代码或可维护性清理——使用 code-simplification
• 提示词编写或可复用技能文件维护——使用 prompt-generator 或 skill-creator
• 跨多个领域全面审计代码库——使用 repo-audit（它会将 update-docs 作为其中一个检查环节）
• Git 提交消息、PR 描述、发布公告文案或标签操作——使用 git
• 路线图优先级排序和待办事项梳理属于 roadmap 技能；将已交付的 [planned] / [exploring] 项目移至其他位置属于路线图模式 2；此处负责记录明确的版本号和亮点说明

---

AI 自检

提交文档更新前，请确认：

• 覆盖受众所需内容：设置、公开行为、注意事项、决策和故障模式；没有冗余的实现清单
• 未引入过期计数（使用“N”或确保计数准确）
• 已验证内部链接（重命名或移动后没有失效引用）
• 配套指令文件仍保持一致（如果 CLAUDE.md 有变更，则同步更新 AGENTS.md）
• 创建新的 Markdown 文件前，已先检查现有文档
• 仅在变更确实影响发布、API、路线图和功能文档时才更新它们
• 不为已修复的问题保留过时的注意事项
• 已弃用条目以 [DEPRECATED] 前缀和日期标记，而非直接删除
• 环境变量或运行时配置有变更时，已更新 .env.example
• 如果仓库文档过于简略，已向用户建议启动最小化文档建设，而非直接强行实施
• 已运行大小检查（wc -c）——指令文件不得超过 40,000 个字符
• 已检查 README／质量证据部分是否存在过期日期、过时计数和旧的运行记录引用
• 已检查所有路线图文件（已提交和被 git 忽略的文件）——其中标注的版本／日期与当前 HEAD 或最新标签一致
• 如果同时存在私有和公开路线图，两者均已更新；公开路线图仅包含用户可见的亮点，私有路线图则包含内部细节
• 文档与代码一致：已根据变更后的实现检查命令、标志、配置名称、屏幕截图和 API 示例
• 已检查受众查阅路径：仅在用户需要时更新 README、变更日志、API 文档、运维手册和迁移说明
• 已应用跨领域 Agent 规范——参见 references/agent-hygiene.md

核心原则

记录读者采取行动所需的信息，并放在他们实际会查阅的文件中。 在受众需要时说明设置、公开行为和必要的默认值；避免重复实现清单。记录注意事项、决策、故障模式、变通方法、隐式依赖、面向发布的变更，以及“花了 30 分钟才弄明白的事情”。

---

实践

• 如果项目已有生成工具，优先使用生成的 API／Schema 文档。
• 示例应尽量精简且可运行，以便日后轻松验证。
• 在用户会查看的位置记录行为变更、弃用事项、迁移步骤和回滚说明。
• 删除过时的说明，不要追加相互矛盾的内容。
• 更新日志条目应面向用户，避免加入内部实现细节。

工作流

仅审计模式： 通过 repo-audit 调用或被要求报告／检查文档时，应检查适用的步骤 1–7，包括配套文件的结构和偏差，但不要编辑。跳过提交步骤 8。将所有检查限定在请求变更影响到的文档范围内；私有配置和无关的路线图不属于自动全面检查的目标。

复制此清单并跟踪进度：

• 1. 确定变更（1.5 路线图时效性，1.6 证据时效性）
• 2. 对文档影响进行分类
• 3. 检查仓库的文档是否缺失或过于简略
• 4. 更新受影响的文档（或在仅审计模式下报告需要更新的内容）
• 5. 验证内部链接；如果有链接失效，修复并返回步骤 5
• 6. 审查指令文件是否冗余
• 7. 同步配套指令文件
• 8. 提交文档变更

1. 确定变更内容

检查 git diff 和对话上下文，了解修改了哪些内容：

# Uncommitted changes
git diff --name-only

# Compare against the roadmap's stated version, falling back to last tag, falling back to last 10
ROADMAP_VER=$(grep -hoE 'Current:?\s*v?[0-9]+\.[0-9]+\.[0-9]+' ROADMAP.md docs/ROADMAP.md 2>/dev/null | head -1 | grep -oE 'v?[0-9]+\.[0-9]+\.[0-9]+')
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
RANGE="${ROADMAP_VER:-${LAST_TAG}}..HEAD"
git log --oneline "$RANGE" 2>/dev/null || git log --oneline -10

检查以下内容是否有变更：配置、基础设施、服务部署、脚本、CI 工作流、网络／IP 分配、服务版本以及任何运维相关内容。

1.5. 路线图时效性检查

路线图最容易与实际情况脱节，因为它们会重述代码、标签和提交历史已经证实的事实。只要仓库中存在路线图（无论已提交还是被 gitignore 忽略），就运行此检查。如果未找到路线图，则无需执行；缺少 ROADMAP.md 不算错误。

运行 references/roadmap-freshness.md 中的脚本。该脚本会发现所有路线图文件（已跟踪和被 gitignore 忽略的），解析每个文件中的 Current／Updated／Version 标题，并在所述版本早于最新标签、标题日期之后发布了新版本，或标题日期比 HEAD 落后超过 14 个日历日时报告 ROADMAP DRIFT。发现偏差时，应扩大步骤 2 中的 RANGE 范围。参考文件还包含检查路线图正文中过时的 Scanned／as of 日期的旁路检查；应将这些作为单独的观察结果报告。

不要捏造更新后的内容。用户希望指出过时之处，以便自行决定是否手动更新，而不是让你编造数据。

1.6. 证据时效性检查

README 文件通常包含会悄然过时的“质量证据”段落：旧基准测试日期、旧运行 ID、过时的技能数量、过时的测试数量、旧版本号，或与仓库当前状态不符的“最新运行”等说法。编辑 README、CHANGELOG、发布文档、项目状态文档或任何包含证据／质量／状态表述的文档时，都要运行此检查。

# Find brittle evidence claims in tracked docs.
DOCS=$(git ls-files '*.md' 'docs/**/*.md' 2>/dev/null)
if [[ -n "$DOCS" ]]; then
  printf '%s\n' "$DOCS" | while IFS= read -r doc; do
    git grep -n -E '([0-9]{4}-[0-9]{2}-[0-9]{2}|[0-9]+/[0-9]+|quality evidence|benchmark|latest (run|score|evidence|benchmark)|current (run|score|evidence|gates|version)|score[: ]|passed (for|in|on))' -- "$doc" 2>/dev/null || true
  done
fi
# Any claimed count ("N plugins", "N endpoints", "N tests") is only as good as the inventory
# that proves it. Recount from the repo's own source of truth before repeating the number:
#   git ls-files '<the tracked glob the claim describes>' | wc -l
# Do the same for scores, run IDs, and benchmark dates: re-read the artifact that stores them.

每项证据声明都必须在同一会话中重新读取其对应的材料：例如从仓库清点结果中获取数量、从记录分数或运行 ID 的文件中获取相关数据，或从来源报告中获取日期。不要重述先前会话中的数据，也不要依据声明所在的文档来重述。

发现过时的证据声明时，应从源材料更新，或改写以避免使用易过时的计数。较好的写法：“当前仓库的门禁检查已通过，适用于公开技能集合。” 有风险的写法：“当前门禁检查已通过全部 42 项技能”，除非你在本次运行中验证了该数量。

2. 对文档影响进行分类

将变更映射到需要更新的文档目标。常见的指令文件名：CLAUDE.md、AGENTS.md、GEMINI.md、CODEX.md。根据项目的文档结构调整：

变更类型	可能需要更新的文档
新增/变更基础设施规范	项目指令文件（AGENTS.md 或同类文件）、清单文档
部署新的服务或应用	项目指令文件、部署文档
IP/端口/端点变更	项目指令文件、网络清单
版本升级（运行时、依赖项、镜像）	项目指令文件
发现新的注意事项	项目指令文件
执行操作流程	操作手册或部署检查清单（注明该流程在部署周期中的执行时机）
新增密钥或凭据	密钥清单
CI/CD 工作流变更	项目指令文件、流水线文档
Docker/Compose 变更	项目指令文件、部署文档
Proxmox/LXC 变更	项目指令文件、清单文档
Rust crate/toolchain 变更	项目指令文件、README.md（构建先决条件）
架构决策	如果影响重大，则编写 ADR（见下文）；否则在指令文件中添加简短条目
新增或变更环境变量、配置键或运行时配置	.env.example、README.md（设置部分）
新增依赖项或设置步骤	README.md（入门指南/先决条件）
API 端点或契约变更	API.md、README.md（API 部分）、端点文档，以及适用时的 OpenAPI 规范
新增、移除或实质性变更功能	README.md、功能文档（FEATURES.md、FEATURESET.md、docs/features/*.md）、变更日志
已合并且对用户可见的 PR	变更日志、路线图/状态文档、发行说明，以及受影响的功能/API/设置文档
版本升级/发布新版本	CHANGELOG.md、发行说明、README.md、安装/升级文档、徽章、包管理器说明
发布版本或升级版本（路线图方面）	ROADMAP.md 标题（Current / Updated）、已交付亮点部分、状态文档
自上次更新路线图以来交付了多个功能	ROADMAP.md 中的已交付亮点说明和当前进度总结（条目状态变更属于路线图模式 2）
同时存在 Git 忽略的私有路线图和已提交的公开路线图	两者都要更新——私有路线图补充更深入的内部细节，公开路线图提供面向用户的概要
策略或顺序变更	ROADMAP.md、状态文档、里程碑文档

何时编写 ADR： 如果某项决策会影响多个组件、限制未来的选择，或推翻之前的决策，那么值得专门编写一份架构决策记录。如果只是简短的一句话（“因为 Z，从 X 切换到了 Y”），在项目指令文件中添加一条简短说明就足够了。

注意事项的放置判断：

• 一句话的注意事项（例如，“VIP 拒绝 k8s 流量——使用直接 IP”）-> 项目指令文件中的条目。
• 多步骤流程（例如，“轮换证书需要依次执行排空、替换、重新加载”）-> 专用操作手册章节。
• 有严格时间要求的部署前/后操作（例如，“Redis FLUSHALL 必须在部署后、流量重新接入前执行”）-> 操作手册顶部的检查清单，而不是埋在某个章节中。

3. 检查仓库的文档是否缺失或过于简略

如果仓库没有完善的文档，或者只有一份简略的 README.md，请在编辑任何内容之前，将此作为一项独立观察记录。

“过于简略”的示例：

• 没有 docs/ 目录，除了一份内容简略的 README.md 外也没有其他持久的 Markdown 文件
• README.md 只介绍了项目名称，没有设置、用法、API 或功能概览
• 文档反复因变更而过时，却没有合适的位置记录这些变更

处理方式：

• 向用户建议进行最精简的文档初始化，并将其作为可忽略的建议
• 建议应小而具体，例如：README.md、CHANGELOG.md、API.md、ROADMAP.md 或 docs/adr/
• 根据仓库类型调整建议，不要机械地套用通用文档目录结构
• 如果用户拒绝，继续使用现有的最佳文档，并说明其局限性

不要这样做：

• 不要自动创建一整套新文档
• 不要因文档初始化建议而阻碍常规文档维护

4. 更新受影响的文档

对于每份受影响的文档，先阅读，再进行针对性编辑。

应添加的内容：

• 代码中不易看出的注意事项（例如：“VIP 不接受 k8s 流量——请使用直接 IP”）
• 组件之间隐含的依赖关系（例如：“更新 SealedSecret 后必须重启 Pod”）
• 故障模式及其表现（例如：“PLEG unhealthy = 容器运行时冻结”）
• 已知问题的解决方法
• 运维限制（例如：“必须设置 serial: 1——移除后会同时更新所有节点”）
• 运维时序——如果某个操作必须在部署的特定步骤前后执行，请明确说明（例如：“必须在部署新镜像后、恢复流量前执行 Redis FLUSHALL”）
• IP、端口或主机名变更时的连接字符串和服务端点
• 决策及其理由
• 在读者预期的位置记录面向用户的功能新增、移除和注意事项
• 面向发布的变更：版本升级、升级说明、重大变更和迁移指引
• API.md、端点文档或仓库的权威 API 文档中的 API 行为变更

尚无文档时：

• 除非用户明确要求，否则不要从头创建一整套文档
• 如果项目文档不足，务必建议进行最精简的文档初始化
• 务必在项目指令文件（CLAUDE.md、AGENTS.md 或同类文件）中添加一条简要说明，记录相关注意事项或运维提示
• 如果项目完全没有指令文件，请告知用户，并建议创建一份文件，写入必要的注意事项。不要因此阻塞工作。

不要添加的内容：

• 预期读者无需了解的实现默认值，不论其是否与设置或正确使用有关
• 与读者任务无关的常规框架或平台细节
• 上游文档中已有的信息
• 临时状态（进行中的工作、已完成的一次性迁移步骤）
• 冗长的解释——每条注意事项用一行说明，只有解决方法不明显时才展开

5. 验证内部链接

编辑文档后，检查内部引用是否仍然有效：

优先使用仓库的 Markdown／链接检查工具检查受影响的文档。如果没有这类工具，可以使用此处提供的有限行内链接检查。该检查会根据源文档的路径解析链接路径，但不会验证标题锚点、引用式链接或嵌套 Markdown 语法。请明确传入已检查的文档路径。

python3 - README.md docs/guide.md <<'PYLINK'
from pathlib import Path
from urllib.parse import unquote, urlsplit
import re, sys
failed = False
for name in sys.argv[1:]:
    source = Path(name)
    for raw in re.findall(r'\[[^\]]*\]\(([^()]+)\)', source.read_text()):
        destination = raw.strip().split(' "', 1)[0].strip('<>')
        url = urlsplit(destination)
        if url.scheme or url.netloc or not url.path:
            continue
        if url.path.startswith('/'):
            print(f"SITE-ROOT LINK: {source}: {raw}; validate against site configuration")
            continue
        target = source.parent / unquote(url.path)
        if not target.exists():
            print(f"BROKEN LINK: {source}: {raw}")
            failed = True
sys.exit(1 if failed else 0)
PYLINK

修复每个 BROKEN LINK，并重新运行检查，直到退出码为 0。如果文件已移动，也要搜索指向这些文件的引用。对于不受支持的链接形式，应报告为未经检查，而非检查通过。

6. 审查项目指令文件中的冗余内容

更新后，认真审查项目的共享指令文件：

以下内容应删除或精简：

• 某个易错点已修复且不再适用（标记为已解决，然后在下次会话中删除）
• 信息现已写入操作手册（替换为指向该文档的链接）
• 某个章节重复描述源文件中的内容（例如，列出每个容器映像标签）
• 多个要点用不同说法表达了相同内容
• 一次性迁移或流程已彻底完成，且不会再次发生
• Renovate/CI 会自动维护的版本号

以下内容应保留：

• 如果没有文档，重新发现这些信息会浪费 15 分钟以上
• 跨组件交互，在任何单个文件中都无法看到全貌
• 与阅读代码后预期的行为相矛盾
• 因实际故障而总结出的“不要做 X”警告

大小目标：

• 共享指令文件：尽量控制在 40,000 个字符以内，并少于 500 行，即使工具允许更多内容也是如此。若超出，则将详细章节移至 docs/ 并添加链接。
• 单个章节：如果超过 30 行，考虑拆分为单独的文档。
• 编辑后检查大小：wc -c CLAUDE.md AGENTS.md 2>/dev/null

7. 同步配套指令文件

如果项目维护多个指令文件（例如 AGENTS.md 和特定工具的变体），更新后应保持内容一致。

编辑前，检查配套文件是符号链接、导入存根、生成文件还是独立文档。如果某个文件是指向规范文件的符号链接，只需编辑一次源文件；无需复制到同一文件。保留导入存根。对于生成的配套文件，编辑其源片段并运行仓库生成器。对于独立文件，只更新相应的共享指南，并保留针对目标工具的章节。检查最终差异；切勿为了同步而覆盖整个不同的配套文件。

默认情况下，指令文件通常会被 Git 忽略，除非项目有意将其纳入跟踪。 提交前检查 .gitignore 和历史记录。

8. 提交文档更改

编辑前记录初始的暂存状态和工作区脏状态。列出任务涉及的路径和代码块，包括计划新增的公开文档。将被忽略的文件和私有文件留在本地。仅通过指定路径或补丁暂存经审查的任务更改。

提交前，检查完整的暂存差异，并将其与初始索引对比。如果已有无关更改被暂存，应予以保留，并将任务更改留在未提交状态，除非用户已授权采用隔离方法。不要重置他人的索引，不要暂存所有有改动的 Markdown 文件，也不要仅仅因为更改了部分文档就提交整个索引。只有在提交属于请求范围时，才遵循仓库的提交流程。

快速参考：文件位置

文件	用途	是否提交？
README.md	仓库概览、设置、安装、用法	是
CHANGELOG.md	面向发行版的历史记录和重大变更	通常是
API.md	面向读者的 API 范围和契约说明	通常是
ROADMAP.md	公开或私有的计划/状态信息	视项目而定
FEATURES.md / FEATURESET.md	面向用户的功能清单	视项目而定
其他 *.md 文档	发行说明、状态文档、迁移说明、架构文档	视项目而定
AGENTS.md	跨工具的项目指令	视项目而定（检查 .gitignore）
特定工具的指令文件	项目维护特定 Agent/工具的配套指令时使用	视项目而定（检查 .gitignore）
docs/	项目文档（清单、操作手册、ADR、迁移说明、发行文档）	是

处理已弃用的功能

在会话期间，如果某项功能、服务或 API 被弃用：

• 保留文档条目，添加 [DEPRECATED] 前缀和日期，不要立即删除
• 在同一部分添加替代项，方便读者同时查阅
• 优先遵循仓库政策和用户明确提出的退役政策。 删除条目前，核实其发布版本、发布日期和经过时间是否符合条件；缺少引用不能缩短已承诺的宽限期。
• 仅当不存在任何政策时，在弃用公告发布后保留条目，直至两个完整的发布周期结束，然后只有在检查入站引用并保留仍需的迁移指南后才能删除。如果没有可用的发布或公告证据，则保留条目并报告尚未核实的内容。
• 破坏性变更应单独列出：说明发生了什么变化、用什么替代，以及任何迁移步骤

输出约定

完整约定请参阅 references/output-contract.md。

• 技能名称： UPDATE-DOCS
• 交付物类别： audits
• 模式： 始终启用。每次调用都必须遵循 references/output-contract.md 中的报告篇幅和证据规则。
• 交付物路径： docs/local/audits/update-docs/<YYYY-MM-DD>-<slug>.md
• 严重程度级别： P0 | P1 | P2 | P3 | info（参见共享约定）。

相关技能

• repo-audit - 并行编排 code-review、code-simplification、security-audit 和 update-docs。Update-docs 是四项检查之一。
• git - 用于提交消息规范和 PR 描述。Update-docs 涵盖项目文档文件；git 涵盖版本控制操作。

参考文件

• references/roadmap-freshness.md - 路线图漂移脚本和旁路日期检查；在步骤 1.5 中运行
• references/agent-hygiene.md - 返回前应用的跨领域检查（生成）
• references/output-contract.md - 每次调用的报告格式（生成）

---

常见错误

• 记录所有内容：避免重复罗列实现清单。只有当读者需要某项默认值来正确配置或使用产品时，才应将其写入文档。
• 过时的质量证据：README 中诸如“最近一次运行”“当前分数”或“39/39 个技能”的说法，必须在同一会话中对照源产物进行核实。
• 过时的注意事项：关于 3 个月前已修复漏洞的注意事项只会造成干扰。应定期清理。
• 假定每次合并都需要更新文档：PR 已合并是强烈的提示，但并不意味着必然需要更新文档。应检查是否真的存在文档偏差。
• 遗漏 README 以外的文档：API 变更应写入 API.md；发布差异应写入 CHANGELOG.md；功能偏差应写入功能文档。
• 过度记录迁移过程：迁移完成并经过核实后，将其精简为一句话，并删除逐步操作流程。
• 过早删除已弃用的文档：遵循仓库政策和用户明确提出的政策；没有引用的证据不能免除宽限期。只有在两者都未定义退役条件时，才使用上述两个完整发布周期的后备方案。
• 跳过路线图标题检查：如果路线图标注 Current: v0.27，而 HEAD 已是 v0.43，这是最明显的偏差迹象。判断路线图是否需要更新前，务必解析并比较标题。
• 将被 git 忽略的路线图视为范围之外：私人路线图最容易产生偏差，因为没人会公开反馈。对 find 命令列出的所有路线图运行新鲜度检查，而不只是已跟踪的路线图。

---

规则

• 记录变更，而非默认行为。 记录发生了什么变化、哪些内容失效，以及后续会话需要了解什么。
• 将已合并的 PR 和发布视为文档偏差的信号，而非保证。 编辑前先核实可能产生的影响。
• 优先选择合适的现有文档，而不是图方便选择最近的文档。 将 API 变更写入 API 文档，将发布变更写入更新日志，并将规划变更写入路线图或状态文档。
• 不要仅为改善文风而重写内容完善的文档。 只进行具有实际运维价值的修改。