AI Generated Code Reading Guide Skill

目的

该 Skill 用于在代码仓库中生成“AI 阅读代码后输出的代码导读文档”。

适用场景：

• 用户要求阅读某个目录或模块的主体代码并总结。
• 用户要求把总结写入一个 Markdown 文档。
• 用户希望文档突出“代码导读”“快速理解代码”“AI 生成”等属性。
• 用户希望对多个模块分别生成导读文档，并统一命名风格。

输出目标：

• 形成一份面向读者的代码导读文档，而不是零散笔记。
• 突出模块职责、调用链路、目录分层、关键流程。
• 明确声明文档由 AI 阅读代码后生成，目标是帮助读者快速理解代码。

产出原则

生成导读文档时，遵循以下原则：

1. 先界定边界

   • 明确哪个目录是公共接口，哪个目录是内部实现。
   • 如果用户特别强调“只有某个目录的头文件是对外 API”，必须在文档中明确写出。

2. 先读说明文档，再读代码

   • 优先阅读目标目录及其子目录中的 README.md、README_zh.md。
   • 先用说明文档建立模块职责认知，再用源码验证和补充细节。

3. 聚焦主体代码

   • 优先阅读入口文件、主流程文件、模块注册文件、构建脚本。
   • 对工具函数和第三方代码只做辅助理解，不喧宾夺主。

4. 从“读者快速理解”出发组织内容

   • 不按“读了哪些文件”写。
   • 要按“这个模块是什么、怎么分层、怎么运行、关键点在哪”来写。

5. 明确是 AI 生成

   • 文档开头应加入统一说明，声明文档由 AI 阅读代码后生成。
   • 同时写明目标是帮助读者快速理解代码结构、模块职责和主要流程。

推荐工作流程

第一步：确认目标和边界

收到用户需求后，先确认：

• 目标目录是什么。
• 输出文件写到哪里。
• 是否有特别限制，例如：
  • 哪些头文件才算对外 API
  • 是否要求参考 README_zh.md
  • 是否要求中英文命名风格

如果用户已经明确给出这些信息，则直接进入下一步。

第二步：建立目录级认知

优先阅读：

• 顶层 README.md
• 目标目录的 CMakeLists.txt
• 各子目录的 README_zh.md
• 关键公共头文件

建立以下初步认知：

• 这是库、组件、应用框架，还是完整程序
• 主要分几层
• 每层的职责大致是什么
• 对外接口在哪里

第三步：梳理主体代码

重点阅读以下类型文件：

• 主入口文件
• 生命周期管理文件
• 模块管理器/注册器
• 关键 service / manager / controller
• 传输层或协议层核心实现
• HAL / OSAL / Framework 核心实现
• 样例代码或示例主程序

梳理时重点回答：

• 系统是怎么初始化的
• 核心对象是什么
• 模块之间如何协作
• 事件/回调/线程/状态机怎么串起来
• 输入输出数据是怎么流动的

第四步：形成导读结构

建议导读文档采用类似结构：

1. 项目/目录定位
2. 对外 API 边界
3. 代码总体结构
4. 核心数据模型
5. 生命周期主流程
6. 关键模块说明
7. 调用链或运行链路
8. 构建与平台适配
9. 示例中的组装方式
10. 一句话总结

如果目录不是库而是应用组件，还应明确说明：

• 它是否包含完整 main
• 它和底层 SDK / 上层示例之间是什么关系

文档开头推荐说明

建议在文档一级标题下方加入统一说明：

说明：本文档由 AI 在阅读当前目录代码后生成，目标是帮助读者快速理解代码结构、模块职责与主要运行流程，作为代码导读使用。

命名建议

如果用户希望文档名更专业，并突出导读和 AI 生成属性，推荐格式：

• <module>_AI_Generated_Code_Reading_Guide.md

例如：

• volc_conv_ai_AI_Generated_Code_Reading_Guide.md
• application_AI_Generated_Code_Reading_Guide.md

写作要求

1. 语言跟随用户

   • 用户用中文，就用中文写导读。
   • 用户用英文，就用英文写导读。

2. 结构化表达

   • 用清晰标题分段。
   • 从总体到细节组织内容。
   • 减少流水账式描述。

3. 强调“导读”

   • 目标不是替代源码。
   • 目标是让读者快速知道从哪里读、为什么这么分层、主线怎么走。

4. 尊重代码现状

   • 以当前仓库中的代码为准。
   • 如果发现示例中的初始化顺序比目录内更完整，可以引用示例帮助解释，但要说明其作用。

5. 不夸大

   • 未实现的能力要明确写“当前未实现”或“当前代码中未看到完整闭环”。
   • 不要把设计意图误写成已实现能力。

推荐输出模板

可以按以下模板生成文档：

# `<模块名>` 代码梳理

> 说明：本文档由 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 是否无明显格式问题