rewrite-section

name	rewrite-section
description	对书籍中未通过质量审查的章节（粒度为 H3 小节）进行深度重写。 使用 MCP context7 和 deepwiki 查阅相关技术文档补充知识深度， 梳理整章上下文确保重写内容不突兀独立。Use when user says "重写章节", "rewrite section", "深度重写", "rewrite chapters", or after review-chapter identifies failures.

/rewrite-section

对《从数据到智能》书中未通过 review-chapter 审查的节进行深度重写。

重写不是"扩写"——不是给原来的几句话加更多修饰词。而是补上缺失的思想内核：设计决策推导、约束分析、取舍对比、实践案例。重写后的节应能在五维度评分中达到 ≥70 分。

运行时：兼容 Claude Code 与 Cursor。工具名对照见 COMPAT.md。局部编辑用 Edit（Claude）或 StrReplace（Cursor）。

---

:material-target: 全书核心主旨（重写前必读）

重写的最高准则不是"写得更多"，而是让每节内容与全书的四个写作理念、叙事主线、十二个核心母题对齐。如果在重写中丢失了本书的核心声音——第一人称、trade-off 诚实、演进视角——那么文字再多也是失败。

以下内容必须在每次重写前完整阅读并内化。（与 review-chapter 技能中的核心主旨部分完全同步。）

四个写作理念（来自前言）

理念	含义	重写时的操作
讲设计，不讲实现	代码会过时，架构思想历久弥新	不要在重写中堆砌代码示例——用"为什么这么设计"替代"代码怎么写"
讲 trade-off，不讲银弹	每个设计决策都是在特定约束下的取舍	至少给出一处权衡分析——"如果选 X 会怎样？代价是什么？"
讲演进，不讲终点	好的架构是持续演进的有机体，平台一直在生长	注入时间感——"当时为什么这么做""后来怎么演变""如果重来…"
讲叙事，不讲干货罗列	每一章都有故事，不是概念/步骤/表格的堆叠	有一个具体场景/故事锚点——不要写成教科书目录

贯穿全书的叙事主线

全书按照一座企业级医药数据平台的真实生命周期组织：

第 0 年 · 架构设计期（Part I-II）
  → 第 1 年 · 核心建设期（Part III-IV）
    → 第 2 年 · 扩展与迁移期（Part V-VI）
      → 第 3 年 · 成熟与治理期（Part VIII 前半）
        → 第 4 年 · Data+AI 转型期（Part VII）
          → 持续演进（Part VIII 后半，Ch 54 复盘）

核心叙事弧：从"医药数据困局"出发 → 建平台骨架 → 工程实践落地 → 基础设施自动化 → 平台扩展迁移 → 衍生系统外延 → 转折点——纯数据平台不够了 → 升华——Data+AI 转型，从数据平台走向 Agentic BI → 最终以"架构师复盘"收束。

重写时，必须在文中交代该节在叙事弧中的位置——"这个设计发生在项目第 N 年，当时…"

全书十二个核心母题（设计思想）

重写的每一节必须至少与以下一个母题产生共振。如果重写后的内容与全部十二个母题都无关，说明它没有触达本书的核心思想层。

#	母题	重写时的注入方式
M1	配置驱动架构	"为什么这么做？因为开闭原则——加数据源=加配置，零代码"
M2	分层架构	"为什么多这一层？因为关注点分离——上层不关心下层实现"
M3	事件驱动编排	"为什么不用 cron？因为事件驱动=数据到达即触发，零延迟零轮询"
M4	同构仓库模式	"为什么要同构？因为规模化——一套 CI 服务所有域，不是复制粘贴"
M5	工程诚实	不粉饰太平——如实写出已知缺陷、改进方向、如果重来怎么做
M6	治理与执行分离	"描述与执行解耦——改配置不改代码，改语义不改引擎"
M7	平台工程	"让业务团队写业务逻辑，平台团队提供抽象层"
M8	从数据到智能	注入演进视角——"这个设计后来在 AI 转型中发挥了什么作用"
M9	第一人称实践	"我在 Aurora 遇到…""我当时选了 X 而非 Y 因为…""后来回头看…"
M10	合规从第一天嵌入	在涉及数据治理/安全的节中，必须提到 GxP/PIPL/数据驻留
M11	规模决定架构	用量化数据解释设计——"如果只有 100 张表可以手工，但 20000 张表只能自动化"
M12	跨行业经验迁移	"我在专利数据/企业征信领域遇到过类似问题，当时…"

全书叙事密度地图

