代码库代码解读文档技能（AI 执行规范）

执行者：AI 模型——本文档是 AI 完成"代码库文档梳理"任务的端到端工作流规范，不是人工操作手册
触发时机：收到"分析/梳理/解读某代码库"的任务指令时，按本文档规定的步骤和标准执行
执行方式：在一次完整任务中连续完成，三步顺序不得颠倒（L1 架构梳理 → L2 任务规划 → L3 逐篇交付）
版本：v1.1（2026-04-02 迭代：增加源文件覆盖完整度规则）

AI 任务启动快速索引

收到新代码库分析指令后，立即按如下顺序执行：

第一步（L1）：找入口 → 追调用链 → 输出架构总览文档（→ 详见 2.3节第一步）

第二步（L2）：枚举模块 → 评估优先级 → 生成 Code_Analysis_Plan.md（→ 详见 2.3节第二步）

第三步（L3）：按计划逐篇套模板输出，B 类总览优先，再做 A/C/D 深潜（→ 详见 2.3节第三步）

单篇文档规范 → Section 3；质量门禁 → Section 5；文件命名 → Section 7；自检清单 → Section 10。

1. 技能目标与原则

1.1 目标

本技能定义了 AI 模型在收到"梳理新代码库"任务指令后，端到端产出一套完整文档的工作流。产出的文档集需满足：

代码库阅读者能快速理解系统执行主线与模块边界
每篇文档都可用于学习、排障、交接与复盘
不同代码库的文档输出风格一致，降低跨库迁移学习成本

1.2 四条原则

流水线优先：先解释“系统怎么跑”，再解释“模块怎么做”
骨架优先：先有模块总览，再做函数深潜
证据优先：每个结论必须可映射到真实源码
模板优先：统一标题、章节、图表、术语和验收口径

2. 文档体系设计（分类 + 分层）

2.1 六类文档（类型层）

沿用并固化为通用分类：

类型	名称	主要用途	交付粒度
A	函数级解析	单函数算法与逻辑拆解	1 函数/篇
B	模块级解析	类/文件/子模块职责与协作	1 模块/篇
C	算法/理论解析	数学推导与代码映射	1 算法/篇
D	调用链/Pipeline	跨模块调用与数据流跟踪	1 链路/篇
E	问题分析/调试报告	BadCase、Bug、性能与回归	1 问题/篇
F	对比/工具参考	概念、语言特性、工具指南	1 主题/篇

2.2 三层结构（目录层）

建议任意新代码库都按三层组织文档目录：

L1 架构层（Architecture）: 入口、主循环、关键 Pipeline
L2 模块层（Module）: Scheduler/Decision/Optimizer/... 各模块总览
L3 专题层（DeepDive）: 函数、算法、调用链、问题分析

推荐目录示例：

mdread/
  00_Architecture/
  01_Module/
    Scheduler/
    Decision/
    Path/
    Speed/
    Selector/
    Common/
  02_DeepDive/
    Function/
    Algorithm/
    CallChain/
    DebugReport/
  99_Standards/

2.3 三层逐层递进顺序（执行视角）

三层结构不是并列关系，而是严格的先后依赖关系：上一层产出是下一层的输入，缺一不可。

L1 架构层  ──产出架构图与主链路──▶  L2 模块层  ──产出解析计划──▶  L3 专题层
  （先）                              （次）                        （后）

第一步：完成 L1 架构层梳理（必须最先做）

目标：输出一份架构总览文档，使代码库阅读者能完整描述"这个系统从入口到输出，经历了哪几层、哪几个关键模块"。

做什么：

找到系统主入口（main / RunOnce / Process 等），从入口开始正向追踪调用链
识别 Pipeline 的主骨架：系统被分成哪几个子系统，数据流从哪里进、从哪里出
画出系统级流程图（Mermaid），框出所有子系统的边界与连接关系
为每个子系统写一句话的职责说明

产出（放入 00_Architecture/）：

架构总览文档（1 篇，含系统级流程图）
模块边界清单（子系统名称、入口函数、主要职责）

验收标准：读完 L1 文档后，能画出系统的数据流骨架，且与真实代码能对应。

第二步：基于 L1 产出，制作 L2 总览 + L3 大纲，生成解析计划

目标：把 L1 给出的模块边界拆解为可执行的文档任务列表，并将其直接写成 Code_Analysis_Plan.md 文件输出到 mdread/ 根目录下。Code_Analysis_Plan.md 就是这一步的唯一交付物，会贯穿整个任务始终。

