WRITING_STYLE.md¶

写作规范：章节结构、工程视角、AI 写作规则¶

本文件定义《Data-Driven AI：从数据到智能》的写作规范。

所有章节作者与 AI 协作 Agent 都必须遵守。

语言红线见 BOOK_CONSTITUTION.md 第七章，本文件是它的展开。

一、章节默认结构¶

1.1 默认结构¶

每章默认采用以下八段结构：

问题
传统方案
为什么失效
新的设计思想
架构设计
工程实践
最佳实践
Checklist

1.2 各段应回答的问题¶

段	应回答
问题	这章要解决的工程问题是什么
传统方案	在 AI 之前，数据团队怎么做
为什么失效	为什么传统方案在 AI 场景下失效
新的设计思想	DDA 方法论如何重新看待这个问题
架构设计	重新设计后系统长什么样
工程实践	落地时有哪些关键工程决策
最佳实践	哪些做法被验证有效
Checklist	读者读完能带走哪些可执行条目

1.3 各段不应写什么¶

段	不应写
问题	不应直接介绍工具
传统方案	不应贬低传统数据工程
为什么失效	不应只说"慢"，要说清失效的具体机制
新的设计思想	不应只贴一张架构图不解释
架构设计	不应只画工具拼装图
工程实践	不应写安装教程
最佳实践	不应写"视情况而定"作为结论
Checklist	不应写无法判定对错的条目

1.4 判定规则¶

不要直接介绍工具。

不要跳过"为什么"直接进入"怎么做"。

二、Why before How¶

2.1 原则¶

每章开篇必先讲为什么（Why）。

再讲如何做（How）。

2.2 开篇五问¶

每章开篇必须回答：

为什么 AI 改变了数据平台？
为什么数据工程师需要学这个概念？
这个概念解决什么问题？
它如何改变系统架构？
它如何影响工程设计？

2.3 禁止¶

禁止直接进入实现。

禁止第一段就贴代码。

禁止第一段就介绍工具。

2.4 判定反例¶

如果一个章节的前 200 字没有出现"为什么"，违反 Why before How。

如果一个章节的第一张图是部署图，违反 Why before How。

三、图优先¶

3.1 原则¶

能用图，不用大段文字。

3.2 图的种类¶

本书使用的图包括：

架构图
生命周期图
时序图
对比图
数据流图
闭环流程图

3.3 图与正文的关系¶

每张图必须有图注。

每张图必须在正文有引用与解读。

图不能替代"为什么"的论述。

3.4 图的规范¶

图的详细规范见 DIAGRAM_GUIDE.md。

3.5 判定规则¶

一段超过 300 字仍在描述系统结构，考虑改成图。

一张图没有正文解读，补解读或删图。

四、代码原则¶

4.1 原则¶

代码用于解释架构。

代码不是为了展示技巧。

4.2 优先顺序¶

优先使用：

SQL
YAML
架构图
配置
流程图

其次使用：

简短的 Python 伪代码

4.3 禁止¶

禁止长代码块。

禁止完整可运行的项目工程。

禁止为代码而代码。

4.4 判定规则¶

如果删掉一段代码，读者仍能理解架构，这段代码是多余的。

如果一段代码超过 30 行，考虑拆成图或伪代码。

五、工程视角¶

5.1 应讨论¶

讨论：

系统架构
数据流
工程设计
治理
可维护性
可演进性

5.2 禁止讨论¶

不要讨论模型排行榜。

不要讨论"哪个 LLM 更聪明"。

不要讨论模型参数量比较。

不要讨论推理速度跑分。

5.3 判定反例¶

如果一个段落的主要信息是某模型的 benchmark，删除它。

如果一个章节的核心论点是"用了某模型所以更好"，重写它。

六、不要写工具书¶

6.1 原则¶

工具只是例子。

6.2 章节必须围绕¶

章节必须围绕以下核心思想展开：

Ontology
Semantic Layer
Knowledge Foundation
Data Loop

6.3 禁止围绕¶

不要围绕以下工具组织章节：

Neo4j
Milvus
LangChain
LlamaIndex
MCP

6.4 工具的出现方式¶

工具只能作为"工程实践"段的例子出现。

工具出现时必须标注：这是某一类实现的一个例子，不是唯一选择。