Part	定位	重写时"深度"标准	重写时"第一人称"标准
Part I (Ch 1-3)	序章	中等——重在"建立共鸣"	高——必须有鲜活的具体场景
Part II (Ch 4-11)	架构设计核心	极高——必须有推导链	高——设计争论、选型拍板
Part III (Ch 12-20)	数据工程实践	高——不只是 HOW 还要 WHY	中——实践中穿插经验
Part IV (Ch 21-30)	基础设施	中高——IaC 治理深度	中——工程流程标准化
Part V (Ch 31-34)	平台演进	高——迁移是架构思维	高——真实的踩坑经历
Part VI (Ch 35-37)	衍生系统	中	中
Part VII (Ch 38–49)	Data+AI 最高价值	极高——最创新的部分	极高——决策逻辑、争论
Part VIII (Ch 50-52)	治理复盘 思想收束	极高——反思必须具体	极高——"诚实需要勇气"

重写时的硬性约束：

• Part VII 的节如果缺少第一人称反思和 trade-off 分析 → 重写不合格
• Part II 的节如果只有"是什么"没有"为什么是" → 重写不合格
• Part I 的节如果缺少具体的、鲜活的场景描写 → 重写不合格
• 任何 Part 的节如果重写后只是"更长的教科书段落"而没有注入第一人称视角 → 重写不合格

叙事声音：第一人称"我"的使用规则

本书的核心叙事声音是第一人称。重写时必须保持这个声音。以下是指南：

✅ 好的第一人称	❌ 差的教科书式
"我在 Aurora 的架构评审会上被问过一个问题：'为什么不用 Airflow？'"	"在实践中，通常建议使用 Airflow 或 Step Functions"
"我当时选了 Step Functions，不是因为我觉得它更好，而是因为…"	"Step Functions 相比 Airflow 有以下优势…"
"后来回头看，这个决策有一个我没有预见的成本…"	"该方案的主要缺点是…"
"我做专利数据的时候遇到过一模一样的问题——…"	"类似的问题在专利数据领域也存在"

重写后自检：通读重写内容，数一下"我"字出现的次数。如果整节 ### 下没有出现一次"我"，则该节几乎一定丢失了本书的叙事声音。

---

重写前置条件

1. 必须有 .claude/review-results/ 下的审查结果 JSON，或用户明确指定要重写的节。
2. 重写粒度为 H3 小节（###），一个 H3 小节及其内容为一次重写的基本单位。

使用方式

/rewrite-section [目标]

/rewrite-section all                    # 重写所有未达阈值的节
/rewrite-section Ch 27                  # 重写 Ch 27 下所有未达阈值的节
/rewrite-section Ch 27 §27.1           # 重写指定节
/rewrite-section Ch 27 §27.1 §27.2     # 重写指定多节
/rewrite-section --priority 5          # 重写优先级最高的 5 节

不带参数时，如果有审查结果则交互式列出待重写清单，由用户选择。

执行流程

Step 0 — 确定重写目标

1. 如果用户指定了 --priority N，从审查结果 JSON 中取前 N 个 priority 最高的节。
2. 如果用户指定了章节范围，匹配对应节。
3. 如果用户明确指定了具体小节，直接使用。
4. 否则，展示待重写清单让用户选择。

Step 1 — 上下文梳理（重要！不可跳过）

重写前必须理解该节所在的完整上下文。读取以下内容：

1. 整章内容：目标节所在整章（从 H1 到末尾），理解章的整体叙事结构。
2. 相邻章节摘要：
   • 上一章的最后 200 行（理解叙事承接关系）
   • 下一章的前 80 行（理解铺垫方向）
3. 同章前后节：
   • 目标节的前一 H3 节（理解上文讲了什么）
   • 目标节的后一 H3 节（理解下文需要什么）
4. 面包屑与章节定位：阅读 !!! info "面包屑" 和 !!! abstract 框，理解项目阶段定位。

上下文理解清单（重写前自问）：

叙事定位层面：

• 该节所在 Part 的叙事密度定位是什么？（查"叙事密度地图"）
• 该节在全书叙事弧中处于什么时间节点？（第 N 年？架构设计期/核心建设期/Data+AI 转型期？）
• 该节应该触达哪些核心母题？（查"十二个核心母题"——该节最相关的 2–3 个是什么？）

结构衔接层面：

• 这一节在整章的叙事流中处于什么位置？（引入→展开→深化→收束？）
• 上一节讲了什么？本节目然承接了什么？
• 下一节需要什么？本节目然铺垫了什么？
• 该节与前后章节是否有经验迁移的呼应？（如"我在专利数据/企业征信遇到过类似问题…"）

