| name | docs-management |
| version | 1.0.0 |
| last_updated | "2026-04-08T00:00:00.000Z" |
| 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 信息已过期 |
输出格式：
## 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 格式示例：
# 系统架构
## 模块概览
| 模块 | 职责 | 文档 |
|------|------|------|
| 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/等）
