# AI_Generated_Code_Reading_Guide_Skill

> 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.

- Skill: `volcengine/ai-generated-code-reading-guide-skill` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add volcengine/ai-generated-code-reading-guide-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/volcengine/ai-generated-code-reading-guide-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: volcengine (https://skillmd.com/u/volcengine)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/volcengine/ai-generated-code-reading-guide-skill

---


# 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. 不夸大
   - 未实现的能力要明确写“当前未实现”或“当前代码中未看到完整闭环”。
   - 不要把设计意图误写成已实现能力。

## 推荐输出模板

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

```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 是否无明显格式问题