312362115/claude/docs-management

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

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

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

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

## 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 |

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

# 系统架构
 
## 模块概览
| 模块 | 职责 | 文档 |
|------|------|------|
| auth | 认证与会话管理 | [auth.md](auth.md) |
| payment | 支付与账单 | [payment.md](payment.md) |
 
## 模块间关系
-auth → payment：支付前需要认证
-...（或引用 docs/assets/ 中的架构图）

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（聚合全局视图）