# Tech Book Writing

> 技术书籍章节写作风格指南。融合反模板化叙事结构与段落级流畅性控制技法。 当用户要求写新的书籍章节、重写现有章节、优化文章可读性、或讨论技术写作风格时使用。 触发场景：写章节、重写、改写、优化文章、写作风格、叙事结构、可读性、 “换个切入方式”“这段太干了”“读者会流失”。 即使用户没有明确提到写作风格，只要任务涉及产出或修改技术书籍的正文内容，就应该参考本 skill。

- Skill: `luochang212/tech-book-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add luochang212/tech-book-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/luochang212/tech-book-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: luochang212 (https://skillmd.com/u/luochang212)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/luochang212/tech-book-writing

---


# 技术书籍章节写作

两个核心维度：

- **章级结构**：每章选择完全不同的叙事结构，拒绝模板化
- **段落级流畅性**：控制呼吸节奏，让读者停不下来

前者解决“章与章之间不能雷同”，后者解决“段与段之间不能断裂”。

---

## 一、反模板化：每章一个独立结构

技术书最大的可读性杀手是"所有章节读起来一样"。读者在第三章就能预测第四章的结构，阅读变成了填表。

每章开写前，先问自己：**这一章的内容特质是什么？什么叙事结构最适配它？**

### 可选的切入方式（不是清单，是灵感库）

| 切入方式 | 适合内容 | 例子 |
|----------|----------|------|
| 悬疑/侦探 | 排查 bug、追踪数据流 | "配置没生效。你检查了三个地方都没问题。第四个地方你根本没想到。" |
| 个人发现 | 首次理解某个机制 | "我一直以为 X 是这样工作的。直到我读了源码。" |
| 问答/对话 | 概念辨析、常见误解 | "每步都全量注入不行吗？可以，但贵。" |
| 类比贯穿 | 抽象机制需要直觉 | 报纸底版与增量、餐厅菜单与厨房 |
| 张力/续写 | 上一章留下的悬念 | "上一章说了知识不是能力。那能力从哪来？" |
| 鸟瞰回顾 | 总结章、哲学章 | 每章一句话概括，然后找共同模式 |
| 痛点-解法 | 工程决策、取舍分析 | "20 条命令点 20 次确认。你受得了吗？" |
| 时间线叙事 | 生命周期、状态迁移 | "下午两点你开始重构。到四点，context window 快满了。" |

### 核心原则

- 相邻两章**必须**用不同的切入方式
- 结构服务内容，不是服务对称
- 如果某章天然适合 Q&A，就用 Q&A；不要为了"统一风格"硬改成叙事
- 全书可以有 3-4 种主要结构模式，但每种最多连续用一次

---

## 二、段落级流畅性：呼吸控制

### 2.1 短段落原则

每段只承载**一个念头**。长度尽量控制在 3 句左右。

读者在手机上看你的文章。一个 6 句的段落在手机上是半屏的文字墙。他们会跳过。

**反面：**
> Codex 的上下文构造采用 baseline/diff 机制。首次全量注入后，后续每步只做增量。这样做的好处是保护前缀不变，从而命中 prompt cache。cache 命中可以显著降低 token 费用。但代价是调试困难，因为你无法在一个地方看到完整的 system prompt。

**正面：**
> 第一步，系统注入所有东西。这是底版。
>
> 从第二步开始，只告诉模型"什么变了"。底版不动。
>
> 为什么？因为前缀不能变。变了就浪费钱。

### 2.2 叙事动量转场

段落之间的衔接不靠"接下来""此外""另外"这类结构标记词。靠的是**上一段末句制造的问题/张力，被下一段首句接住**。

**弱转场：**
> ……cache 就 miss。
>
> 接下来我们看看 compaction 机制。

**强转场：**
> ……cache 就 miss。
>
> 那如果对话太长了呢？128K 的窗口，40 轮对话就满了。系统必须做点什么。

### 2.3 数字锚点

用具体数字替代形容词。数字制造画面感，形容词制造模糊感。

| 弱 | 强 |
|----|----|
| 很多 token | 110K token |
| 等很久 | 90 秒超时 |
| 大幅降低 | 从 20 次审批降到 0-2 次 |
| 很快 | 200ms 初始退避，每次翻倍 |

注意：数字必须来自源码或可验证的事实。不要为了画面感编造数字。

### 2.4 引用替代转述

能引用源码注释/变量名/函数名的时候，直接引用。引用比转述更可信，也更精确。

**转述：** 系统会在压缩后警告用户准确性可能下降。

**引用：** 系统发送一条 Warning："长线程和多次压缩可能降低准确性，建议开新线程。"

### 2.5 比喻即分析框架

比喻不是装饰。好的比喻**构成分析框架**——读者可以用它推理后续问题。

**装饰性比喻：** 沙箱就像一个保护罩。（然后呢？保护什么？怎么保护？读者还是不知道。）

**分析性比喻：** 底版不动，增量追加。就像报纸印刷——底版校准一次很贵，所以底版不变，只换今天的新闻。（读者立刻能推理：如果底版变了会怎样？校准成本。如果增量太多会怎样？版面不够→compaction。）

### 2.6 第一人称的困惑与反思

适度使用"我"表达真实的困惑。这建立可信度——读者知道作者也是人，也会犯错。

> 说实话，第一次看到这个空文件时我觉得这是个 bug。

但不要滥用。每章最多 2-3 处。第一人称是调味料，不是主菜。

### 2.7 节尾金句

每个 section 的最后一句应该是**可记忆的**——一个判断、一个对比、一个反转。不是总结性陈述。

**弱：** 综上所述，baseline/diff 机制在效率和正确性之间取得了平衡。

**强：** 上下文不是一个字符串，是一条装配线。

---

## 三、代码出场规则

### 前半段禁代码

文章前半段（建立问题感和直觉的阶段）不出现代码块。代码会吓跑初级读者。

前半段用：
1. 场景叙事建立"为什么我要关心这个"
2. Mermaid 图展示结构和流程
3. 类比建立直觉

### 代码只在证明承重逻辑时出场

代码不是"给读者看看长什么样"。代码是**证据**——证明一个文字无法独立验证的判断。

出场前必须有铺垫：
- 这段代码要证明什么？
- 读者应该重点看哪几行？
- 看完之后结论是什么？

出场后必须有解释：
- 控制流或状态变化意味着什么？
- 对前面的判断有什么影响？

### 不引用什么

- 样板代码、字段搬运、转发逻辑
- 信息量低的代码（看了跟没看一样）
- 可以用 Mermaid 图替代的结构关系

---

## 四、语言风格

- 中文。直接、准确、具体。
- 不写宣传腔（"强大的""优雅的""令人惊叹的"）
- 不把"复杂度""可扩展性""稳定性"当万能词——必须落到具体机制
- 允许指出读者的错误认知，但要说明为什么错
- 优先解释取舍，而不是堆工程名词
- 标题必须是自然、通顺、有信息量的中文问题或判断句

---

## 五、写作检查清单

写完一章后，过一遍：

- [ ] 本章的切入方式和前一章不同？
- [ ] 前 1/3 没有代码块？
- [ ] 段间转场靠叙事动量，不靠"接下来""此外"？
- [ ] 有具体数字（来自源码），不是"很多""很快"？
- [ ] 比喻构成分析框架，不是装饰？
- [ ] 每个 section 结尾有可记忆的句子？
- [ ] 代码出场前有"为什么要看"的铺垫？
- [ ] 没有宣传腔和万能词？