| name | AI_Generated_Code_Reading_Guide_Skill |
| description | Generates AI-authored code reading guides from a project or module. Invoke when user asks to read code, summarize architecture, and write a guide document. |
AI Generated Code Reading Guide Skill
目的
该 Skill 用于在代码仓库中生成“AI 阅读代码后输出的代码导读文档”。
适用场景：
- 用户要求阅读某个目录或模块的主体代码并总结。
- 用户要求把总结写入一个 Markdown 文档。
- 用户希望文档突出“代码导读”“快速理解代码”“AI 生成”等属性。
- 用户希望对多个模块分别生成导读文档，并统一命名风格。
输出目标：
- 形成一份面向读者的代码导读文档，而不是零散笔记。
- 突出模块职责、调用链路、目录分层、关键流程。
- 明确声明文档由 AI 阅读代码后生成，目标是帮助读者快速理解代码。
产出原则
生成导读文档时，遵循以下原则：
-
先界定边界
- 明确哪个目录是公共接口，哪个目录是内部实现。
- 如果用户特别强调“只有某个目录的头文件是对外 API”，必须在文档中明确写出。
-
先读说明文档，再读代码
- 优先阅读目标目录及其子目录中的
README.md、README_zh.md。
- 先用说明文档建立模块职责认知，再用源码验证和补充细节。
-
聚焦主体代码
- 优先阅读入口文件、主流程文件、模块注册文件、构建脚本。
- 对工具函数和第三方代码只做辅助理解，不喧宾夺主。
-
从“读者快速理解”出发组织内容
- 不按“读了哪些文件”写。
- 要按“这个模块是什么、怎么分层、怎么运行、关键点在哪”来写。
-
明确是 AI 生成
- 文档开头应加入统一说明，声明文档由 AI 阅读代码后生成。
- 同时写明目标是帮助读者快速理解代码结构、模块职责和主要流程。
推荐工作流程
第一步：确认目标和边界
收到用户需求后，先确认：
- 目标目录是什么。
- 输出文件写到哪里。
- 是否有特别限制，例如：
- 哪些头文件才算对外 API
- 是否要求参考
README_zh.md
- 是否要求中英文命名风格
如果用户已经明确给出这些信息，则直接进入下一步。
第二步：建立目录级认知
优先阅读：
- 顶层
README.md
- 目标目录的
CMakeLists.txt
- 各子目录的
README_zh.md
- 关键公共头文件
建立以下初步认知：
- 这是库、组件、应用框架，还是完整程序
- 主要分几层
- 每层的职责大致是什么
- 对外接口在哪里
第三步：梳理主体代码
重点阅读以下类型文件：
- 主入口文件
- 生命周期管理文件
- 模块管理器/注册器
- 关键 service / manager / controller
- 传输层或协议层核心实现
- HAL / OSAL / Framework 核心实现
- 样例代码或示例主程序
梳理时重点回答：
- 系统是怎么初始化的
- 核心对象是什么
- 模块之间如何协作
- 事件/回调/线程/状态机怎么串起来
- 输入输出数据是怎么流动的
第四步：形成导读结构
建议导读文档采用类似结构：
- 项目/目录定位
- 对外 API 边界
- 代码总体结构
- 核心数据模型
- 生命周期主流程
- 关键模块说明
- 调用链或运行链路
- 构建与平台适配
- 示例中的组装方式
- 一句话总结
如果目录不是库而是应用组件，还应明确说明：
- 它是否包含完整
main
- 它和底层 SDK / 上层示例之间是什么关系
文档开头推荐说明
建议在文档一级标题下方加入统一说明：
说明：本文档由 AI 在阅读当前目录代码后生成，目标是帮助读者快速理解代码结构、模块职责与主要运行流程，作为代码导读使用。
命名建议
如果用户希望文档名更专业，并突出导读和 AI 生成属性，推荐格式：
<module>_AI_Generated_Code_Reading_Guide.md
例如：
volc_conv_ai_AI_Generated_Code_Reading_Guide.mdapplication_AI_Generated_Code_Reading_Guide.md
写作要求
-
语言跟随用户
- 用户用中文，就用中文写导读。
- 用户用英文，就用英文写导读。
-
结构化表达
- 用清晰标题分段。
- 从总体到细节组织内容。
- 减少流水账式描述。
-
强调“导读”
- 目标不是替代源码。
- 目标是让读者快速知道从哪里读、为什么这么分层、主线怎么走。
-
尊重代码现状
- 以当前仓库中的代码为准。
- 如果发现示例中的初始化顺序比目录内更完整，可以引用示例帮助解释，但要说明其作用。
-
不夸大
- 未实现的能力要明确写“当前未实现”或“当前代码中未看到完整闭环”。
- 不要把设计意图误写成已实现能力。
推荐输出模板
可以按以下模板生成文档：
# `<模块名>` 代码梳理
> 说明：本文档由 AI 在阅读当前目录代码后生成，目标是帮助读者快速理解代码结构、模块职责与主要运行流程，作为代码导读使用。
## 1. 项目定位
## 2. 对外 API 边界
## 3. 代码总体结构
## 4. 核心流程
## 5. 关键模块说明
## 6. 构建与运行关系
## 7. 一句话总结
使用示例
示例 1
用户请求：
“阅读 /path/to/project/module 下的主体代码并总结，把总结写到 code_map.md 里。注意对外暴露的 API 只有 inc 目录中的。”
处理要点：
- 先读
inc/ 公共头文件，确定 API 边界。
- 再读主入口和主要实现文件。
- 在文档中明确写出“只有
inc 为对外 API”。
示例 2
用户请求：
“阅读该目录下主体代码并总结，把总结写到 code_map.md 里。注意阅读各个子目录中的 README_zh.md 文件，帮助理解。”
处理要点：
- 优先读取各子目录
README_zh.md。
- 用 README 建立模块认知后再补源码细节。
- 在总结中体现 README 中的设计原则和代码中的实际落地。
完成后检查
生成文档后，检查以下事项：
- 文档是否写明“AI 生成”和“代码导读用途”
- 是否明确公共接口边界
- 是否覆盖主流程和关键模块
- 是否避免大量无关第三方细节
- 文件名是否符合用户要求
- Markdown 是否无明显格式问题
