Markdown 技术文档写作

写作流程

创建或改写 Markdown 文档时都使用本技能。文档应先解释功能或流程，再关联维护所需的关键代码对象，使工程维护者和产品读者都能理解。

局部修改遵守用户指定范围，保留已有结构和无关改动，不为满足完整技术文档的标题层级而扩大重写。AGENTS.md、SKILL.md 等指令文件保留各自格式；只在描述代码行为时要求源码锚点。授权与询问遵守仓库 AGENTS.md，本技能不增加确认步骤。

先建立提纲

从领域概念出发，不按源文件顺序机械展开。先识别真实的产品或技术概念，再把每个概念映射到函数、结构体、枚举、常量、表、接口路由、配置字段或文件等源代码锚点。

文档只设一个有意义的一级标题。正文标题显式编号，并至少使用两级正文标题。例如在 ## 1. 构建流程 下设置 ### 1.1 配置选择 和 ### 1.2 内核构建，再设置 ## 2. 运行验证、### 2.1 QEMU 启动 和 ### 2.2 板卡启动。子标题数量由领域复杂度决定，复杂主题可拆成三个或更多同级小节，简单主题可以保留两个。一级标题之后最多再使用三层正文标题。不要加入“阅读导航”“使用说明”“背景说明”等不承载领域内容的装饰小节。

以解释段落组织章节

每个标题后先写一段完整说明，再放图、表、列表或代码块。说明段落应交代目的、行为和维护意义，不得只写一句重复标题的短句。

章节内部按需重复下列结构：

1. 用说明段落把功能行为与关键代码锚点联系起来。
2. 视需要加入 Mermaid 图、表、序号列表、无序列表或短代码片段。
3. 块状内容涉及边界条件、状态转移或实现约束时，再写解释段落。

两个块状内容之间必须有解释段落，不能把图、表、列表或代码块直接相邻堆放。

内容要求

技术文档必须有源码依据。描述行为的小节通常要指出实现或保存该行为的关键结构体、函数、枚举、常量或模块，但不要退化成逐行源码复述。

代码锚点

使用行内代码标注 cargo starry qemu、ArgsDefconfig、write_defconfig()、PlatformConfig 或 vm_configs 等名称。只有展示精确调用顺序、数据布局或条件规则时才使用短代码块。

代码锚点适合按下表组织：

文档需求	推荐形式
状态字段及含义	结构体字段表
函数职责	函数及其功能职责表
枚举值与阶段	枚举成员及用户可见含义表
常量与阈值	常量名称、值、单位和行为表
流程	Mermaid 图与解释段落

说明代码对象时必须解释其功能意义。例如，应说明 write_defconfig() 生成后续 build 和 qemu 命令读取的默认构建配置，而不是只说该函数存在。

图

能用 Mermaid 表达时优先使用 Mermaid。只有 Mermaid 无法清楚表达，或目标渲染器不支持所需语法时才使用字符图。

目的	Mermaid 图类型
流程或决策	flowchart
启动阶段或运行时状态机	stateDiagram-v2
时序与交互顺序	sequenceDiagram
数据关系	erDiagram 或 flowchart

图前必须用段落说明读者应从图中理解什么。图中含重要转移、安全分支、阈值或实现注意事项时，图后还要补充解释。

表与列表

表用于紧凑映射，不能代替解释。表前说明比较对象和比较意义；存在约束、默认值、边界情况或维护影响时，表后再解释。

只有顺序或快速浏览确有价值时才使用列表。序号列表表示有先后关系的步骤，无序列表表示同级项目。列表不能直接跟在另一个列表、表、图或代码块后面。

结构规则

新建或整体重写技术文档时检查本节规则；局部修改只检查本次涉及的内容、引用和格式。范围外的结构问题列为建议，不直接重写。

标题规则

文档只使用一个一级标题。正文标题采用显式点号编号：二级标题使用 ## 1. xxxx、## 2. xxxx；三级标题使用 ### 1.1 xxxx、### 1.2 xxxx；确有需要时四级标题使用 #### 1.1.1 xxxx。不得使用五级或更深标题，也不得用缩进序号列表模拟标题层级。

标题应短而明确，通常只标识一个功能面或概念，不在标题中放代码符号、括号或整句描述。优先使用“启动检查”“平台配置”“中断处理”，避免使用“boot_system() 启动逻辑”“平台配置（含动态探测）”或“构建和测试”。“甲和乙”都承载大量内容时，应改用更上位概念或拆成两个小节。

父标题一旦有子标题，同一层至少要有两个子标题。这个数量只是下限，不是固定模板。复杂领域应按真实功能拆成三个、四个或更多同级小节。正文不能只有二级标题，也不能出现只有一个子标题的层级。

块状内容位置

标题后不得直接放图、表、列表或代码块，必须先写段落。两个块状内容也不得直接相邻；中间应写一段解释它们之间关系的文字。

段落质量

有效段落通常同时说明功能行为、用户可见结果或工程后果，以及控制该行为的源代码锚点。删除“如下所示”“具体见下表”“本节介绍”“方便阅读”等不增加领域信息的填充语，改写为真实行为、约束或实现背景。

最终检查清单

按上述适用范围检查下列项目。请求内容已写入、事实与引用已核对、差异没有越界且适用校验通过后交付；无法核实的内容明确说明，不用无关构建或测试补充文档证据。

结构检查

• 每个标题后先有解释段落，没有直接放图、表、列表或代码块。
• 任意两个块状内容之间都有解释段落。
• 全文只有一个一级标题，正文标题使用 1.、1.1、1.2、2.、2.1、2.2 等显式编号。
• 正文不是只有二级标题；有子标题的父标题至少有两个子标题，复杂区域也没有机械地固定为两个。
• 标题简短，不含代码符号或括号，通常只命名一个功能面。

技术依据检查

• 功能说明包含维护所需的重要结构体、字段、函数、枚举、常量、状态名、参数名或模块文件。
• 图能用 Mermaid 时已使用 Mermaid。
• 表前后有必要解释，代码片段短且确有必要。
• 已删除不增进系统理解的装饰性小节和导航性填充内容。