SuperAPI AI Directory

AI_Generated_Code_Reading_Guide_Skill

Coding & development

View repository

Updated 10-16 09:15

About this skill

AI Generated Code Reading Guide Skill

Purpose

This Skill is used to generate a "code walkthrough document output by AI after reading code" in a code repository.

Applicable scenarios:

  • The user requests reading the main code of a directory or module and summarizing it.
  • The user requests writing the summary into a Markdown document.
  • The user wants the document to emphasize attributes such as "code walkthrough", "quickly understand code", and "AI generated".
  • The user wants to generate walkthrough documents for multiple modules separately and unify the naming style.

Output goals:

  • Form a reader-oriented code walkthrough document, rather than scattered notes.
  • Highlight module responsibilities, call chains, directory layering, and key processes.
  • Clearly state that the document was generated by AI after reading code, and that the goal is to help readers quickly understand the code.

Production principles

When generating a walkthrough document, follow these principles:

  1. Define boundaries first

    • Clearly identify which directory is the public interface and which directory is the internal implementation.
    • If the user specifically emphasizes that "only the header files in a certain directory are the external API", this must be clearly stated in the document.
  2. Read documentation first, then code

    • Prioritize reading the target directory and its subdirectories README.md、README_zh.md。
    • First use the documentation to establish an understanding of the module responsibilities, then use the source code to verify and supplement details.
  3. Focus on the main code

    • Prioritize reading entry files, main process files, module registration files, and build scripts.
    • Use utility functions and third-party code only as auxiliary understanding, without letting them dominate.
  4. Organize content from the perspective of "readers quickly understanding"

    • Do not write according to "which files were read".
    • Write according to "what this module is, how it is layered, how it runs, and where the key points are".
  5. Clearly state that it is AI generated

    • At the beginning of the document, add a unified statement declaring that the document was generated by AI after reading code.
    • At the same time, state that the goal is to help readers quickly understand the code structure, module responsibilities, and main processes.

Recommended workflow

Step 1: Confirm goals and boundaries

After receiving the user's request, first confirm:

  • What the target directory is.
  • Where the output file should be written.
  • Whether there are special restrictions, for example:
    • Which header files count as the external API
    • Whether it is required to refer to README_zh.md
    • Whether a Chinese or English naming style is required

If the user has already clearly provided this information, proceed directly to the next step.

Step 2: Establish directory-level understanding

Prioritize reading:

  • Top-level README.md
  • The target directory's CMakeLists.txt
  • Each subdirectory's README_zh.md
  • Key public header files

Establish the following preliminary understanding:

  • Whether this is a library, component, application framework, or complete program
  • How many layers it is mainly divided into
  • What the responsibility of each layer roughly is
  • Where the external interface is

Step 3: Sort out the main code

Focus on reading the following types of files:

  • Main entry file
  • Lifecycle management file
  • Module manager/registrar
  • Key service / manager / controller
  • Core implementation of the transport layer or protocol layer
  • HAL / OSAL / Framework core implementation
  • Sample code or example main program

When reviewing, focus on answering:

  • How the system is initialized
  • What the core objects are
  • How modules collaborate with each other
  • How events/callbacks/threads/state machines are connected
  • How input and output data flows

Step 4: Form the reading guide structure

It is recommended that the reading guide document adopt a structure similar to:

  1. Project/directory positioning
  2. External API boundaries
  3. Overall code structure
  4. Core data model
  5. Main lifecycle flow
  6. Key module descriptions
  7. Call chain or runtime chain
  8. Build and platform adaptation
  9. Assembly approach in examples
  10. One-sentence summary

If the directory is not a library but an application component, it should also clearly state:

  • Whether it contains a complete main
  • What its relationship is with the underlying SDK / upper-layer examples

The beginning of the document should recommend stating

It is recommended to add a unified statement below the document's first-level heading:

Note: This document was generated by AI after reading the code in the current directory. Its goal is to help readers quickly understand the code structure, module responsibilities, and main runtime flow, and to serve as a code reading guide.

Naming suggestions

If the user wants the document name to be more professional and to highlight the reading guide and AI-generated attributes, the recommended format is:

  • <module>_AI_Generated_Code_Reading_Guide.md

For example:

  • volc_conv_ai_AI_Generated_Code_Reading_Guide.md
  • application_AI_Generated_Code_Reading_Guide.md

Writing requirements

  1. Language follows the user

    • If the user uses Chinese, write the reading guide in Chinese.
    • If the user uses English, write the reading guide in English.
  2. Structured expression

    • Use clear headings to separate sections.
    • Organize content from the overall to the details.
    • Reduce run-on, log-like descriptions.
  3. Emphasize the "reading guide"

    • The goal is not to replace the source code.
    • The goal is to let readers quickly know where to start reading, why it is layered this way, and how the main line flows.
  4. Respect the current state of the code

    • Base it on the code currently in the repository.
    • If the initialization order in the examples is found to be more complete than in the directory, the examples may be cited to help explain, but their role should be stated.
  5. Do not exaggerate

    • Capabilities that are not implemented should be explicitly written as "currently not implemented" or "no complete closed loop is seen in the current code."
    • Do not mistakenly write design intent as implemented capability.

Recommended output template

The document can be generated according to the following template:

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

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

## 1. 项目定位

## 2. 对外 API 边界

## 3. 代码总体结构

## 4. 核心流程

## 5. 关键模块说明

## 6. 构建与运行关系

## 7. 一句话总结

Usage examples

Example 1

User request:

"Read /path/to/project/module the main code under and summarize it, and write the summary into code_map.md . Note that the only externally exposed APIs are in the inc directory."

Processing points:

  • First read inc/ public header files to determine the API boundaries.
  • Then read the main entry point and main implementation files.
  • Clearly state in the document that "only inc is the external API."

Example 2

User request:

"Read the main code under this directory and summarize it, and write the summary into code_map.md . Note to read the README_zh.md files in each subdirectory to help understand."

Key points:

  • Prioritize reading each subdirectory README_zh.md。
  • Use the README to build an understanding of the module before filling in source code details.
  • Reflect in the summary the design principles in the README and their actual implementation in the code.

After completion, check

After generating the document, check the following items:

  • Whether the document states "AI-generated" and "for code reading guidance purposes"
  • Whether the public interface boundaries are clearly defined
  • Whether the main flow and key modules are covered
  • Whether a large amount of irrelevant third-party details is avoided
  • Whether the file name meets the user's requirements
  • Whether the Markdown has no obvious formatting issues