Back to Details

actualizar-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Updater

文档更新器

Goal

目标

Documentation goes stale because nobody updates it when the code changes. This skill runs at the end of any implementation and closes that gap in the same change: it reads what the diff changed, finds every document that now says something false or incomplete because of it, and proposes the exact edits — each one backed by evidence from the code.
It is diff-scoped on purpose. It does not audit the whole project (that is 
auditar-drift
); it answers one question: "what did this change make outdated?"
代码发生变化时无人更新文档，导致文档逐渐过时。此 skill 会在任何实现结束时运行，并在同一次变更中弥补这一缺口：读取 diff 所涉及的内容，找出所有因该变更而变得错误或不完整的文档，并提出精确的编辑建议——每项建议均有代码证据支持。
有意将范围限定在 diff 内。它不会审计整个项目（那是 
auditar-drift
的职责），它只回答一个问题：“此次变更使哪些内容过时？”

Definition: a "puerta"

定义：“入口”

A puerta (door) is any point through which someone — a person or another system — asks the system for something: an HTTP route, a screen and its actions, a CLI command, the public functions of a module, or the tools/intents of an agent. The industry calls it an interface or an API. A documented door answers three questions: what it receives, what it returns, and how it fails (in business language).
入口（puerta）是指个人或其他系统向系统请求某项内容的任何交互点：HTTP 路由、界面及其操作、CLI 命令、模块的公开函数，或 Agent 的工具/意图。业界通常将其称为 interface 或 API。一个有文档的入口需要回答三个问题：接收什么、返回什么，以及如何失败（使用业务语言表述）。

Input

输入

  • The change to document. By default: everything on the current branch against its base (
    git merge-base HEAD <main branch>
    ), plus uncommitted changes. If the user names a commit range, a PR, or specific files, use that instead.
  • The project's existing documentation — discovered, not assumed (step 2).
If there is no git history and the user gives no scope, ask what changed before proceeding.
  • 需要记录文档的变更。默认范围：当前分支相对于其基准分支的全部变更（
    git merge-base HEAD <main branch>
    ），以及尚未提交的变更。如果用户指定了 commit 范围、PR 或特定文件，则改用该范围。
  • 项目现有的文档——通过实际发现获取，而非预先假设（步骤 2）。
如果没有 Git 历史记录且用户未指定范围，请先询问具体变更，再继续执行。

Workflow

工作流

1. Understand the change

1. 理解变更

List the changed files and read the diff. Summarize the change in business terms in 1-3 lines. Then classify what kind of things changed:
  • Doors: a door was added, removed, renamed, or its inputs, outputs, or errors changed.
  • How to run it: commands, scripts, dependencies, required environment variables, ports.
  • Structure: new or moved components, modules, folders, data model, integrations.
  • Rules for agents: conventions or paths that 
    AGENTS.md
    /
    CLAUDE.md
    describe.
If the change is purely internal (no door, command, config, or structure changed), say so and stop: "no documentation impact" is a valid, useful result.
列出发生变更的文件并阅读 diff。用 1-3 句话从业务角度概括变更。
然后对变更内容进行分类：
  • 入口：新增、删除、重命名了某个入口，或其输入、输出、错误发生变化。
  • 运行方式：命令、脚本、依赖项、必需的环境变量、端口。
  • 结构：新增或移动了组件、模块、目录、数据模型、集成。
  • Agent 规则：
    AGENTS.md
    /
    CLAUDE.md
    中描述的约定或路径。
如果变更纯粹属于内部变更（未新增、删除或修改入口、命令、配置或结构），请明确说明并停止：“无文档影响”也是有效且有用的结果。

2. Find the documents that talk about it

2. 查找与其相关的文档

