Write-Code-Anls：源码解析技术写作方法论
> 一句话版本：这是一套教 AI 怎么写技术书的"写手技能"——它定义了一个完整的写作流程，告诉 AI 如何从源代码出发，通过生活类比、架构图、逐行注释等方式，写出像《Claude Code 完全指南》那样的深度技术教程。
- 来源: https://github.com/DracoUnion/skills/blob/master/write-code-anls/SKILL.md
- 仓库: https://github.com/DracoUnion/skills
- 示例大纲: https://github.com/DracoUnion/skills/blob/master/write-code-anls/examples/outline.md
- 研究日期: 2026-04-28
一、这是什么？
这是一个 Agent Skill（AI 编程助手的技能文件），专门用于指导 AI 如何将复杂源代码转化成深入浅出的技术教程。
它不是一个工具插件，也不是一个应用——它就是一个 Markdown 文件（SKILL.md），里面写满了"如何写技术书"的规则和模板。当 AI 编程助手加载这个技能后，它就知道如何：
- 分析源码结构 → 识别入口文件、模块依赖、核心类型
- 设计章节大纲 → 从基础概念到高级实现，渐进式组织
- 用生活类比解释复杂概念 → Agent Loop 像厨师做菜，权限系统像门禁卡
- 写逐行注释的代码解析 → 每行代码解释"为什么这么写"
和普通的"提示词"有什么不同？
| 普通提示词 | Agent Skill | |
|---|---|---|
| 结构 | 一段话描述任务 | 完整方法论 + 模板 + 示例 |
| 可复用性 | 每次手动写 | 一次性加载，永久可用 |
| 规范性 | 随缘 | 严格的 8 步工作流 |
| 示例 | 无 | 附带完整的《Claude Code 完全指南》样例 |
二、核心方法论的 8 条原则
2.1 源码驱动，从代码到故事
不搞"先讲概念再贴代码"那套。起点必须是源码——从实际代码出发，逐行解析。
先给完整代码 → 逐行注释 → 代码块后总结 → 对比不同方案
> 类型定义就是"设计图纸"——得先让读者看懂结构，再看逻辑。
2.2 技术写作风格
- 标题风格：
主标题 —— 形象副标题
- 例："Agent Loop 核心循环 —— 像厨师做菜一样的AI思考流程"
- 用"你"或"我们"：直接对话，不端着
- 短段落：不超过 4 行
- 列表项是段落：每一项是一段完整思考，不是短句
2.3 结构化章节模板（硬性要求）
每个章节必须包含这 7 个部分：
| 模块 | 内容 |
|---|---|
| 学习目标 | 3-5 点，列表形式 |
| 生活类比 | 完整段落，用日常场景建立直觉 |
| 模块地图 | 展示文件结构和模块关系 |
| 源码解析 | 核心概念 → 类型定义 → 逐行解析 → 数据流 |
| 设计取舍 | 一问一答，分析 trade-off |
| 动手练习 | 列表形式，不给答案 |
| 本章小结 | 小结 + 概念表 + 下章预告 |
2.4 生活类比 — 贯穿全文
比类比更重要的：连贯性。
> ❌ 开头提一句"像做菜"后面再也不提了
> ✅ 整章用"做菜"的比喻贯穿：准备食材(加载模块) → 烹饪(执行流程) → 出锅(返回结果)
Skill 里给出了几个经典类比：
- Agent Loop → 厨师做菜（准备→烹饪→上菜→反馈）
- BashTool 安全检查 → 银行柜台的多层验证
- QueryEngine → 超级管家协调各方
2.5 架构可视化
必须用 Mermaid 画图，而且是 4 种图表都要：
- 模块依赖图（文件之间的关系）
- 数据流图（状态如何流转）
- 时序图（关键调用链）
- 架构分层图（系统层次结构）
2.6 渐进式难度
第1-2章 → 基础概念，大量类比（★☆☆☆☆）
第3-5章 → 源码阅读，逐行解释（★★★☆☆）
第6+章 → 深入实现，设计决策（★★★★☆）
2.7 源码对应关系标注
每段代码必须标注：
| 标注项 | 示例 |
|---|---|
| 文件路径 | `src/QueryEngine.ts` |
| 行号范围 | 第 120-145 行 |
| 类/接口 | `QueryEngine` 类 |
| 函数名 | `submitMessage()` |
| 常量名 | `ALL_AGENT_DISALLOWED_TOOLS` |
2.8 执行步骤（8 步工作流）
1. 分析源码结构 → 找入口、梳理依赖、识别核心类型
2. 编写大纲 → 保存到 book/outline.md
3. 设计生活类比 → 找到能贯穿全文的比喻
4. 规划章节结构 → 确定学习目标、划分段落
5. 编写细纲 → 一章一个，book/details/{n}_detail.md
6. 撰写内容 → 一章一个，book/articles/{n}_body.md
7. 质量检查 → 是否标注了所有源码路径？类比是否贯穿？
8. 产出最终书籍
三、示例：《Claude Code 完全指南》
这个技能附带了完整的示例文件（examples/ 目录），展示这个方法论的实际产出。
outline.md（706 行，40.6 KB）是一本完整的 12 篇 114 节课程 的书籍大纲，基于 Claude Code 的 51 万行 TypeScript 源码。
| 篇 | 内容 | 章节数 |
|---|---|---|
| 第一篇 | 基础入门（Claude Code 是什么、编程基础、TypeScript、React/Ink） | ~4 |
| 第二篇 | 架构全景（启动流程、工具系统、QueryEngine、权限系统） | ~8 |
| 第三篇+ | 子系统深入、高级主题、实战总结 | 102+ |
| **总计** | **12 篇** | **114 节** |
四、DracoUnion 组织
DracoUnion 是一个 GitHub 组织，维护一个 技能仓库（DracoUnion/skills），里面除了 write-code-anls 这个技术写作技能外，还有大量其他技能：
技术类：
write-code-anls— 源码解析技术写作
自我成长/哲学类（大量）：
abcd-model— ABCD 模型advantage-compounding-in-networks— 网络中的优势累积adversity-to-opportunity-framework— 逆境转机遇框架ancestor-wisdom-inheritance— 祖先智慧继承anti-fragility-gene-cultivation— 反脆弱基因培养bidirectional-mentorship-model— 双向导师模式concise-communication-principle— 简洁沟通原则- ...
看起来像是一个人/团队在摸索 Agent Skills 的最佳实践，把自己的思考框架写成技能文件。
五、与我们的关联
对 Jay 的启发：
1. OpenClaw 里的 skill-creator 技能也可以借鉴这个方法论。目前 OpenClaw 的 skill-creator 负责创建/编辑 SKILL.md，但缺少这么完整的内容写作规范。
2. 这个技能本身就是一个完美的"技能怎么写"范例——它用自己的格式定义了一套方法论，同时展示了产出示例。如果我们要写新的 Agent Skills，这个可以作为参考。
3. 自我成长类技能——DracoUnion 仓库里大量的哲学类技能（反脆弱、逆境转机遇等）展示了一个有趣的方向：Agent Skills 不只是用来写代码的，也可以用来引导 AI 提供人生/思维建议。
4. 直接可用：把这个 SKILL.md 下载下来，加载到 Claude Code 或 Codex 里，你就能直接让它帮你写技术书了。
六、评分
| 维度 | 评分 | 说明 |
|---|---|---|
| 方法论完整性 | ⭐⭐⭐⭐⭐ | 8 条原则 + 8 步工作流，非常系统 |
| 实用性 | ⭐⭐⭐⭐⭐ | 可以直接用，产出质量有保证 |
| 示例质量 | ⭐⭐⭐⭐⭐ | 40KB 的完整书籍大纲，诚意十足 |
| 原创性 | ⭐⭐⭐⭐ | 融合了《Claude Code 完全指南》经验，但方法论是自创的 |
| 可移植性 | ⭐⭐⭐⭐ | 标准 SKILL.md 格式，兼容主流 Agent |
| 文档可读性 | ⭐⭐⭐ | 中文+英文混杂，格式一致性可改进 |
综合评分: 4.5/5
七、总结
write-code-anls 是目前见过的最完整、最系统的技术写作 Agent Skill。
它的核心价值不在于"教 AI 怎么写代码解析"，而在于提供了一套被验证过的方法论——一个把 51 万行源码变成 114 节课程的完整工作流。
如果你想把一个复杂项目的源码变成一本可读的技术书，直接下载这个技能加载到你的 AI 编程助手里就能开工。
> 一句话：想写技术书但不知道怎么下手？把这个 Skill 扔给 AI，它会告诉你每一步该做什么。