⚠️ 重要约束：Code_Analysis_Plan.md 必须是本次任务、本代码库的执行计划，不得使用其他代码库的模板文件或历史计划文件。启动新任务时，若 mdread/ 下已存在 Code_Analysis_Plan.md，必须用本次任务的真实计划完整替换其内容。

做什么：

对每个 L1 识别到的子系统，逐一枚举其内部的关键模块/文件（可借助 find / ls / 代码结构工具）
为每个模块评估优先级（P0/P1/P2/P3），依据：是否在主链路、是否空白、是否高复杂度
为每个模块确定"需要哪些文档"：
- B 类（模块总览）：每个模块必须有一篇
- A 类（函数深潜）：核心函数或算法复杂的函数各一篇
- D 类（调用链）：跨多个模块的关键链路，单独一篇
为每个文档分配序号（例如 01、05）与文件名
将上述内容写入 mdread/Code_Analysis_Plan.md，格式要求见 §8

Code_Analysis_Plan.md 必须包含的内容（详细格式要求见 §8.1）：

代码库模块规模总览表（模块 × 文件数 × 行数 × 优先级）
逐篇文档计划表（序号 × 主题 × 对应源码 × 文档类型 × 优先级 × 状态字段）
源文件覆盖矩阵附录（所有 ≥100 行源文件 × 文档编号，不得有空白行）
进度统计行（已完成 / 进行中 / 待完成数量）

产出（放入 mdread/ 根目录）：

mdread/Code_Analysis_Plan.md：本次任务的唯一执行计划文件，状态从 🆕 开始，随任务推进逐条更新为 ✅
L2 目录骨架：01_Module/ 下各子目录（对应各子系统）预先建好

验收标准：

Code_Analysis_Plan.md 已创建，内容为本代码库的真实计划（非模板、非其他库的历史文件）
计划表覆盖所有 P0/P1 模块，每个模块至少有 1 篇 B 类文档计划项
序号连续、无重名
源文件覆盖矩阵附录已填写，≥300 行的文件均有独立文档编号

这一步的本质：L1 架构文档告诉你"有哪些模块"，第二步把它转化为"要写哪些文档"，写入 Code_Analysis_Plan.md 后成为整个任务的驾驶证。后续每篇文档完成后，都要回来在这张表上打 ✅，没有这张表，整个文档集就是无序堆砌。

第三步：按解析计划逐篇交付 L3 专题文档

目标：按计划、按优先级、一篇一篇地完成深度解析文档。

做什么：

按 P0 → P1 → P2 顺序，从计划表中取当前任务
读源码（头文件先于实现文件，理解结构后再看逻辑）
套用对应类型的模板（B 类用 Template_Module_Overview.md，A 类用 Template_Function_DeepDive.md）
完成文档后做自检（对照 Section 10 的 Checklist），通过后标记计划项为 ✅
每完成一篇文档 → 立即执行 /compact 压缩历史对话，在下一篇文档开头回顾关联上下文
更新计划文档的统计行

节奏：先完成该模块的 B 类总览，再做其下的 A/C/D 类深潜；不要在没有总览的情况下先写函数深潜。

验收标准：

进入 L3 阶段前，所有 P0 模块的 B 类总览文档必须全部完成（不得跳过先写深潜）
每完成一篇文档立即执行 /compact（这是上下文管理的核心规则，不可跳过）
每完成 5 篇更新一次计划状态
整个文档集在计划范围内的覆盖率 100%

三层顺序一览

层	阶段	核心问题	主要产出	前置依赖
L1 架构层	第一步：系统定向	系统从哪进、怎么跑、分哪几层	架构总览文档 + 模块边界	无（起点）
L2 模块层	第二步：任务规划	每个模块有哪些文件、要写哪些文档	`Code_Analysis_Plan.md` + 目录骨架	L1 文档完成
L3 专题层	第三步：逐篇交付	每个模块的逻辑、算法、边界是什么	A/B/C/D/E/F 类具体文档	L2 计划完成

3. 单篇文档标准结构（模板化）

以下结构作为默认模板，适配 A~F 六类文档。

3.1 必选章节（所有类型通用）

标题
源码路径
概述（定位、上下游、价值）
核心逻辑（分步骤）
流程图（Mermaid）
参数/变量说明表
总结（设计意图 + 边界）

3.2 条件章节（按类型启用）

函数签名与参数注释（A/B/D）
输入/输出协议（B/D/E）
关键公式与推导（C）
调用链追踪与时序图（D）
风险点/改进建议（E）
对比维度表（F）