Inventory the documentation that actually exists in the project. Typical candidates: 
README.md
, 
AGENTS.md
, 
CLAUDE.md
, 
docs/puertas.md
, 
docs/openapi.yaml
(or any OpenAPI/Swagger file), 
TECH-DESIGN.md
, 
docs/**
, 
.env.example
, 
CHANGELOG.md
, PR templates.
For each change from step 1, search those documents for the places that describe it. Use the code-intelligence tooling the environment provides (code graph, IDE index) for the code side before broad grep.
盘点项目中实际存在的文档。常见候选项包括： 
README.md
、
AGENTS.md
、
CLAUDE.md
、
docs/puertas.md
、
docs/openapi.yaml
（或任何 OpenAPI/Swagger 文件）、
TECH-DESIGN.md
、
docs/**
、
.env.example
、
CHANGELOG.md
、PR 模板。
对于步骤 1 中的每项变更，在这些文档中搜索描述其相关内容的位置。对于代码侧，应先使用环境提供的代码智能工具（代码图谱、IDE 索引），然后再进行广泛 grep。

3. Decide what each document needs

3. 判断每份文档需要如何处理

For each affected spot, classify:
  • DESACTUALIZADO — the document states something the code no longer does.
  • FALTA — the change added something the document should cover and doesn't (for example, a new door missing from 
    docs/puertas.md
    or from the OpenAPI file).
  • SIN IMPACTO — mentioned, but still true. Count these; don't list them.
If a door changed in a way that breaks whoever already uses it (a required input added, a field renamed or removed, an error changed), flag it as CAMBIO QUE ROMPE and say so explicitly — it must be announced and versioned, not silently documented.
对于每个受影响的位置，将其归类为：
  • 已过时——文档中的内容已不再符合代码。
  • 缺失——变更新增了文档应当涵盖但尚未记录的内容（例如，
    docs/puertas.md
    或 OpenAPI 文件中缺少新入口）。
  • 无影响——虽然有所提及，但内容仍然正确。仅统计即可，不要列出。
如果入口的变更会导致现有使用者无法正常使用（例如新增必需输入、重命名或删除字段、改变错误行为），请将其标记为破坏性变更，并明确说明—— 必须对此进行公告和版本管理，不能仅在文档中静默记录。

4. Decisions are not documentation

4. 决策不属于文档

PRD.md
, user stories (HU files), and ADRs record decisions, not descriptions. Never edit them. If the change contradicts one of them, report it as DECISIÓN A REVISAR with the quote and the code evidence, and suggest the human either update the decision or run 
auditar-drift
.
PRD.md
、用户故事（HU 文件）和 ADR 记录的是决策，而不是功能描述。绝不修改这些文件。如果变更与其中某项决策冲突，请将其报告为待审查决策，并附上相关引用和代码证据，同时建议人工更新该决策或运行 
auditar-drift
。

5. Propose, show the diff, wait

5. 提出建议、展示 diff、等待批准

Present a table before writing anything:
DocumentoSecciónEstadoQué cambiaEvidencia (archivo:línea)
Then show the proposed diff of each document. Wait for explicit approval. The user may approve all, some, or ask for changes.
Rules for the edits:
  • Only touch the parts affected by this change. Do not rewrite, reorganize, or restyle the rest.
  • Keep each document's existing language, tone, and format.
  • Every fact comes from the code with 
    archivo:línea
    . What cannot be verified goes as 
    NO VERIFICADO
    . Never invent fields, errors, commands, or URLs.
  • Never modify code. If documenting reveals a code bug, report it; don't fix it.
在写入任何内容之前，先展示下表：
文档章节状态要变更的内容证据（文件:行）
然后展示每份文档的建议 diff。**等待明确批准。**用户可以批准全部建议、批准其中一部分，或要求修改。
编辑规则：
  • 仅修改受此次变更影响的部分。不要重写、重组或重新设置其余内容的样式。
  • 保持每份文档现有的语言、语气和格式。
  • 每项事实都必须来自代码，并附有 
    文件:行
    。无法验证的内容必须标为 
    未验证
    。绝不虚构字段、错误、命令或 URL。
  • 绝不修改代码。如果在记录文档时发现代码缺陷，请报告该问题，不要修复它。

6. Apply and check

6. 应用并检查

Apply only the approved edits. If an OpenAPI file was edited and a validator is available in the project (or via 
npx @redocly/cli lint <file>
), run it and report the result; if it can't run, say it was not validated.
仅应用已批准的编辑。如果修改了 OpenAPI 文件，并且项目中有可用的验证器（或可通过 
npx @redocly/cli lint <file>
运行），请执行验证并报告结果；如果无法运行，请说明未经验证。

Output

输出

  • The approved documentation edits, applied in the working tree (same branch as the code change).
  • A short final report:
    • Change summarized in business terms.
    • Documents updated (with what changed in each).
    • CAMBIO QUE ROMPE
      , 
      DECISIÓN A REVISAR
      , and 
      NO VERIFICADO
      items, if any.
    • A suggested line for the PR description: "Documentación actualizada: <files>".
  • 已批准的文档编辑，并将其应用到工作区（与代码变更位于同一分支）。
  • 一份简短 final 报告：
    • 从业务角度概括变更。
    • 已更新的文档，以及每份文档的变更内容。
    • 破坏性变更
      、
      待审查决策
      和
      未验证
      事项（如有）。
    • PR 描述的建议文本：“文档已更新：<files>”。

Quality Gate

质量关卡

Before returning, silently check:
  • Every edit traces to a specific change in the diff — nothing outside the change's scope was touched.
  • Every documented fact cites 
    archivo:línea
    or is marked 
    NO VERIFICADO
    .
  • New doors were actively looked for, not only modified ones — a door missing from the docs is the easiest gap to skip.
  • No code, PRD, HU, or ADR file was modified.
  • Nothing was written before the user approved it.
返回前，在内部静默检查：
  • 每项编辑都可追溯到 diff 中的具体变更——没有修改变更范围之外的内容。
  • 每项文档事实均引用了 
    文件:行
    ，或已标记为 
    未验证
    。
  • 已主动查找新增入口，而不只是检查被修改的入口——文档中遗漏新入口是最容易漏掉的问题。
  • 未修改任何代码、PRD、HU 或 ADR 文件。
  • 在用户批准前没有写入任何内容。