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