doc-syncer

name	doc-syncer
description	代码变更后自动同步开发文档。支持功能文档、技术设计、决策记录的智能更新。当用户提到更新文档、同步文档、完成功能、修改数据结构或新增KPI时激活。
version	2.2.0
allowed-tools	Read, Edit, Write, Grep, Glob

文档同步智能助手 V2.2

⚡ 快速开始

自动激活场景

本 skill 会在以下情况下自动激活：

• 用户明确请求："更新文档" / "同步文档"
• 完成功能开发："完成了数据导入功能" / "实现了KPI看板"
• 代码结构变更："修改了数据结构" / "新增了KPI字段"
• 重构代码："重构了计算逻辑" / "调整了API接口"

基本使用

用户: "我完成了多周导入功能,请更新相关文档"

Claude (使用 doc-syncer skill):
1. 分析变更范围 → 识别到 F010_multi_week_import
2. 读取现有文档 → F010/README.md
3. 执行精准更新 → 更新技术实现和代码示例
4. 自动验证质量 → 检查链接、版本号、一致性
5. 报告完成状态 → 显示更新摘要

---

🎯 核心使命

解决六大文档管理痛点:

1. ❌ 防止文档泛滥（无用文档堆积）
2. ❌ 防止文档无结构（找不到文档）
3. ❌ 防止文档之间无联系（信息孤岛）
4. ❌ 防止文档与代码不一致（信息错误）
5. ❌ 防止信息过载（重复冗余）
6. ✅ 达到文档必要、无冗余、好理解、自动更新

---

📋 工作流程（四步法）

第1步: 智能分析变更范围

目标: 自动识别代码变更并确定需要更新的文档

操作:

1. 读取用户提示或分析最近的代码变更
2. 查阅 doc-registry.md（文档注册表）
3. 应用 sync-rules.md（同步规则）
4. 生成更新计划并征求用户确认

输出示例:

📊 变更分析结果:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
检测到: KPI计算逻辑变更 (src/domain/rules/kpi-calculator.ts)

需要更新的文档:
✅ 必须更新 (P0):
   • 开发文档/03_technical_design/core_calculations.md

⚠️ 建议检查 (P1):
   • 开发文档/01_features/F002_kpi_dashboard/README.md

📋 更新计划:
   1. 更新KPI公式描述
   2. 同步代码示例
   3. 验证文档链接

是否继续执行? (输入 "yes" 或提出修改建议)

---

第2步: 读取现有文档上下文

原则: 最小化读取，只获取必要的上下文

策略:

• ✅ 渐进式读取: 先读目录结构，再读具体章节
• ✅ 只读相关部分: 使用 offset/limit 精准定位
• ✅ 缓存已读内容: 避免重复读取

反模式（避免）:

• ❌ 一次性读取所有相关文档
• ❌ 读取整个文件（当只需要更新一个章节时）
• ❌ 重复读取相同内容

---

第3步: 精准执行文档更新

核心原则: 修改优于创建，局部优于全局

更新策略决策树

需要更新文档?
├─ 文档已存在?
│  ├─ 是 → 使用 Edit 工具（精准修改）
│  │      ├─ 只修改变更的章节
│  │      ├─ 保持现有结构
│  │      └─ 标注更新时间
│  │
│  └─ 否 → 检查是否真的需要新文档
│         ├─ 能合并到现有文档? → 使用 Edit 添加章节
│         └─ 必须新建? → 使用模板创建 (参考 templates.md)
│
└─ 否 → 跳过更新

更新风格指南

必须遵守:

1. ✅ 中文优先: 所有描述使用中文
2. ✅ 代码示例: 包含实际可运行的代码片段
3. ✅ 版本标注: 更新版本号和日期
4. ✅ 链接完整: 确保所有内部链接有效
5. ✅ 格式一致: 遵循现有文档的Markdown风格

禁止:

1. ❌ 创建重复文档
2. ❌ 删除历史信息（应移至archive/）
3. ❌ 修改文档ID编号（如F001不能改为F015）
4. ❌ 破坏现有文档结构

---

第4步: 自动验证与质量检查

验证清单 (参考 quality-check.md):

一致性验证

• 文档描述与代码实现一致
• 代码示例可以运行
• 版本号已更新
• 更新日期已标注

链接完整性

• 所有内部链接可访问
• 文件路径正确

结构完整性

• 遵循模板结构
• 章节编号连续
• 标题层级正确

内容质量

• 无冗余信息
• 术语使用一致

---

🔧 核心工具集

1. 文档注册表 (doc-registry.md)

• 作用: 维护所有活跃文档的清单，防止文档泛滥
• 使用: 在第1步查阅，确定更新范围

2. 同步规则 (sync-rules.md)

• 作用: 定义代码变更到文档更新的映射规则
• 使用: 在第1步应用，自动生成更新计划

3. 质量检查清单 (quality-check.md)

• 作用: 确保文档质量和一致性
• 使用: 在第4步执行，输出验证报告

4. 文档模板库 (templates.md)

• 作用: 提供标准化的文档模板
• 使用: 在第3步创建新文档时使用

---

📚 参考文档

• 文档注册表 - 活跃文档清单和健康度评分
• 同步规则 - 代码变更到文档更新的映射规则
• 质量检查 - 文档质量验证标准
• 文档模板 - 标准化文档模板库
• 项目参考手册 - 项目特定目录结构与原则
• 项目约定 - 项目级协作约定 (如果存在)

---

💡 使用示例

示例1：完成新功能后更新文档

用户输入:

"我完成了多维雷达图功能,代码在 src/components/features/multi-dimension-radar.tsx"

Skill 执行流程:

1. 读取 sync-rules.md 识别出对应文档应为 F009/README.md
2. 读取 doc-registry.md 确认 F009 是否存在
3. 读取 src/components/features/multi-dimension-radar.tsx 提取关键逻辑
4. 更新 F009/README.md 的"技术实现"章节
5. 运行 quality-check.md 中的检查项