---
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](./reference/doc-registry.md)（文档注册表）
3. 应用 [sync-rules.md](./reference/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](./reference/quality-check.md)):

#### 一致性验证

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

#### 链接完整性

- [ ] 所有内部链接可访问
- [ ] 文件路径正确

#### 结构完整性

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

#### 内容质量

- [ ] 无冗余信息
- [ ] 术语使用一致

---

## 🔧 核心工具集

### 1. 文档注册表 ([doc-registry.md](./reference/doc-registry.md))

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

### 2. 同步规则 ([sync-rules.md](./reference/sync-rules.md))

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

### 3. 质量检查清单 ([quality-check.md](./reference/quality-check.md))

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

### 4. 文档模板库 ([templates.md](./reference/templates.md))

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

---

## 📚 参考文档

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

---

## 💡 使用示例

### 示例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` 中的检查项