---
name: doc-auto-sync
description:  强制规范：AI 改动模块代码时需同步创建/更新模块文档与索引，保持文档与代码一致。
---


# 模块文档维护指南

## 系统概述

项目使用分层文档系统帮助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 不存在
3. [触发规则] 创建文档：生成 Moment.md
4. 通知用户：已创建 Moment 模块文档

最终响应："背景图片问题已修复。已创建 Moment 模块文档"
```

**注意：** 如果文档已存在，则按规则2（更新文档）或规则（忽略微小修改）处理。本规则仅针对**文档缺失**的情况。

## 简洁版文档模板

```markdown
# [模块名]

## 模块简介

一句话描述这个模块的作用和职责。

## 核心功能

- 功能1：简短描述
- 功能2：简短描述
- 功能3：简短描述

## 主要类/文件

| 文件名                  | 说明       | 常用叫法/位置描述      |
| ----------------------- | ---------- | ---------------------- |
| XXXViewController | 主控制器   | 主页、首页             |
| XXXTopView        | 顶部视图   | 头部、顶部区域、banner |
| XXXManager        | 业务管理类 | 管理器、业务层         |

## 关键词

搜索关键词1, 关键词2, 关键词3

## 常用叫法映射（可选）

记录团队内部的口语化表达和对应的代码位置：

- "头部" / "顶部区域" → XXXTopView
- "底部按钮" / "操作栏" → XXXBottomView
- "列表" / "信息流" → XXXListViewController

## 最后更新

YYYY-MM-DD
```

## 使用示例

**开发场景1：新增功能**

```
用户：帮我在GameDetail模块添加分享功能

AI工作流：
1. 实现代码功能
2. 读取 tap-agents/prompts/modules/GameDetail.md
3. 在"核心功能"中添加"分享功能"
4. 在"主要类/文件"中添加新增的类
5. 更新"最后更新"时间
6. 提示："已完成分享功能，并更新了GameDetail模块文档"
```

**开发场景2：定位需求**

```
用户：修改评分显示样式

AI工作流：
1. 读取 tap-agents/prompts/module-map.md 查找"评分"关键词
2. 定位到相关模块
3. 读取 tap-agents/prompts/modules/[模块名].md 找到具体文件
4. 实现修改
5. 判断：仅样式修改，不需要更新文档
```

## 文档检查脚本使用

项目提供了两个辅助脚本用于检查文档状态：

**何时建议用户运行脚本：**

1. **check-docs.py** - 检查缺少文档的模块
   - 用户询问"有哪些模块还没有文档"
   - 用户想了解文档完成度
   - 开发了新模块，想确认是否创建了文档
   - 使用命令行参数：`python [check-docs.py 路径] --modules-dir [TapTap 业务根目录] --docs-dir [tap-agents/prompts/modules 文档目录]`

2. **check-stale-docs.py** - 检查可能过期的文档
   - 用户询问"哪些文档可能过期了"
   - 长时间没有更新文档系统
   - 想验证文档是否与代码同步
   - 使用命令行参数：`python [check-stale-docs.py 路径] --modules-dir [TapTap 业务根目录] --docs-dir [tap-agents/prompts/modules 文档目录]`

**AI的职责：**

- 当用户明确询问文档状态时，主动建议运行相应脚本
- 脚本运行后，根据结果提供建议（如：优先更新哪些模块）
- 不要在每次对话都建议运行脚本，只在必要时提及