| 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 有以下优势…" |
| "后来回头看，这个决策有一个我没有预见的成本…" | "该方案的主要缺点是…" |
| "我做专利数据的时候遇到过一模一样的问题——…" | "类似的问题在专利数据领域也存在" |
重写后自检：通读重写内容，数一下"我"字出现的次数。如果整节 ### 下没有出现一次"我"，则该节几乎一定丢失了本书的叙事声音。
重写前置条件
- 必须有
.claude/review-results/ 下的审查结果 JSON，或用户明确指定要重写的节。
- 重写粒度为 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 — 确定重写目标
- 如果用户指定了
--priority N，从审查结果 JSON 中取前 N 个 priority 最高的节。
- 如果用户指定了章节范围，匹配对应节。
- 如果用户明确指定了具体小节，直接使用。
- 否则，展示待重写清单让用户选择。
Step 1 — 上下文梳理（重要！不可跳过）
重写前必须理解该节所在的完整上下文。读取以下内容：
- 整章内容：目标节所在整章（从 H1 到末尾），理解章的整体叙事结构。
- 相邻章节摘要：
- 上一章的最后 200 行（理解叙事承接关系）
- 下一章的前 80 行（理解铺垫方向）
- 同章前后节：
- 目标节的前一 H3 节（理解上文讲了什么）
- 目标节的后一 H3 节（理解下文需要什么）
- 面包屑与章节定位：阅读
!!! 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 — 设计重写方案
在理解上下文和补充知识后，设计该节的重写方案：
- 保留什么：现有内容中哪些是好的（准确的概念定义、好的图表）——不要删除。
- 补充什么：
- 纵向深化：概念 → 为什么 → 怎么选 → 实际案例（补上缺失的中间层）
- 横向对比：与主流方案/替代方案的对比表或分析段落
- 实践注入：添加第一人称经验（"我在 Aurora 遇到…"）
- 衔接增强：节首加"回顾式"过渡句，节尾加"下一节预告"句
- 重写后结构：重写后该节的叙事弧（问题引入 → 方案分析 → 设计决策 → 实践验证 → 关键洞察 → 过渡铺垫）
重写方案模板（向用户展示确认后执行）：
### 重写方案：Ch X §X.Y [节标题]
**核心观点**：一句话
**现有问题**：
- 问题1
- 问题2
**重写后结构**：
1. 承上启下过渡段（衔接上一节 X.Y-1）
2. 问题引入：为什么需要 [主题]
3. 方案分析：[主题]的几种做法 + 对比
4. 设计决策：Aurora 的约束下为什么选了 X
5. 实践深化：一个具体案例
6. 关键图表 + 深度解读
7. 小结与铺垫（引出下一节）
**将补充的外部知识**：
- 从 Context7 [库名]：具体要查什么
- 从 DeepWiki [仓库]：具体要问什么
!!! warning "重要"
向用户展示重写方案，确认后再执行重写。如果用户说"直接重写"或"按方案执行"，则跳过确认直接重写。
Step 4 — 执行重写
按照确认的方案重写目标节。
重写规则
-
保持格式约定（必须严格遵守 AGENT.md）：
- 简体中文撰写
- 保留现有
!!! info / !!! abstract / !!! warning / !!! tip 等 Admonition 框的写法
- 图表标题格式：
<p class="caption" markdown="span">**图 X-Y** ...</p>
- 表格标题格式：
**表 X-Y** ...
- 章节内交叉引用一律用
./ 同级相对链接
-
保持图号/表号不变：
- 如果只是修改描述文字而不改变图表顺序，图号/表号不变
- 如果新增图表，用该章下一可用序号（如该章已有图 X-1 到 X-4，新图用 X-5）
- 如果删除图表，对应的图号/表号需保留空缺标记，待整章重排后更新
-
Mermaid 图变更：
- 如需新增/重绘 Mermaid 图，必须调用
mermaid-illustrate 技能
- 不得手写未经该技能校验的 Mermaid 代码
-
内容深度增强的具体手法：
- 加"为什么"：每个设计决策后加一句解释原因
- 加"对比"：在关键概念处加"与 X 的对比"分析
- 加"案例"：在抽象概念后给具体的 Aurora 场景
- 加"过渡"：节首句呼应上文，节尾句铺垫下文
- 加"反思"：在章的叙事关键节点加 "我当时意识到…" 的第一人称洞察
- 加"母题共振"：确保本节至少与 1-2 个全书核心母题产生共振（M1-M12）
4b. 重写后自检清单（重写完成后逐条检查）：
- 编辑操作：
- 用
Edit（Claude）或 StrReplace（Cursor）替换目标 H3 节下的内容（从 ### X.Y 标题 行到下一个 ### 或 ## 行之前）
- 保留该节的标题行不变
- 保留该节中好的图表，只补充解读文字
Step 5 — 同步更新目录文件
重写后如果涉及以下变更，按 AGENT.md 规则同步更新：
- 新增/删除/修改 Mermaid 图 → 更新
meta/mermaid-catalog.md
- 新增/删除/修改表格 → 更新
meta/table-catalog.md
- 图号/表号变化时，重排受影响章节的序号并更新统计
Step 6 — 构建验证
重写完成后，运行构建验证：
uv run mkdocs build --strict
确保无告警后，报告重写完成。
深度重写的核心技法
技法 1：三段论分析模式
图表后必须有三段文字：
- 图表说明了什么（What）：图中展示了什么架构/流程/对比
- 关键洞察是什么（So What）：图中最关键的信息是什么，为什么重要
- 对实践意味着什么（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？'我的回答是…"
注意事项
- 不要破坏现有格式：AGENT.md 的格式约束高于一切。
- 不要过度扩写：一节应该是 200–800 字的精华，不是 3000 字的教科书。长度不是质量。
- 图表不随意增删：好的图表保留，只在确实需要时才加新图。
- 重写后节号/图号/表号不变：除非用户要求整章重新编号。
- 每次都运行构建验证：
uv run mkdocs build --strict 是提交前的必需步骤。
- 重写结果记录：保存重写前后对比到
.claude/rewrite-logs/，便于回滚和复盘。
- 对齐核心主旨——硬性约束：
- 重写后的内容必须通过"重写后自检清单"全部 8 条检查。
- 如果某条未通过，必须继续修改直到通过。
- 特别关注"我"的存在感——这是本书与其他技术书籍最本质的区别。
