"The most tiring part of maintaining a knowledge base isn't reading and thinking, it's bookkeeping—cross-references, consistency maintenance. This is exactly what LLMs are good at." — Karpathy, LLM Wiki
Three-layer architecture
Raw Sources（原始素材） → 代码、git log、会议记录、外部文档
Wiki（知识库） → docs/ 目录下所有结构化文档
Schema（规则） → CLAUDE.md 中的文档规范
Four core operations
Operation 1: Ingest
When new information comes in, don't just create a new file—find existing documents to merge and update.
Trigger timing：
- When task-manager marks done (automatically triggered after the retrospective is complete)
- When a new design decision is made
- When external information needs to be integrated into project documentation
Execution flow：
新信息产生
│
├─ 搜索 docs/ 中是否有相关文档
│ ├─ 有 → 更新已有文档，合并新信息
│ └─ 无 → 创建新文档
│
├─ 更新 docs/ 内相关交叉引用
│
└─ 更新 INDEX（如有）
Example：
- task-finish produces a retrospective → write to
docs/decisions/, and at the same time check whether the corresponding spec needs to be annotated with "the plan has been executed, see decisions/xxx for actual deviations" - Discover a new best practice → update
docs/guides/related guidelines
Spec deviation handling in Ingest
When a spec is marked done, it must reflect the final implementation, but not all deviations need the same handling.
偏差判断
│
├─ 细节偏差（字段名调整、参数变更、实现细节微调）？
│ └─ 直接更新 spec 中的技术方案章节
│
├─ 方案偏差（换了实现路径，但目标不变）？
│ └─ 更新 spec 技术方案 + 在决策章节补注"实际执行偏差及原因"
│
└─ 方向偏差（目标或范围发生了变化）？
└─ 写 decision 记录完整复盘，spec 中标注"已被 decisions/xxx 覆盖"
Operation 2: Query
docs/ is the project's queryable knowledge base, not a pile of files.
Trigger timing：
- The user asks "How was this module designed before?"
- The user asks "How was a similar problem solved last time?"
- task-start retrieves historical experience during the alignment phase
Execution flow：
查询请求
│
├─ 在 docs/ 中搜索相关文档
│ ├─ specs/ — 设计方案
│ ├─ decisions/ — 踩坑记录和经验
│ ├─ plans/ — 历史开发计划
│ ├─ tests/ — 测试用例
│ └─ guides/ — 开发指南
│
├─ 综合相关文档给出回答
│
└─ 如果回答有价值且不在现有文档中 → Ingest 回 wiki
Operation 3: Lint (health check)
Regular checkups to prevent documentation rot.
Trigger timing：
- The user actively requests a check
- After large-scale code changes
- Regular maintenance
Checklist：
| # | Check item | How to check | Problem example |
|---|---|---|---|
| 1 | Reference validity | Whether the file paths referenced in the document exist | The spec references a file that has been deleted |
| 2 | Progress consistency | Whether the plan's checklist matches the actual code | The plan says "to do" but the code is already complete |
| 3 | INDEX sync | Whether INDEX.md matches the actual files | INDEX has it but the file has been deleted |
| 4 | Cross-document consistency | Whether the spec referenced by the plan exists | The plan points to a nonexistent spec |
| 5 | Status sync | Whether the backlog status matches the actual progress | The backlog is open but the plan is fully complete |
| 6 | Orphan documents | Whether there are any files not referenced by any INDEX or document | A forgotten old spec |
| 7 | Outdated content | Whether the code structure described in the document still exists | The spec says "modify src/old.ts" but that file has been renamed |
| 8 | Global view sync | Whether the INDEX of architecture/ and user-guide/ is consistent with the actual subdocuments | INDEX lists them but the files do not exist, a new module has a spec but it is not included in architecture/ |
| 9 | Memory inspection | Whether the entries in memory are still valid | The module referenced by feedback has been deleted, the project information is outdated |
Output format：
## 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 |
Operation 4: Index (index maintenance)
The index is the entry point of the knowledge base and must stay in sync with the actual content.
Maintenance targets：
docs/backlog/INDEX.md— requirements index (already exists, maintained by task-manager)docs/decisions/INDEX.md— experience index (to be created, in reverse chronological order)
INDEX update timing：
- After creating a new document
- After a document's status changes
- After Lint finds an inconsistency
Operation 5: Synthesize (aggregation)
Maintain a global view index from fragmentary documents. It is not about writing long documents, but about keeping the index accurate.
Maintenance targets：
| Directory | Responsibility of INDEX.md | Subdocuments |
|---|---|---|
docs/architecture/ |
Module list, relationships between modules, overview of core data flows | One architecture document per module |
docs/user-guide/ |
Feature catalog, quick start navigation | One user guide per feature/module |
Trigger timing：
| Trigger scenario | Operation | token cost |
|---|---|---|
| User manually requests | Full: read all relevant spec/decision, rebuild INDEX | High |
| User confirms after task-finish reminder | Incremental: read only the modules involved in this change, update the corresponding subdocuments and INDEX | Low |
| Lint finds that INDEX and actual files are inconsistent | Fix: align INDEX with the actual file list | Very low |
Execution flow：
触发 Synthesize
│
├─ 全量模式（首次生成 / 用户要求重建）
│ ├─ 扫描 docs/specs/ 和 docs/decisions/ 提取模块列表
│ ├─ 每个模块生成/更新 architecture/<模块名>.md
│ ├─ 生成 architecture/INDEX.md（模块导航 + 关系概览）
│ └─ user-guide 同理
│
└─ 增量模式（单次改动后）
├─ 只读本次涉及的 spec/decision
├─ 判断是否涉及新模块 / 模块间关系变更
│ ├─ 是 → 更新对应子文档 + INDEX
│ └─ 否 → 跳过
└─ 完成
INDEX.md format example：
# 系统架构
## 模块概览
| 模块 | 职责 | 文档 |
|------|------|------|
| auth | 认证与会话管理 | [auth.md](auth.md) |
| payment | 支付与账单 | [payment.md](payment.md) |
## 模块间关系
- auth → payment：支付前需要认证
- ...（或引用 docs/assets/ 中的架构图）
Difference from Ingest：
- Ingest: one piece of new information → archived into one document (one-to-one)
- Synthesize: multiple documents → aggregated into an index and global view (many-to-one)
Relationship with other skills
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：Producedocuments (write them from scratch)
- docs-management：Maintaindocuments (ensure existing documents stay healthy and usable)
docs-management vs task-manager：
- task-manager: specifically manages the backlog (collection/prioritization/cleanup of requirements)
- docs-management: manages the entire docs/ directory (including specs/plans/decisions/etc. outside the backlog)