3.3 单篇模板（可直接复用）

# [序号] [主题名]

> 源文件:
> - `path/to/file_a.cc`
> - `path/to/file_a.h`

## 1. 概述
- 该代码在系统中的职责
- 上游输入与下游输出
- 调用时机

## 2. 函数/模块签名（按需）
```cpp
// 真实源码签名

3. 核心逻辑（分步骤）

3.1 步骤一

解释
关键代码片段

3.2 步骤二

解释
关键代码片段

4. 数据流 / 调用链

输入数据结构
中间状态
输出结构

5. 流程图

flowchart TD
  A[输入] --> B[处理]
  B --> C{分支}
  C -->|是| D[路径1]
  C -->|否| E[路径2]
  D --> F[输出]
  E --> F

6. 关键参数说明

参数	类型	默认值	单位	说明

7. 设计意图与边界

为什么这样设计
适用边界
潜在风险

8. 关联文档

上游:
下游:


---

## 4. 全库执行流程（SOP）

### 阶段 0: 启动与盘点

1. 统计代码规模: 模块、文件数、语言、测试分布
2. 建立模块清单: 入口层、编排层、功能层、支撑层
3. 识别高优先级模块: P0/P1/P2/P3
4. **逐目录枚举所有源文件**：用 `find <src_dir> -name "*.c" | xargs wc -l | sort -rn` 获取每个文件行数，建立"源文件清单矩阵"（文件路径 | 行数 | 初步归属模块）；**特别扫描每个 `src/` 根目录**，`util.c`、`debug.c`、`logger.c` 等跨切面辅助文件往往不属于任何命名子模块，极易被遗漏或以附带方式稀释
5. 生成计划文件: Code_Analysis_Plan.md

交付物:
- 模块规模表
- **源文件清单矩阵**（全部 `.c`/`.cc` 文件 × 行数 × 归属模块，含"未归属"标记）
- 优先级矩阵
- 解析顺序图

### 阶段 1: 骨架文档先行

1. 先写架构总览（1~3篇）
2. 每个核心模块先写“模块总览”
3. 明确每个模块的入口函数、输入输出、关键依赖

验收标准:
- L1 架构文档已输出，系统主链路与模块边界可被完整描述

### 阶段 2: 深度拆解

1. 按计划逐项写 A/B/C/D/E/F 类文档
2. 每篇文档至少包含 1 张流程图 + 1 张参数表
3. 对关键算法补充公式与边界条件
4. 对复杂调用链提供链路文档而非单点文档堆砌

验收标准:
- 任一核心函数都能追溯到上游调用与下游影响

### 阶段 3: 交叉校验与收口

1. 文档与源码一致性检查（签名、路径、命名）
2. 去重与合并（避免同主题重复）
3. 计划文档状态回填（🆕/✅）
4. 更新统计表与覆盖率

验收标准:
- 计划项闭环率 100%
- 文档索引可导航

### 阶段 4: 维护机制

1. 代码变更触发对应文档更新
2. 新增模块必须先加“模块总览”再写深潜文档
3. 每次版本迭代输出“变更影响文档列表”

---

## 5. 执行标准（质量门禁）

### 5.1 内容质量标准

每篇文档必须满足：

1. 可定位: 标题、源码路径、命名统一
2. 可理解: 概述明确，术语可解释
3. 可追溯: 关键结论有源码证据
4. 可复用: 模板结构完整，图表齐全
5. 可学习: 有“为什么”和“边界条件”6. **可覆盖**: 源文件覆盖矩阵中每个行数 ≥ 300 的源文件，必须在某篇文档中作为**主角**被深入解析（函数逐一说明 + 流程图 + 参数表），不允许以"工具函数详见 XXX 总览"的附带方式一笔带过
### 5.2 表达标准

1. 一文一主题，避免多个主线混杂
2. 先结论后展开，先总览后细节
3. 代码片段只截关键段，必须加中文解释
4. 参数表必须标注默认值与单位（若有）
5. 图表命名规范，避免歧义

### 5.3 一票否决项

出现以下任一项判为不合格：

1. 源码路径错误或函数签名不一致
2. 只有代码粘贴，没有逻辑解释
3. 没有流程图或没有参数表
4. 无上下游关系说明
5. 结论无法从源码验证
6. **计划范围内存在行数 > 300 的源文件，在源文件覆盖矩阵中"文档编号"列为空**（即该文件未被任何文档显式覆盖）

---

## 6. 单次任务执行节奏（AI 执行顺序）

> 以下是 AI 在一次代码库梳理任务中的完整执行顺序，**每步完成后才进入下一步，不得跳步**。

### 步骤 1：启动盘点

1. 用 `find <src> -name "*.c" -o -name "*.cc" | xargs wc -l | sort -rn` 列出所有源文件及其行数，**建立源文件清单矩阵**（文件路径 | 行数 | 初步归属模块 | 计划文档——初始为空白）
2. 搜索关键词（`main`、`RunOnce`、`Process`、`Init`）定位系统入口文件
3. 按"入口层 → 编排层 → 功能层 → 支撑层"归类所有模块；**重点检查每个 `src/` 根目录有哪些 `.c` 文件不在任何子目录中**——此类文件（`util.c`、`debug.c`、`qp_solver.c`、`logger.c` 等）提供跨切面服务但命名不显眼，极易被漏进某个"总览"文档而从未被深入解析
4. 在 `mdread/` 下建立目录骨架（`00_Architecture/`、`01_Module/`、`02_DeepDive/`、`99_Standards/`）
5. 在清单矩阵中标记：**行数 > 300 的文件，必须独立成篇**，不允许与其他文件合并在同一模块总览中一笔带过

### 步骤 2：输出 L1 架构文档

1. 从入口函数正向追踪调用链，识别各子系统边界
2. 用 Mermaid 画出系统级流程图（子系统框 + 数据流箭头）
3. 为每个子系统写一句话职责说明
4. 输出架构总览文档 → 存至 `00_Architecture/`

### 步骤 3：生成解析计划（Code_Analysis_Plan.md）

1. 基于 L1 模块边界，用 `find` 枚举各模块下的关键文件；**同时遍历源文件清单矩阵，将"归属模块"列为空的文件逐一归类**，确保 `util.c`、`debug.c`、`qp_solver.c` 等根目录文件不被遗漏
2. 评定优先级（P0/P1/P2/P3）：主链路 + 空白 + 高复杂度 → P0；**行数 > 300 的文件自动升至 P1 或以上**，无论其看起来是否"只是工具类"
3. 为每个模块确定文档任务：B 类总览（必须）+ A/C/D 类（按需）；**行数 > 300 的单个源文件必须有独立计划项**，不允许将其与其他文件合并在一篇总览中仅用一段话覆盖
4. **将本次任务的真实文档计划写入 `mdread/Code_Analysis_Plan.md`**（若文件已存在，用本次任务内容完整替换其全部内容），格式要求见 §8；该文件放在 `mdread/` 根目录，便于查看和随时更新
5. 执行**覆盖率自检**：检查矩阵中每行"文档编号"列是否填写，若有空白则必须补充计划项，自检通过后才可继续
6. 预建 `01_Module/` 下各模块子目录

### 步骤 4：逐篇交付文档

1. 按 P0 → P1 → P2 顺序从计划表取任务
2. 每个模块严格按：**先 B 类总览 → 再 A/C/D 深潜** 的顺序执行
3. 每篇：读 `.h` → 读 `.cc` → 套对应模板 → 对照 Section 10 Checklist 自检 → 标记 ✅
4. 每完成约 5 篇，回填一次计划表统计行

### 步骤 5：收口校验

1. 检查所有文档的源码路径与函数签名是否与真实代码一致
2. 合并同主题重复文档
3. 确认计划表所有条目已回填状态，统计行数字准确
4. 确认文档集可从计划表完整导航（无死链、无孤立文档）

---

## 7. 文档命名与编号规范

### 7.1 文件命名

统一格式：

```text
{序号}_{主题英文短名}.md

