docs-sync-check

name	docs-sync-check
description	Ensure code and script changes keep functional-folder README files and in-file usage notes in sync, using manual self-check and bundled templates.
metadata	{"short-description":"Keep README and usage notes in sync after code changes"}

Docs Sync Check

Goal

在新增或修改代码、脚本、命令入口、产物路径时，同步维护该功能目录的 README.md 与脚本内“使用方法”说明，避免代码和说明脱节。

这个 skill 的重点不是“补一句文档”，而是把文档更新变成和代码改动同一轮交付的一部分。

When to use

• 用户要求新增、修改、重构代码或脚本。
• 新增或变更 .py、.sh、CLI 命令、关键参数、输入输出路径、生成产物位置。
• 移动文件、拆分功能目录、调整产物落盘位置。
• 更新会影响别人如何运行、理解或复用该功能。

When not to use

• 纯讨论、纯方案设计、纯代码审查且未落地修改。
• 只改注释、格式、空白、拼写且不影响运行方式。
• 仅修改二进制产物，且没有新增可执行入口或路径变化。

Required workflow

1. 先识别本次变更影响了哪些“功能主题”目录。
2. 对每个受影响目录检查 README.md 是否存在；不存在就创建。
3. 对每个新增或修改的 .py / .sh 文件检查是否有“使用方法”说明；没有就补上。
4. 如果运行方式、参数、输入输出、产物位置发生变化，README 和“使用方法”都必须同步更新。
5. 如果发生文件移动或目录重组，README 中的路径、命令、产物位置说明必须一起改。
6. 结束前做一次手动自检，并在最终回复中明确说明是否已同步 README 与“使用方法”。

Required README coverage

每个受影响功能目录的 README.md 至少应覆盖：

• 功能用途：这个目录解决什么问题。
• 输入：需要什么源数据、配置、参数。
• 输出：生成什么文件，默认写到哪里。
• 运行方式：最小可运行命令。
• 关键参数：只写真正影响行为的参数。
• 目录结构：脚本、数据、产物分别在哪。
• 最近变更：本次修改了什么，影响什么使用方式。

如果该目录本来已有更成熟的 README 结构，沿用原结构，不要强行改模板。

Required script usage coverage

每个新增或修改的 .py / .sh 文件都必须带“使用方法”说明。内容至少包括：

• 脚本用途。
• 运行命令。
• 关键参数或环境变量。
• 输入输出路径示例。

优先放在文件顶部附近，便于打开文件即可看到。保持简短，但必须可执行、可复现。

示例：

# 使用方法：
# python script.py --input data/input.json --output output/result.json
# 作用：读取输入数据并生成标准化结果。
# 关键参数：
#   --input   输入文件路径
#   --output  输出文件路径

# 使用方法：
# bash run_task.sh /path/to/input /path/to/output
# 作用：执行批处理并写出结果。
# 参数：
#   $1 输入目录
#   $2 输出目录

Decision rules

• 如果只是内部重构，但运行方式、参数、产物都没变：
  • 仍然检查 README 和“使用方法”是否依然准确。
  • 如果无需修改，在最终回复中明确说明“已检查，无需变更”。
• 如果只改测试文件或临时脚本：
  • 若这些文件会被人直接运行，也要补“使用方法”。
  • 若仅为内部测试且不会直接复用，可不扩写 README，但要确认不误导现有说明。
• 如果一个变更跨多个功能目录：
  • 每个目录分别维护自己的 README.md，不要把说明堆到无关目录。
• 如果新增产物目录：
  • README 必须写清产物位置、命名方式、是否可覆盖。

Prefer single source of truth

如果项目已有成熟 CLI 体系，优先让命令帮助本身成为事实来源，再把 README 指向它，而不是重复维护多份长篇命令说明。例如：

• Python argparse / typer / click 的 --help
• 由 CLI 自动生成的 README 片段
• 由文档站自动抽取的命令参考

当自动生成和手写说明并存时，以自动生成内容为准，README 只保留入口说明、示例和上下文。

Self-check before finishing

• 是否为每个受影响功能目录补齐或更新了 README.md
• 是否为每个新增/修改的 .py / .sh 补齐或更新了“使用方法”
• README 中的命令、路径、参数、产物位置是否与代码一致
• 若移动了文件，README 是否已同步新路径
• 最终回复中是否明确说明这两项检查结果

Final response contract

结束时要明确说明以下其一：

• 已同步更新相关 README.md 与脚本“使用方法”说明。
• 已检查相关 README.md 与脚本“使用方法”，本次无需修改。
• 本次未改代码/脚本，未触发该 skill。

Suggested automation

如果仓库对文档一致性要求较高，建议把这个 skill 与自动化一起使用：

• pre-commit：在提交前运行 Markdown / prose / link 检查。
• markdownlint-cli2：检查 README/Markdown 结构一致性。
• Vale：检查术语、语气和常见文案问题。
• lychee：检查文档链接失效。
• 对 CLI 项目，优先采用自动生成命令文档，而不是手写重复说明。

Bundled files

• templates/feature-readme.md：当功能目录缺少 README 时可直接作为起点。