文档同步智能助手 V2.2
⚡ 快速开始
自动激活场景
本 skill 会在以下情况下自动激活：
-
用户明确请求："更新文档" / "同步文档"
-
完成功能开发："完成了数据导入功能" / "实现了KPI看板"
-
代码结构变更："修改了数据结构" / "新增了KPI字段"
-
重构代码："重构了计算逻辑" / "调整了API接口"
基本使用
用户: "我完成了多周导入功能,请更新相关文档"
Claude (使用 doc-syncer skill):
- 分析变更范围 → 识别到 F010_multi_week_import
- 读取现有文档 → F010/README.md
- 执行精准更新 → 更新技术实现和代码示例
- 自动验证质量 → 检查链接、版本号、一致性
- 报告完成状态 → 显示更新摘要
🎯 核心使命
解决六大文档管理痛点:
-
❌ 防止文档泛滥（无用文档堆积）
-
❌ 防止文档无结构（找不到文档）
-
❌ 防止文档之间无联系（信息孤岛）
-
❌ 防止文档与代码不一致（信息错误）
-
❌ 防止信息过载（重复冗余）
-
✅ 达到文档必要、无冗余、好理解、自动更新
📋 工作流程（四步法）
第1步: 智能分析变更范围
目标: 自动识别代码变更并确定需要更新的文档
操作:
-
读取用户提示或分析最近的代码变更
-
查阅 doc-registry.md（文档注册表）
-
应用 sync-rules.md（同步规则）
-
生成更新计划并征求用户确认
输出示例:
📊 变更分析结果: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 检测到: KPI计算逻辑变更 (src/domain/rules/kpi-calculator.ts)
需要更新的文档: ✅ 必须更新 (P0): • 开发文档/03_technical_design/core_calculations.md
⚠️ 建议检查 (P1): • 开发文档/01_features/F002_kpi_dashboard/README.md
📋 更新计划:
- 更新KPI公式描述
- 同步代码示例
- 验证文档链接
是否继续执行? (输入 "yes" 或提出修改建议)
第2步: 读取现有文档上下文
原则: 最小化读取，只获取必要的上下文
策略:
-
✅ 渐进式读取: 先读目录结构，再读具体章节
-
✅ 只读相关部分: 使用 offset/limit 精准定位
-
✅ 缓存已读内容: 避免重复读取
反模式（避免）:
-
❌ 一次性读取所有相关文档
-
❌ 读取整个文件（当只需要更新一个章节时）
-
❌ 重复读取相同内容
第3步: 精准执行文档更新
核心原则: 修改优于创建，局部优于全局
更新策略决策树
需要更新文档? ├─ 文档已存在? │ ├─ 是 → 使用 Edit 工具（精准修改） │ │ ├─ 只修改变更的章节 │ │ ├─ 保持现有结构 │ │ └─ 标注更新时间 │ │ │ └─ 否 → 检查是否真的需要新文档 │ ├─ 能合并到现有文档? → 使用 Edit 添加章节 │ └─ 必须新建? → 使用模板创建 (参考 templates.md) │ └─ 否 → 跳过更新
更新风格指南
必须遵守:
-
✅ 中文优先: 所有描述使用中文
-
✅ 代码示例: 包含实际可运行的代码片段
-
✅ 版本标注: 更新版本号和日期
-
✅ 链接完整: 确保所有内部链接有效
-
✅ 格式一致: 遵循现有文档的Markdown风格
禁止:
-
❌ 创建重复文档
-
❌ 删除历史信息（应移至archive/）
-
❌ 修改文档ID编号（如F001不能改为F015）
-
❌ 破坏现有文档结构
第4步: 自动验证与质量检查
验证清单 (参考 quality-check.md):
一致性验证
-
文档描述与代码实现一致
-
代码示例可以运行
-
版本号已更新
-
更新日期已标注
链接完整性
-
所有内部链接可访问
-
文件路径正确
结构完整性
-
遵循模板结构
-
章节编号连续
-
标题层级正确
内容质量
-
无冗余信息
-
术语使用一致
🔧 核心工具集
- 文档注册表 (doc-registry.md)
-
作用: 维护所有活跃文档的清单，防止文档泛滥
-
使用: 在第1步查阅，确定更新范围
- 同步规则 (sync-rules.md)
-
作用: 定义代码变更到文档更新的映射规则
-
使用: 在第1步应用，自动生成更新计划
- 质量检查清单 (quality-check.md)
-
作用: 确保文档质量和一致性
-
使用: 在第4步执行，输出验证报告
- 文档模板库 (templates.md)
-
作用: 提供标准化的文档模板
-
使用: 在第3步创建新文档时使用
📚 参考文档
-
文档注册表 - 活跃文档清单和健康度评分
-
同步规则 - 代码变更到文档更新的映射规则
-
质量检查 - 文档质量验证标准
-
文档模板 - 标准化文档模板库
-
项目参考手册 - 项目特定目录结构与原则
-
项目约定 - 项目级协作约定 (如果存在)
💡 使用示例
示例1：完成新功能后更新文档
用户输入:
"我完成了多维雷达图功能,代码在 src/components/features/multi-dimension-radar.tsx"
Skill 执行流程:
-
读取 sync-rules.md 识别出对应文档应为 F009/README.md
-
读取 doc-registry.md 确认 F009 是否存在
-
读取 src/components/features/multi-dimension-radar.tsx 提取关键逻辑
-
更新 F009/README.md 的"技术实现"章节
-
运行 quality-check.md 中的检查项