示例：

3.2_EstPlanner_SingleTaskPipeline.md
8.7_GriddedSvtGraph_DpGraph.md
5.5_NudgeDecision_LateralOffset.md

7.2 标题命名

统一格式：

{序号} {英文主题} 中文说明

示例：

# 8.6 ConstraintGenerator 速度约束生成

7.3 中文信息保留规则

若历史文件名包含中文，重命名后在文档开头保留：

> 原始文件名: `中文名.md`

8. 计划管理规范（Plan-Driven）

8.1 计划文档必须包含

位置：mdread/Code_Analysis_Plan.md（放在 mdread/ 根目录，而非 99_Standards/）
内容归属：必须是本次任务、本代码库的真实执行计划；启动新任务时若文件已存在，用本次内容完整替换，不得保留其他代码库的历史内容

代码库信息头：工程名、语言、控制频率（如有）、主要源文件路径
模块优先级总览表（模块 × 文件数 × 行数 × 优先级 × 已完成文档数）
计划项编号（序号连续）
对应源码路径
解析目标（一句话说明该文档要解决什么问题）
文档类型（A/B/C/D/E/F）
状态字段（🆕 待开始 / 🔄 进行中 / ✅ 已完成）
统计汇总行（已完成 / 进行中 / 待完成 / 合计）
源文件覆盖矩阵（附录，必须）：所有行数 ≥ 100 的源文件均须出现，"文档编号"列不得为空，格式如下：

