---
name: qshanx-docs-maintenance
description: "在任务改变了文档承载的事实、发现正文冲突，或用户要求“同步文档”“收尾”“准备交接”时，按影响同步现有文档。"
license: "MIT"
metadata:
  decimalai-skill-id: "dba4444b-7a4d-401f-bbc3-d88b1f1c0aed"
  decimalai-version-id: "6a752bb7-f57f-486f-ab5d-2ba33c98903a"
  decimalai-version: "1"
  decimalai-body-sha256: "3534d13ca6bfc321dfe540077180e19d35b6bd5c70e483368b6172720c02e502"
  decimalai-name: "qshanx/docs-maintenance"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "documentation"
  decimalai-source: "https://app.decimal.ai/s/qshanx-docs-maintenance@1/SKILL.md"
---
# 日常文档维护

让下一位使用者或开发者读到的说明与本次变化一致。只维护受影响的文档；只读任务只报告差异。

需要接入收尾时，由 `agent-entrypoints` 在项目共享入口配置以下约定，Skill 名替换为实际可读取路径，外部插件使用完整路径：

> 任务改变了文档承载的行为、接口、路径、需求或需持续交接的风险时，按 docs-maintenance 同步受影响主记录；没有这些变化则直接交付，只读任务只报告差异。

“一轮”指完整任务，维护本身不递归触发。入口约定由 Agent 执行，Skill 文件本身不会自动运行，也不自行安装 Hook。

## 1. 确定这次改变了什么

结合本轮对话、实际 diff 和确认材料，说清**什么行为变了、影响谁、依据是什么**，不只列改过的文件。例如“订单取消时限从 30 分钟改为 60 分钟”，会影响用户说明与验收条件。由模块变更流程进入时，复用任务基线、影响清单和回归结果。

区分已确认需求、实际实现、上线状态与验证结果；测试失败或未运行不能写成已验收。未改变文档事实的内部修复、样式调整或问答，在回复说明依据后结束，不为收尾运行全量审计或创建记录。缺少 Git 基线时依据现有材料核对，标出无法确定的旧状态。

## 2. 找到受影响的说明，就地更新

先复用本轮有效影响分析：范围、版本及未提交变化一致，且包含该范围要求的审计结果；出现新变化、失败或未覆盖项时，不沿用旧结论，按 `skills/engineering/change-impact/SKILL.md` 的“按事实核对文档”补查。它提供候选与依据，本 Skill 判断并修改正文。沿项目入口补查相关说明；零命中不等于无影响。

对每处说明判断：**下一位读者照着做，是否还会得到文档承诺的结果？** 根据变化定位现有主记录：

| 本次变化 | 重点核对 |
|---|---|
| 功能、使用方式或操作命令 | README、使用说明及操作文档中的步骤和预期结果 |
| 接口、配置或数据结构 | 契约、接入说明和调用示例；旧用法是仍受支持，还是已失效？契约写法沿用 `contract-first` |
| 文件位置或模块关系 | MAP 和相关引用；架构变化交给 `architecture-docs` |
| 需求、决策或稳定约定 | PRD／Spec、ADR 或项目入口；分别按 `product-evolution`、`domain-modeling`、`agent-entrypoints` 处理 |
| 需持续交接的风险、阻塞或关键验证状态变化 | STATUS 对应条目；普通测试通过只在回复说明，任务排期仍留 Tracker |
| 值得追溯的重要事件 | 沿用项目约定的历史主源，保留原因、确认依据和相关版本；已有 LOG 按约定追加，否则复用 PR／Issue／决策或能承载这些信息的 Git 记录，不另建流水，保留既有历史 |

沿用项目实际路径，不为凑齐表格创建文件。MAP 只管导航事实，不记录每次改动；LOG 只保留重要历史，不复制 MAP 或普通测试结果。小任务可以零文档变更；确有事实变化才修改主记录和必要引用；不默认联动写入 STATUS、LOG、产品阶段和验收记录。同一结论在回复或既有记录留一份可追溯证据，其他位置需要时引用；项目明确要求的历史或门禁仍执行。在获准范围内修改过时条目、失效引用和重复的现役正文，保留条件、例外和必要案例。

例如，接口字段改名后，更新当前接入指南和调用示例；历史日志中的旧字段名可以保留。实现与已确认需求冲突时分别记录依据，不能直接把需求改成代码现状；主源不明或无法裁决时列出待确认项。

## 3. 验证更新，并交代剩余差异

先检查受影响的路径、引用与正文，再运行项目已有相关检查；示例或其依赖变化时按下节验证。旧结论依赖的行为或条件变化后须复验，未运行标待复验。

### 示例与命令怎么验证

本轮修改了示例，或改变了它依赖的接口、参数、配置、环境时，再验证相关示例与命令：

- 从文档原文取示例，确认适用版本、工作目录、依赖和预期结果，复用现有测试或契约检查；说明占位符替换，不只验证手写副本。
- 可安全执行的内容在隔离环境运行，同时检查退出码和实际输出。片段缺少前置条件时说明检查限制；发布、删除、付费或使用凭据仍须在已有授权范围内，不全量执行文档代码块。
- 失败时区分过期示例、实现错误和环境缺失，按已确认需求修复本轮问题后复跑，保留原验收要求。历史示例保留当时语义，不当作当前指南执行。

接口样例的失败、修复与复验见[可复跑案例](../../engineering/change-impact/examples/interface-change.md#示例与命令验证)。

完成时在回复或已有测试记录中简述：已同步内容（或无需同步的理由）、待确认差异、失败及未验证范围；附受检版本、文档位置和实际命令／环境、预期与结果。本次受影响的主记录和查到的引用均应已处理；未解决项写清位置、依据和下一步，并标为部分完成。无需另建报告或台账，脚本通过不代表内容全部一致。