---
name: docs-management
version: 1.0.0
last_updated: 2026-04-08
repository: https://github.com/312362115/claude
description: >
  项目知识库引擎：持续维护 docs/ 目录作为活的知识库。
  灵感来源：Karpathy LLM Wiki — LLM 不只是写文档，而是持续维护知识库。
  五个核心操作：Ingest（摄入新信息）、Query（检索知识）、Lint（健康检查）、Index（索引维护）、Synthesize（聚合全局视图）。
  触发词：文档检查、清理文档、文档索引、docs 整理、知识库、文档过期了吗、架构文档、用户手册。
  触发场景：task-manager 标 done 时自动触发 Ingest、定期 Lint 健检、用户查询项目历史、
  task-finish 提醒后触发 Synthesize 更新 architecture/ 或 user-guide/。
  即使用户没有说"文档管理"，只要涉及 docs/ 目录的整理/检查/更新，都应触发此技能。
---

# 项目知识库引擎（Docs Management）

> "维护知识库最累的不是阅读和思考，是记账——交叉引用、一致性维护。这正是 LLM 擅长的。"
> — Karpathy, LLM Wiki

---

## 三层架构

```
Raw Sources（原始素材）  →  代码、git log、会议记录、外部文档
Wiki（知识库）           →  docs/ 目录下所有结构化文档
Schema（规则）           →  CLAUDE.md 中的文档规范
```

---

## 四个核心操作

### 操作 1：Ingest（摄入）

> 新信息进来时，不只是新建文件，而是找到已有文档合并更新。

**触发时机**：
- task-manager 标 done 时（复盘完成后自动触发）
- 新的设计决策产生时
- 外部信息需要整合到项目文档时

**执行流程**：

```
新信息产生
  │
  ├─ 搜索 docs/ 中是否有相关文档
  │   ├─ 有 → 更新已有文档，合并新信息
  │   └─ 无 → 创建新文档
  │
  ├─ 更新 docs/ 内相关交叉引用
  │
  └─ 更新 INDEX（如有）
```

**示例**：
- task-finish 产出复盘 → 写入 `docs/decisions/`，同时检查对应的 spec 是否需要标注"方案已执行，实际偏差见 decisions/xxx"
- 发现新的最佳实践 → 更新 `docs/guides/` 相关指南

### Ingest 中的 spec 偏差处理

> spec 标 done 时必须反映最终实现，但不是所有偏差都需要同样的处理方式。

```
偏差判断
  │
  ├─ 细节偏差（字段名调整、参数变更、实现细节微调）？
  │   └─ 直接更新 spec 中的技术方案章节
  │
  ├─ 方案偏差（换了实现路径，但目标不变）？
  │   └─ 更新 spec 技术方案 + 在决策章节补注"实际执行偏差及原因"
  │
  └─ 方向偏差（目标或范围发生了变化）？
      └─ 写 decision 记录完整复盘，spec 中标注"已被 decisions/xxx 覆盖"
```

### 操作 2：Query（查询）

> docs/ 是项目的可查询知识库，不是文件堆。

**触发时机**：
- 用户问"这个模块之前怎么设计的？"
- 用户问"上次类似问题怎么解的？"
- task-start 对焦阶段检索历史经验

**执行流程**：

```
查询请求
  │
  ├─ 在 docs/ 中搜索相关文档
  │   ├─ specs/ — 设计方案
  │   ├─ decisions/ — 踩坑记录和经验
  │   ├─ plans/ — 历史开发计划
  │   ├─ tests/ — 测试用例
  │   └─ guides/ — 开发指南
  │
  ├─ 综合相关文档给出回答
  │
  └─ 如果回答有价值且不在现有文档中 → Ingest 回 wiki
```

### 操作 3：Lint（健康检查）

> 定期体检，防止文档腐烂。

**触发时机**：
- 用户主动要求检查
- 大批量代码改动后
- 定期维护

**检查清单**：

| # | 检查项 | 怎么查 | 问题示例 |
|---|--------|--------|---------|
| 1 | **引用有效性** | 文档中引用的文件路径是否存在 | spec 引用了已删除的文件 |
| 2 | **进度一致性** | plan 的 checklist 和实际代码是否一致 | plan 说"待做"但代码已完成 |
| 3 | **INDEX 同步** | INDEX.md 和实际文件是否对得上 | INDEX 有但文件已删 |
| 4 | **跨文档一致** | plan 引用的 spec 是否存在 | plan 指向不存在的 spec |
| 5 | **状态同步** | backlog 状态和实际进度是否匹配 | backlog open 但 plan 已全部完成 |
| 6 | **孤立文档** | 有没有不被任何 INDEX 或文档引用的文件 | 遗忘的旧 spec |
| 7 | **过期内容** | 文档描述的代码结构是否还存在 | spec 说"改 src/old.ts"但该文件已重命名 |
| 8 | **全局视图同步** | architecture/ 和 user-guide/ 的 INDEX 和实际子文档是否一致 | INDEX 列了但文件不存在、新模块有 spec 但 architecture/ 没收录 |
| 9 | **记忆巡检** | memory 中的条目是否仍然有效 | feedback 引用的模块已删除、project 信息已过期 |

