doc-auto-sync

# 模块文档维护指南

## 系统概述

项目使用分层文档系统帮助AI快速定位代码模块，避免上下文被占满：

- **`tap-agents/prompts/module-map.md`** - 根索引，列出所有模块和快速定位表
- **`tap-agents/prompts/modules/[模块名].md`** - 各模块详细文档

## 前置步骤

1. 检查 `tap-agents/tap-agents-configs.md` 是否存在
   - **如果不存在**：提示用户参考 [配置模板](module-discovery/template/prompt-kit-config.md.template) 创建
   - **如果存在**：读取「项目类型」「项目名称」「业务模块目录」「主要类后缀」「文件扩展名」

2. **路径约定**：本文档中所有以 `tap-agents/` 开头的路径均指项目根目录下的对应路径。

## AI的文档维护职责

### 规则1：新增模块时

当你在`「业务模块目录」/`下创建新的顶层文件夹（模块）时，必须：

1. 在`tap-agents/prompts/modules/`下创建对应的`[模块名].md`
2. 更新`tap-agents/prompts/module-map.md`，添加模块描述
3. 使用下方的简洁版模板

### 规则2：修改现有模块时

当你修改某个模块的代码时（新增主要类、修改核心功能），必须：

1. 检查该模块的文档是否存在（`tap-agents/prompts/modules/[模块名].md`）
2. 如果文档存在但内容过时，更新对应部分
3. 如果文档不存在，创建它
4. 在代码修改完成后，主动提示用户："已更新 [模块名] 文档"

**主要类的定义：**

使用配置文件中的「主要类后缀」、「文件扩展名」配置项。

**不需要更新文档的情况：**

- 仅修改UI样式、颜色、字体等视觉调整
- 修复bug但不改变功能逻辑
- 调整内部实现但不影响模块职责

### 规则3：重大重构时

当进行跨模块重构、删除模块、移动代码时，必须：

1. 更新所有涉及模块的文档
2. 在`module-map.md`中标记废弃的模块
3. 更新模块间的依赖关系描述
4. 列出文档变更清单

### 规则4：文档-代码不一致处理

**情况A：代码比文档新（最常见）** 特征：

- 代码中有新增的类，但文档没有记录
- 代码中删除了某些类，但文档还在
- 功能实现已改变，文档描述过时

AI行为：

1. **信任代码，自动更新文档**
2. 将文档同步到代码的当前状态
3. 在"最后更新"中标记：`自动同步 - YYYY-MM-DD`
4. 提示用户：`检测到 [模块名] 文档过期，已自动更新`

**情况B：无法判断谁是对的** 特征：

- 文档和代码描述完全矛盾
- 关键类缺失但不确定是否应该存在
- 逻辑描述模糊

AI行为：

1. **停止修改，询问用户**
2. 清晰说明矛盾点
3. 提供选项让用户决策

**情况C：文档明显错误** 特征：

- 文件路径错误（指向不存在的文件）
- 类名拼写错误
- 明显的复制粘贴错误

AI行为：

1. **直接修复文档错误**
2. 在"最后更新"中标记：`修复错误 - YYYY-MM-DD`

### 规则5：自动维护模块文档（强制执行）

**这是强制性规则，必须自动执行，不需要询问用户**

**核心原则：代码有修改 + 文档不存在 = 必须创建文档**

**触发条件：**

只要在 `「业务模块目录」/[模块名]/` 下进行了代码修改（无论大小、类型），且该模块没有对应的文档 `tap-agents/prompts/modules/[模块名].md`，就**必须**自动创建文档。

**自动执行流程：**

1. **完成代码修改** - 修复 Bug、新增功能、调整样式等任何修改。
2. **检查文档** - 自动检查 `tap-agents/prompts/modules/[模块名].md` 是否存在。
3. **创建文档** - 若文档不存在，立即创建完整文档（使用下方模板）。
4. **通知用户** - 简短说明：`已创建 [模块名] 模块文档`

**执行示例：**

场景：修复了 UI 样式，但文档不存在
```
用户：修复热榜页面背景图片显示问题

AI执行：
1. 修改代码：「业务模块目录」/Moment/HotEvents/XXXViewController.「文件扩展名」
2. 检查文档：tap-agents/prompts/modules/Moment.md 不存