syncdocs

Syncdocs：代码是文档中每项事实的依据

文档包含两类文字：代码可以证实或证伪的事实，以及只有人才能判断的文字。这项技能的核心理念是：**每项事实在写入前都要重新从代码中读取，除此之外不改动任何内容。**版本来自清单，命令来自脚本，目录树来自 ls，功能来自实现它的文件。文字内容、语气和章节顺序都由作者决定，而代码既无法证实也无法证伪的说法应交由相关人员处理，而不是写入修改。

本技能由负责维护它的工程师撰写，内容源自其在自己代码仓库中执行的文档检查；provenance.md 记录了相关信息。

何时使用

版本、依赖、脚本、结构或功能变更后，文档可能不再匹配时；发布前；或有人要求检查文档是否准确时。

调用方式	含义
/syncdocs	同步工作目录中的所有现有文档，生成报告，然后提交文档文件
/syncdocs check	仅验证并生成报告：不编辑，不提交
/syncdocs <path>	<path> 路径下的代码仓库

用户的要求优先于默认行为：“不要提交”“我想查看差异”或“只要告诉我”表示不提交，或完全不编辑，具体按用户要求执行。如果指定的代码仓库不存在，则从其公开 URL 克隆到临时目录；在评估场景中，该克隆操作和软件包注册表不属于外部服务。除非用户要求生成报告文件，否则保持非目标工作目录原样不动。

何时不要使用

用途	使用
编写变更日志或更新版本号	bumpv
按照项目惯例提交	commit
以文档为规范检查代码	code-audit
编写尚不存在的 README、CLAUDE.md 或指南	按需使用文档技能

架构

discover docs --> README.md, CLAUDE.md, AGENTS.md, docs/** (only what exists)
      |
ground truth  --> manifest + lockfile, scripts/targets/CI, ls, the implementing file
      |
compare       --> each claim: accurate | stale (code says X) | unverifiable
      |
sync          --> targeted edits to stale facts, the same fact equal in every file
      |
report        --> changed / verified accurate / flagged
      |
commit        --> doc files only, "docs: sync documentation with codebase state"

衔接点就是目标代码仓库本身：其清单决定版本，其脚本和目标决定命令，其目录决定目录树，而仓库自身的提交规范和变更日志维护者仍由 commit 和 bumpv 负责。这里没有 adaptation.md；本段就是对它的说明。

关键事实

1. 声明的版本范围不等于已安装版本。"next": "^16.2.0" 允许多个版本；锁文件会说明实际解析到哪个版本。文档若指定精确版本，应采用锁文件中的版本；若指定版本范围或主版本，则应采用清单中的内容（ground-truth.md）。
2. **只有代码仓库实际定义的命令，才是真实可用的命令。**如果没有 lint 脚本，npm run lint 就会在读者首次尝试时失败；只有脚本、目标或 CI 步骤确实存在，该命令才能保留。
3. **文档中的目录树和其他说法一样，也是一项断言。**目录可能在无人修改 README 的情况下发生变化，因此结构章节应根据 ls 和受版本控制的文件重新生成，绝不能依据文档自身的目录树。
4. **Agent 指令文件会被执行，而不只是阅读。**CLAUDE.md 和 AGENTS.md 会告知 Agent 要运行什么；其中过时的命令会在每次会话中执行，因此应优先检查这些文件，并保持内容精简。
5. **每个文件中的同一项事实都应有唯一值。**如果多个文档中都出现某个版本或命令，应在同一轮检查中全部同步；否则就应报告不一致。只同步部分内容会产生新的过时事实。
6. **没有清单的代码仓库仍有事实依据。**对于仅包含 Markdown 的代码仓库，最新的变更日志章节、受版本控制的文件和 Git 标签就是事实依据；变更日志只读取，绝不编辑。

硬性规则

事实依据来自代码，而不是文档或记忆。 每个写入的值都必须是在本次会话中从清单、锁文件、脚本、目标、CI 文件或 ls 中读取的。

只更改事实。 在原处精准修正过时事实；绝不改写文案、调整章节顺序、改变样式，或添加徽章、章节或功能。

绝不创建不存在的文档。 仅在 README.md、CLAUDE.md、AGENTS.md 和 docs/ 已存在时同步；如果缺少文件，在报告中提出，而不是创建文件。

绝不修改 CHANGELOG.md。 bumpv 会根据提交历史生成该文件；docs: 提交就是同步记录。

无法核实的说法必须标记，绝不默默保留或删除。 对于找不到对应文件、路由或标记的功能，或需要决策才能处理的移除项，都应列入报告，交由相关人员处理。

没有过时内容，就不编辑，也不提交。 说明文档准确无误后停止；不要为了凑出一次提交而做表面修改。

只提交文档文件；仅在用户未要求先审核时提交，并且不添加任何 AI 署名。 提交信息为 docs: sync documentation with codebase state，不得添加指名任何模型或工具的 Co-Authored-By: 署名行、生成者说明或会话链接；之后检查 git log -1 --format=%B。

快速开始

1. 列出已存在的文档，排除 .claude/ 等 Agent 文件夹和供应商副本，并完整阅读每份文档：syncing.md，“发现”。
2. 根据仓库自身的清单、脚本、目录树和实现文件确立事实依据：ground-truth.md。
3. 将每条事实性说法分类为准确、过时或无法核实，然后逐个文件在原处修正过时内容：syncing.md。
4. 报告已更改、已核实和已标记的内容，然后提交文档文件，或按用户要求停止：reporting.md。

参考目录

场景	触发关键词	参考文档
每条事实的来源	package.json、lockfile、pyproject.toml、Cargo.toml、go.mod、Makefile、justfile、CI、scripts、ls、声明范围、解析版本、无清单	ground-truth.md
编辑各份文档	README.md、CLAUDE.md、AGENTS.md、docs/、精准修改、文案、结构树、功能说法、跨文件一致性	syncing.md
告知用户的内容和提交方式	报告、已更改、已核实、已标记、检查模式、先审核、提交信息、署名	reporting.md
内容来源	来源、固定、刻意保留、添加	provenance.md

此内容属于 Timerise Skills 索引，该索引列出了相关的同级技能。