内容质量层面：

• 这一节的核心观点是什么？（一句话概括——如果说不出来，说明内容没有焦点）
• 现有内容缺失了什么？（查审查结果的 main_issues 字段）
• 该节是否有"我"的声音？如果重写后整节没有一次"我"，需要补第一人称叙事

Step 2 — 知识补充（使用 MCP 工具）

这是核心步骤。深度重写需要补充外部知识。必须使用 Context7 + DeepWiki（工具名因运行时而异，见 COMPAT.md）。

2a — 使用 Context7 查阅最新技术文档

根据该节涉及的技术主题获取最新文档：

运行时	调用方式
Claude Code	mcp__context7__resolve-library-id → mcp__context7__query-docs
Cursor	GetMcpTools（server 含 context7）→ CallMcpTool：resolve-library-id / query-docs

示例：

• 如果节涉及 "GitHub Actions reusable workflows" → 查询 github-actions 相关文档
• 如果节涉及 "AWS Step Functions" → Context7 查 AWS / Step Functions 文档
• 如果节涉及 "LangGraph agent orchestration" → 查 LangGraph 最新文档

不要只查一个库——查 2–3 个相关库，获取多维度的专业知识。

2b — 使用 DeepWiki 获取深度知识

对相关开源项目提问：

运行时	调用方式
Claude Code	mcp__cognitionai_deepwiki__ask_question
Cursor	CallMcpTool，server 为 deepwiki（如 user-cognitionai/deepwiki），tool ask_question

示例：

• 节涉及 "Terraform module design" → 查 hashicorp/terraform deepwiki
• 节涉及 "LangGraph state machine" → 查 langchain-ai/langgraph deepwiki
• 节涉及 "Apache Iceberg" → 查 apache/iceberg deepwiki

每次重写至少使用 Context7 2 次 + DeepWiki 1 次。 这是硬性要求。

Step 3 — 设计重写方案

在理解上下文和补充知识后，设计该节的重写方案：

1. 保留什么：现有内容中哪些是好的（准确的概念定义、好的图表）——不要删除。
2. 补充什么：
   • 纵向深化：概念 → 为什么 → 怎么选 → 实际案例（补上缺失的中间层）
   • 横向对比：与主流方案/替代方案的对比表或分析段落
   • 实践注入：添加第一人称经验（"我在 Aurora 遇到…"）
   • 衔接增强：节首加"回顾式"过渡句，节尾加"下一节预告"句
3. 重写后结构：重写后该节的叙事弧（问题引入 → 方案分析 → 设计决策 → 实践验证 → 关键洞察 → 过渡铺垫）

重写方案模板（向用户展示确认后执行）：

### 重写方案：Ch X §X.Y [节标题]

**核心观点**：一句话

**现有问题**：
- 问题1
- 问题2

**重写后结构**：
1. 承上启下过渡段（衔接上一节 X.Y-1）
2. 问题引入：为什么需要 [主题]
3. 方案分析：[主题]的几种做法 + 对比
4. 设计决策：Aurora 的约束下为什么选了 X
5. 实践深化：一个具体案例
6. 关键图表 + 深度解读
7. 小结与铺垫（引出下一节）

**将补充的外部知识**：
- 从 Context7 [库名]：具体要查什么
- 从 DeepWiki [仓库]：具体要问什么

!!! warning "重要" 向用户展示重写方案，确认后再执行重写。如果用户说"直接重写"或"按方案执行"，则跳过确认直接重写。

Step 4 — 执行重写

按照确认的方案重写目标节。

重写规则

1. 保持格式约定（必须严格遵守 AGENT.md）：

   • 简体中文撰写
   • 保留现有 !!! info / !!! abstract / !!! warning / !!! tip 等 Admonition 框的写法
   • 图表标题格式：<p class="caption" markdown="span">**图 X-Y** ...</p>
   • 表格标题格式：**表 X-Y** ...
   • 章节内交叉引用一律用 ./ 同级相对链接

2. 保持图号/表号不变：

   • 如果只是修改描述文字而不改变图表顺序，图号/表号不变
   • 如果新增图表，用该章下一可用序号（如该章已有图 X-1 到 X-4，新图用 X-5）
   • 如果删除图表，对应的图号/表号需保留空缺标记，待整章重排后更新

3. Mermaid 图变更：

   • 如需新增/重绘 Mermaid 图，必须调用 mermaid-illustrate 技能
   • 不得手写未经该技能校验的 Mermaid 代码