**输出格式**：

```markdown
## Docs 健康检查报告 — YYYY-MM-DD

### 概况
- 扫描目录：docs/
- 文档总数：X 个
- 发现问题：X 个

### 问题清单

| # | 级别 | 文件 | 问题 | 建议 |
|---|------|------|------|------|
| 1 | 高 | plans/xxx.md | 引用的 spec 不存在 | 更新引用或补建 spec |
| 2 | 中 | specs/xxx.md | 引用的文件路径 src/old.ts 已不存在 | 更新路径 |
| 3 | 低 | backlog/xxx.md | 状态 open 但关联 plan 已全部完成 | 更新为 done |
```

### 操作 4：Index（索引维护）

> 索引是知识库的入口，必须和实际内容同步。

**维护对象**：
- `docs/backlog/INDEX.md` — 需求索引（已有，由 task-manager 维护）
- `docs/decisions/INDEX.md` — 经验索引（待建，按时间倒序）

**INDEX 更新时机**：
- 新建文档后
- 文档状态变更后
- Lint 发现不一致后

---

### 操作 5：Synthesize（聚合）

> 从碎片文档中维护全局视图索引。不是写长文档，是保持索引准确。

**维护对象**：

| 目录 | INDEX.md 的职责 | 子文档 |
|------|----------------|--------|
| `docs/architecture/` | 模块列表、模块间关系、核心数据流概览 | 每个模块一份架构文档 |
| `docs/user-guide/` | 功能目录、快速入门导航 | 每个功能/模块一份用户指南 |

**触发时机**：

| 触发场景 | 操作 | token 成本 |
|---------|------|-----------|
| 用户手动要求 | 全量：读所有相关 spec/decision，重建 INDEX | 高 |
| task-finish 提醒后用户确认 | 增量：只读本次变更涉及的模块，更新对应子文档和 INDEX | 低 |
| Lint 发现 INDEX 和实际文件不一致 | 修复：对齐 INDEX 和实际文件列表 | 极低 |

**执行流程**：

```
触发 Synthesize
  │
  ├─ 全量模式（首次生成 / 用户要求重建）
  │   ├─ 扫描 docs/specs/ 和 docs/decisions/ 提取模块列表
  │   ├─ 每个模块生成/更新 architecture/<模块名>.md
  │   ├─ 生成 architecture/INDEX.md（模块导航 + 关系概览）
  │   └─ user-guide 同理
  │
  └─ 增量模式（单次改动后）
      ├─ 只读本次涉及的 spec/decision
      ├─ 判断是否涉及新模块 / 模块间关系变更
      │   ├─ 是 → 更新对应子文档 + INDEX
      │   └─ 否 → 跳过
      └─ 完成
```

**INDEX.md 格式示例**：

```markdown
# 系统架构

## 模块概览
| 模块 | 职责 | 文档 |
|------|------|------|
| auth | 认证与会话管理 | [auth.md](auth.md) |
| payment | 支付与账单 | [payment.md](payment.md) |

## 模块间关系
- auth → payment：支付前需要认证
- ...（或引用 docs/assets/ 中的架构图）
```

**和 Ingest 的区别**：
- Ingest：一条新信息 → 归档到一个文档（一对一）
- Synthesize：多个文档 → 聚合成索引和全局视图（多对一）

---

## 与其他 skill 的关系

```
task-finish（复盘产出）→ docs-management.Ingest（整合到知识库）
task-finish（提交时）  → 提醒：是否需要 Synthesize（涉及新模块/模块间交互变更？）
task-start（对焦阶段）→ docs-management.Query（检索历史经验）
task-manager（需求管理）→ docs-management.Index（维护 backlog INDEX）

定期 / 用户主动 → docs-management.Lint（健康检查）
用户主动 / Lint 发现不一致 → docs-management.Synthesize（聚合全局视图）
```

**docs-management vs writing**：
- writing：**生产**文档（从无到有写出来）
- docs-management：**维护**文档（确保已有文档保持健康和可用）

**docs-management vs task-manager**：
- task-manager：专门管 backlog（需求的收集/排序/清理）
- docs-management：管整个 docs/ 目录（包括 backlog 之外的 specs/plans/decisions/等）