| 源文件路径 | 行数 | 文档编号 | 备注 |
|:-----------|-----:|:---------|:-----|
| src/control/util.c | 2050 | 25 | 工具函数深度解析 |
| src/control/lon_controller.c | 3958 | 11, 22 | 模块总览 + 函数深潜 |
...（每个 ≥100 行的文件一行）

8.2 状态更新规则

文档创建完成并自检通过后才可标记 ✅
若仅有草稿或信息不全，不得标 ✅
每次批量完成后必须更新统计行

9. 复用清单（换库时直接复制）

在新代码库中，先复制并初始化以下文件：

文件	用途	是否必须
`Code_Documentation_Standard.md`	撰写规范（内容标准 + 质量门禁）	✅ 必须
`Code_Analysis_Plan.md`	解析计划（进度管理 + 优先级）	✅ 必须
`Codebase_Documentation_Skill_Methodology.md`	本方法论（总 SOP）	✅ 必须
`Template_Module_Overview.md`	模块总览模板（B 类文档）	✅ 必须
`Template_Function_DeepDive.md`	函数深潜模板（A 类文档）	✅ 必须
`Template_Problem_Analysis.md`	问题分析报告模板（E 类文档）	推荐
`README_Doc_Index.md`	文档导航索引（按模块 + 学习路径）	推荐

模板文件使用方式：复制文件、替换 [...] 占位符、删除  注释行。

10. 文档审核 Checklist（提交前自检）

单篇文档自检（每篇完成后）：

标题、编号、源码路径是否正确
是否明确上下游与调用时机
是否有分步骤核心逻辑
是否有至少 1 张 Mermaid 流程图
是否有关键参数表（含单位/默认值）
是否解释设计意图与边界条件
是否列出关联文档（上游/下游）
是否更新计划状态与统计

阶段性自检（完成所有 B 类总览后 + 收口时各做一次）：

源文件覆盖矩阵中是否存在"文档编号"列为空的行（即行数 ≥ 100 的源文件未被任何文档覆盖）
各模块的根目录源文件（不在任何子目录中的 .c 文件）是否均已纳入计划，且行数 > 300 的是否均已独立成篇
是否有某篇模块总览把多个大文件合并覆盖——若单篇文档对应的源文件合计行数 > 800，需检查是否存在内容稀释问题

11. 这套技能的最终价值

对个人学习: 降低新代码库上手成本，形成可重复学习路径
对团队协作: 统一文档语言与结构，降低沟通损耗
对维护迭代: 代码变更可快速定位受影响文档
对知识沉淀: 从“读过代码”升级为“可传承知识资产”

12. 配套模板索引

模板文件	适用文档类型	核心特色
Template_Module_Overview.md	B 类（模块总览）	文件清单 + 公开接口 + 输入输出协议 + 依赖关系图
Template_Function_DeepDive.md	A 类（函数深潜）	签名注释 + 分步骤逻辑 + 场景校验 + 调用关系树
Template_Problem_Analysis.md	E 类（问题报告）	根因树 + 方案对比 + 修复前后对比 + 预防措施

13. 版本迭代记录与待打磨方向

v1.1 已完成（2026-04-02）

触发背景：util.c（2050 行，代码库第二大文件）在原始计划中被归入 18_AssistFunctions_Overview.md（实际覆盖的是 200 行的 assist_function/ 子目录），文件体量与覆盖深度严重不匹配，后期才被单独补充为 25_Util_DeepDive.md（700+ 行深度解析）和 26_SmithPredictor_DeepDive.md。

根因：规划阶段没有文件级枚举，模块以"子目录/算法分类"划定边界，位于 src/control/ 根目录的跨切面工具文件（util.c、debug.c、qp_solver.c 等）未被识别为独立文档任务。顺带导致的未覆盖清单：qp_solver.c（733行）、log/logger.c（527行）、lpc_controller.c（381行）、angle_diff_est/kinematic_model.c（281行）、debug.c（274行）等。