6.5 判定规则¶

如果一个章节的小标题是某工具名，违反本规则。

如果一个章节删掉工具名后没有剩下思想，违反本规则。

七、中文技术写作规范¶

7.1 术语¶

术语首次出现给中英文并列。

后续统一用中文。

术语的统一翻译以 GLOSSARY.md 为准。

7.2 数字与单位¶

数字用半角阿拉伯数字。

单位与数字之间留一个半角空格。

7.3 标点¶

中文段落用中文标点。

代码与命令用半角标点。

不滥用破折号。

不滥用省略号。

7.4 句子¶

长句拆短。

一句一个意思。

避免从句嵌套超过两层。

7.5 段落¶

一段一个主题。

段首不必用"首先""其次""再次"。

7.6 避免口语化¶

本书不是博客。

本书不是公众号文章。

保持书面工程语言的密度。

7.7 避免营销腔¶

营销语言的红线见 BOOK_CONSTITUTION.md 第七章。

八、AI 写作规则¶

本节专门约束 AI 协作 Agent 的写作痕迹。

8.1 总原则¶

AI 写的章节，读起来应该像一位资深数据工程师写的。

不应该读起来像 AI。

8.2 禁止的 AI 痕迹¶

禁止以下 AI 写作特征：

夸大象征意义
宣传式开头
-ing 式肤浅分析
模糊归因
破折号过度使用
三段式排比
否定式排比
过多连接性短语
空泛的"在当今……时代"开场

8.3 正反例对照¶

夸大象征意义¶

❌ 错误：

Ontology 的出现，标志着数据平台走向了一个全新的纪元。

✅ 正确：

Ontology 让 AI 系统拥有了一份与业务共识对齐的世界模型。

宣传式开头¶

❌ 错误：

在大模型席卷一切的今天，每一个数据团队都必须重新思考自己的定位。

✅ 正确：

AI 系统需要的数据访问语义，传统数仓不提供。

-ing 式肤浅分析¶

❌ 错误：

通过将 Ontology 与 Semantic Layer 结合，能够实现数据的语义化消费。

✅ 正确：

Semantic Layer 把 Ontology 暴露为 Agent 可调用的接口。

模糊归因¶

❌ 错误：

业界普遍认为，Data Loop 是 AI Native 的关键。

✅ 正确：

本书认为 Data Loop 是 AI Native 企业的竞争壁垒，理由见 ARCHITECTURE.md 2.7 节。

破折号过度使用¶

❌ 错误：

数据是中心——不是模型——也不是 Prompt——而是数据。

✅ 正确：

数据是中心。模型和 Prompt 都不是。

三段式排比¶

❌ 错误：

它是数据的底座。它是知识的源头。它是 AI 的起点。

✅ 正确：

它是数据底座，也是 AI 系统理解业务的起点。

否定式排比¶

❌ 错误：

它不是 RDF，不是 OWL，不是知识图谱，不是图数据库。

✅ 正确：

这些只是 Ontology 的可能实现技术，不是 Ontology 本身。

空泛开场¶

❌ 错误：

在当今 AI 飞速发展的时代，数据工程师面临着前所未有的机遇与挑战。

✅ 正确：

直接进入工程问题。

8.4 判定规则¶

如果一段话删掉后，章节的工程信息没有任何损失，删除它。

如果一段话在多个主题之间通用，它太空，重写或删除。

如果一段话读起来像产品发布会文案，重写。

九、章节完成标准 Checklist¶

完成一章之前，检查是否回答：

为什么需要它？
为什么数据工程师应该关心？
它解决什么问题？
它属于 DDA 哪一层？
它改变了哪些架构设计？

如果不能回答，说明章节尚未完成。

9.1 额外自检¶

是否先讲 Why 再讲 How？
是否有图，且每张图有解读？
代码是否用于解释架构而非展示技巧？
是否围绕核心思想而非工具组织？
是否符合 GLOSSARY.md 的术语？
是否避免了 WRITING_STYLE.md 第八章的全部 AI 痕迹？

十、本文件的修订规则¶

新增写作规则需要给出正反例。

修订术语相关规则需要同步 GLOSSARY.md。

修订图相关规则需要同步 DIAGRAM_GUIDE.md。