文档同步

📌 Skill 基础信息

• Skill 名称：docs-sync
• 简称：文档同步
• 来源：社区第三方（开发者 reblocke）
• 运行宿主：仅限 Claude-Code CLI 运行
• 核心定位：在代码行为、配置、验证逻辑、公共术语或工作流命令变更时，自动检测并同步更新相关文档，确保代码与文档的一致性。

🧩 内部核心组成

该 Skill 主要通过规则约束和文档检测逻辑实现核心功能，不涉及子 Agent 或复杂命令集。其内部运作包含以下组成部分：

1. 文档检测范围

自动扫描以下文档：

• README.md
• docs/DECISIONS.md
• docs/ 目录下所有相关文档
• 任何架构决策记录（ADRs）

2. 规则约束

• 同步更新规则：当公共行为、命令、假设或验证逻辑发生变化时，必须在同一变更中更新文档。
• 决策记录规则：持久化决策需记录于 docs/DECISIONS.md 或新建 ADR，禁止仅隐藏在聊天记录中。
• 文档简洁性规则：文档需保持简洁和可操作性，明确描述变更内容、原因、运行方式及剩余未覆盖范围。
• 历史保护规则：禁止重写无关文档或修改历史决策，仅允许添加带日期的补充说明。

🛠 安装与启用方式

安装步骤

1. 通过以下命令安装（需提前配置好 Claude-Code CLI 环境）：

```bash

skills install --user reblocke/stewart-light

```

1. 安装后，Skill 将自动集成到 Claude-Code CLI 中，无需额外配置或启动命令。

前置依赖

• 需已安装并配置 Claude-Code CLI
• 本地 Git 仓库环境（用于检测文档变更）

📋 标准工作流

1. 用户输入指令：用户在 Claude-Code CLI 中执行代码变更相关操作。
2. 自动触发检测：Skill 检测到代码行为、配置或工作流命令发生变更。
3. 文档扫描：自动扫描仓库中的 README.md、docs/DECISIONS.md、docs/ 目录下的文档及所有 ADRs。
4. 变更分析：识别需要更新的文档内容，确保与代码变更保持一致。
5. 文档更新建议：提示用户需同步更新哪些文档，并提供更新指导（如保持简洁、记录决策等）。
6. 用户确认执行：用户根据提示完成文档更新，确保变更的完整性。

⚠️ 关键限制、缺陷、注意事项

• 平台限制：仅支持 Claude-Code CLI，无法在其他 Agent 工具（如 Cursor、MCP、OpenAI Agent）中运行。
• 项目类型适配：最适合代码库文档需要与代码严格同步的项目（如开源库、工具链、API 服务）；不适合文档与代码关联性弱的项目（如纯前端页面、静态内容网站）。
• 生产环境适用性：适用于开发和生产环境，但需团队遵循文档更新纪律，否则无法发挥最大价值。
• 已知坑点：

- 依赖本地 Git 仓库检测，非 Git 项目无法使用。

- 无法自动修改历史决策文档，仅支持提示用户添加补充说明。

• Token 消耗：无额外 Token 消耗，仅依赖本地文件扫描和规则检查。

✅ 适用场景 & ❌ 不适合场景

✅ 适用场景

• 需要严格保持代码与文档一致性的 开源项目 或 内部工具库。
• 团队遵循 决策记录规范（如 ADR 模式）的项目。
• 频繁变更公共 API、工作流命令或验证逻辑的 后端服务 或 CLI 工具。

❌ 不适合场景

• 文档与代码关联性弱的项目（如 静态博客、宣传页面）。
• 无需决策记录或文档同步的 简单脚本 或 一次性项目。
• 使用 非 Git 版本控制 或 无文档规范 的团队。