4. 内容深度增强的具体手法：

   • 加"为什么"：每个设计决策后加一句解释原因
   • 加"对比"：在关键概念处加"与 X 的对比"分析
   • 加"案例"：在抽象概念后给具体的 Aurora 场景
   • 加"过渡"：节首句呼应上文，节尾句铺垫下文
   • 加"反思"：在章的叙事关键节点加 "我当时意识到…" 的第一人称洞察
   • 加"母题共振"：确保本节至少与 1-2 个全书核心母题产生共振（M1-M12）

4b. 重写后自检清单（重写完成后逐条检查）：

• 我是否交代了"为什么这么做"而非只写了"怎么做"？
• 我是否有至少一处 trade-off 分析（如果选 X 会怎样？代价是什么？）？
• 我是否注入了时间感/演进视角（"当时…后来…如果重来…"）？
• 我是否有至少一个具体场景/故事锚点（不是纯概念罗列）？
• 我是否用了第一人称"我"？（整节至少出现 1-2 次）
• 我是否与至少一个全书核心母题产生了共振？（M1-M12）
• 叙事密度是否匹配该节所在 Part 的定位？（查"叙事密度地图"）
• 如果该节在 Part VII/VIII/II，深度和第一人称是否达到了"极高"标准？

5. 编辑操作：
   • 用 Edit（Claude）或 StrReplace（Cursor）替换目标 H3 节下的内容（从 ### X.Y 标题 行到下一个 ### 或 ## 行之前）
   • 保留该节的标题行不变
   • 保留该节中好的图表，只补充解读文字

Step 5 — 同步更新目录文件

重写后如果涉及以下变更，按 AGENT.md 规则同步更新：

1. 新增/删除/修改 Mermaid 图 → 更新 meta/mermaid-catalog.md
2. 新增/删除/修改表格 → 更新 meta/table-catalog.md
3. 图号/表号变化时，重排受影响章节的序号并更新统计

Step 6 — 构建验证

重写完成后，运行构建验证：

uv run mkdocs build --strict

确保无告警后，报告重写完成。

深度重写的核心技法

技法 1：三段论分析模式

图表后必须有三段文字：

1. 图表说明了什么（What）：图中展示了什么架构/流程/对比
2. 关键洞察是什么（So What）：图中最关键的信息是什么，为什么重要
3. 对实践意味着什么（Now What）：基于这个洞察，实践者应该怎么决策

技法 2：叙事弧补全

如果原有节的段落是"平铺"的（A → B → C 可任意重排），重写后应为：

呼应上文（1–2 句过渡）
    ↓
问题引入（为什么需要解决这个问题？当时的约束是什么？）
    ↓
方案探索（有几种做法？我最初想了什么？试了什么？）
    ↓
设计决策（在 Aurora 的约束下，选了哪个方案？为什么？）
    ↓
实现要点（关键的技术细节，不要罗列，挑 1–2 个最有洞察的展开）
    ↓
验证与反思（方案实际效果如何？有什么 hindsight？）
    ↓
过渡铺垫（自然引出下一节要讲的主题）

技法 3：外部知识有机融合

Context7/DeepWiki 查到的知识不是贴引用——而是要融入叙事：

• ❌ 差："根据 LangGraph 官方文档，StateGraph 是…" → 贴标签式引用
• ✅ 好："StateGraph 的本质是一个带状态的有向图——每个 node 执行后更新 state，edge 决定下一个 node。LangGraph 设计者选择这个抽象是因为…这与我们在 Aurora 中遇到的 [具体问题] 恰好契合…"

技法 4：第一人称再深化

原书定位就是"首席解决方案架构师的第一人称手记"。重写时必须强化这个视角：

• ❌ 差："在实践中，通常建议使用…"
• ✅ 好："我在 Aurora 的架构评审会上被问过一个问题：'为什么不用 Airflow？'我的回答是…"

注意事项

1. 不要破坏现有格式：AGENT.md 的格式约束高于一切。
2. 不要过度扩写：一节应该是 200–800 字的精华，不是 3000 字的教科书。长度不是质量。
3. 图表不随意增删：好的图表保留，只在确实需要时才加新图。
4. 重写后节号/图号/表号不变：除非用户要求整章重新编号。
5. 每次都运行构建验证：uv run mkdocs build --strict 是提交前的必需步骤。
6. 重写结果记录：保存重写前后对比到 .claude/rewrite-logs/，便于回滚和复盘。
7. 对齐核心主旨——硬性约束：
   • 重写后的内容必须通过"重写后自检清单"全部 8 条检查。
   • 如果某条未通过，必须继续修改直到通过。
   • 特别关注"我"的存在感——这是本书与其他技术书籍最本质的区别。