模块文档维护指南

系统概述

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

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

前置步骤

1. 检查 tap-agents/tap-agents-configs.md 是否存在

   • 如果不存在：提示用户参考 配置模板 创建
   • 如果存在：读取「项目类型」「项目名称」「业务模块目录」「主要类后缀」「文件扩展名」

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（更新文档）或规则（忽略微小修改）处理。本规则仅针对文档缺失的情况。

简洁版文档模板

# [模块名]

## 模块简介

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

## 核心功能

- 功能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的职责：

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