apple-ouyang Kernel Code To Docs
把“读代码”沉淀成长期文档，不输出临时聊天结论、计划文档或 TODO 清单。
长期文档仓固定入口是 ~/kernel-docs；如果实际仓库不在这个目录，安装脚本会维护同名软链接。
长期文档默认只写入 ~/kernel-docs/docs/<version>/<domain>/topic.md，不要把长期文档写回当前代码仓的 docs/。
When To Use
- 用户要你先读内核/系统代码，再整理成长期文档
- 默认读者是内核开发者，目标是沉淀机制问题、模块边界、调用链、约束和风险点
- 输出要进入
~/kernel-docs/docs/<version>/<domain>/
Execution Skeleton
按下面顺序执行：
- 先检查当前
repo_root + branch今天是否已经成功执行过git pull --rebase - 如果今天尚未成功 pull，且工作区干净，则先执行
git pull --rebase - 按
kernel-docs-system的入口规则直接运行docs-list，查看现有文档入口 - 判断这次调研的
version/domain - 抽查同主题文档，决定是更新原文还是新建
- 读代码并提炼稳定结论
- 如果发现现有文档与代码不一致，以代码为准修改文档
- 先写机制要解决的问题与稳定结论，再补证据索引和风险点
- 运行
docs-lint校验目标文档 - 用一条原子 git 命令提交本次文档改动
- commit 成功后执行
git mr --yes
Core Rules
- 每次进入本 Skill，先做一次每日
git pull --rebase检查，再开始读文档或读代码 - 每日 pull 的频率按“自然日 +
repo_root + branch”控制，状态记录在~/.claude/kernel-docs-pull-state.json - 只有成功 pull 才更新每日状态；失败不算完成
- 不要把输出写成计划文档
- 不要单独创建
research/目录 - 已经进入本 Skill 后，不要再回跳
kernel-docs-system做二次分发；这里只复用它的docs-list与路由规则 - 代码是事实真源；代码与文档冲突时，必须以代码为准修正文档
- 默认把文档写给内核开发者，优先帮助读者建立正确机制心智模型，而不是罗列零散实现细节
- 结论先讲清楚，再补证据路径
- 如果已有同主题文档，优先更新原文，而不是新建重复文档
- 即使已经存在同主题文档，只要内容与代码不一致，也必须更新该文档并提交
- 不确定点写进风险点，不要转成 TODO 清单
- 文档路径固定为
~/kernel-docs/docs/<version>/<domain>/topic.md process不单独建类，进程、线程、调度、启动、IPC 默认归arch- 目标文档落盘后必须提交，不能只停留在工作区
- 不要假设存在额外的 commit Skill、helper 或封装脚本；提交要求直接由本 Skill 明确给出
- commit 成功后必须继续执行
git mr --yes
Version And Domain Rules
固定版本目录：
v2v3lite
固定领域目录：
archmemoryfilesystemdfxdebugsecuritydrivers
版本判断：
- 仓名以
hm-开头：v3 - 绝对路径包含
RTOS_V3_master：v3 - 绝对路径包含
RTOS_V2_master：v2 - 路径或仓名包含
kernel-5.x：v2 lite只有用户明确说明时才按lite处理
阅读已有文档时遵循非对称规则：
- 当前路径命中
v2：只看docs/v2/ - 当前路径命中
v3：默认看docs/v3/；只有用户明确要求参考v2/Linux时，才额外看docs/v2/ - 当前上下文是
lite：先看docs/lite/；不够时再补看docs/v2/；不看docs/v3/ - 当前路径无法判断版本：根据用户语义决定是否读
docs/v2/、docs/v3/或docs/lite/
Front Matter And Structure
最小 front matter：
---
summary: 一句话概括这篇调研解决了什么理解问题
read_when:
- AI 需要判断这篇文档是否覆盖当前代码调研目标时
- 准备修改相关模块前
---
推荐正文结构：
# 标题
## TL;DR
## 这个机制解决什么问题
## 模块边界
## 关键数据结构
## 关键调用链
## 并发与内存语义
## 接口与约束
## 常见误用与风险点
## 证据索引
source 如果需要写：
- 参考文档：只写文档名
- 参考代码：写
git仓库名:仓内相对路径 - 不要求穷举所有参考文件，只记录主要来源
What To Extract
读代码后优先提炼这些内容：
- 这个机制解决什么问题，为什么需要这套设计
- 模块边界
- 关键数据结构
- 核心调用链
- 锁、线程、内存语义
- 接口约束和输入输出假设
- 常见误用、容易改坏的边界与风险点
- 证据索引
如果已有文档，额外检查这些差异：
- 模块边界是否已经变化
- 数据结构字段、状态机或生命周期是否已经变化
- 调用链、锁语义、并发语义是否已经变化
- 接口约束、前置条件、错误路径是否已经变化
- 文档中的结论是否已经被代码推翻
Commit And MR
- commit 标题默认使用
docs(<domain>): <补充、更新或纠正><主题>文档 <domain>只在能清楚表达领域时填写，例如docs(memory): 补充页表切换文档- 正文至少包含“原因：”和“改动：”两段；只有存在兼容性或迁移影响时再补“影响：”
- 提交必须通过一条原子 git 命令完成，命令中显式列出目标路径，不要依赖 repo-wide staging
- 提交路径必须显式列出本次修改的文档和必要的引用修复文件，禁止 repo-wide 提交
git mr --yes放在 commit 成功之后执行；如果失败，保留 commit 并明确报告失败
推荐 commit message 模板：
docs(<domain>): <补充、更新或纠正><主题>文档
原因：
- 当前问题缺少可复用的长期文档入口，或现有文档与代码不一致
改动：
- 新建或更新目标主题文档
- 补充稳定结论、证据索引与风险点
影响：
- 后续同主题问题可先从长期文档入口读取
Stop Conditions
下面这些情况不要硬写：
version/domain还没判断清楚- 还没判断该更新旧文还是新建
- 证据不足以支撑结论
- 用户真正要的是归档、迁移步骤或计划
- 今天还没成功 pull，但当前工作区不干净，无法安全执行
git pull --rebase
Output Contract
默认输出的文档或结论必须明确包含：
- 目标路径
- 为什么是这个版本目录
- 为什么是这个领域目录
- 主要参考了哪些代码路径
- 这个机制解决什么问题
- 已经确定的结论
- 还不能拍板的风险点
- 如果发现代码与文档不一致，哪些结论已按代码修正
- 是否执行了每日 pull 检查，以及结果是什么
- commit message 应该采用什么标题
Done Criteria
- 已明确是更新原文还是新建
- 如果发现文档过期，已按代码修正文档并提交
- 文档先讲结论，再给证据
- 当前实现和历史参考没有混写
- 风险点写清楚了边界