本次新增规则速查（所有改动均已写入上方对应 Section）：

改动位置	改动内容
§4 阶段0	新增步骤4：逐目录枚举源文件 + 行数统计，产出"源文件清单矩阵"
§6 步骤1	扩展为5步：含根目录文件扫描 + 行数 > 300 必须独立成篇
§6 步骤3	扩展为6步：含覆盖矩阵归属自检 + 大文件独立计划项要求
§5.1	新增第6条质量标准"可覆盖"
§5.3	新增第6条一票否决项：大文件未被任何文档覆盖
§8.1	新增第7条：源文件覆盖矩阵为计划文档必选附录；增加位置约束（mdread/ 根目录）和内容归属约束（禁止用历史文件代替）
§2 第二步	明确 `Code_Analysis_Plan.md` 是第二步唯一交付物，必须是本代码库真实计划，不得用模板/历史文件代替
§6 步骤3	明确写入路径为 `mdread/Code_Analysis_Plan.md`，若已存在需完整替换
§10	新增阶段性自检3项（覆盖矩阵 + 根目录文件 + 单篇合并检查）

v1.2 候选

增加"调用链追踪模板（时序图 sequenceDiagram 版）"
增加"算法/理论解析模板（C 类，含公式推导框架）"
增加"文档-源码一致性自动检查脚本规范"
增加"学习路径推荐"，按学习目标（入门/贡献/调试）给出文档阅读顺序
Code_Analysis_Plan.md 模板中内置"源文件覆盖矩阵"空白表格，避免遗忘

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

代码库代码解读文档技能（AI 执行规范）

AI 任务启动快速索引

1. 技能目标与原则

1.1 目标

1.2 四条原则

2. 文档体系设计（分类 + 分层）

2.1 六类文档（类型层）

2.2 三层结构（目录层）

2.3 三层逐层递进顺序（执行视角）

第一步：完成 L1 架构层梳理（必须最先做）

第二步：基于 L1 产出，制作 L2 总览 + L3 大纲，生成解析计划

第三步：按解析计划逐篇交付 L3 专题文档

三层顺序一览

3. 单篇文档标准结构（模板化）

3.1 必选章节（所有类型通用）

3.2 条件章节（按类型启用）

3.3 单篇模板（可直接复用）

3. 核心逻辑（分步骤）

3.1 步骤一

3.2 步骤二

4. 数据流 / 调用链

5. 流程图

6. 关键参数说明

7. 设计意图与边界

8. 关联文档

7.2 标题命名

7.3 中文信息保留规则

8. 计划管理规范（Plan-Driven）

8.1 计划文档必须包含

8.2 状态更新规则

9. 复用清单（换库时直接复制）

10. 文档审核 Checklist（提交前自检）

11. 这套技能的最终价值

12. 配套模板索引

13. 版本迭代记录与待打磨方向

v1.1 已完成（2026-04-02）

v1.2 候选

FilesExpand file tree

Codebase_Documentation_Skill_Methodology.md

Latest commit

History

Codebase_Documentation_Skill_Methodology.md

File metadata and controls

代码库代码解读文档技能（AI 执行规范）

AI 任务启动快速索引

1. 技能目标与原则

1.1 目标

1.2 四条原则

2. 文档体系设计（分类 + 分层）

2.1 六类文档（类型层）

2.2 三层结构（目录层）

2.3 三层逐层递进顺序（执行视角）

第一步：完成 L1 架构层梳理（必须最先做）

第二步：基于 L1 产出，制作 L2 总览 + L3 大纲，生成解析计划

第三步：按解析计划逐篇交付 L3 专题文档

三层顺序一览

3. 单篇文档标准结构（模板化）

3.1 必选章节（所有类型通用）

3.2 条件章节（按类型启用）

3.3 单篇模板（可直接复用）

3. 核心逻辑（分步骤）

3.1 步骤一

3.2 步骤二

4. 数据流 / 调用链

5. 流程图

6. 关键参数说明

7. 设计意图与边界

8. 关联文档

7.2 标题命名

7.3 中文信息保留规则

8. 计划管理规范（Plan-Driven）

8.1 计划文档必须包含

8.2 状态更新规则

9. 复用清单（换库时直接复制）

10. 文档审核 Checklist（提交前自检）

11. 这套技能的最终价值

12. 配套模板索引

13. 版本迭代记录与待打磨方向

v1.1 已完成（2026-04-02）

v1.2 候选