technical-articles

技术文章

所有文章都必须遵循 writing-voice 规则。此技能规定文章结构；writing-voice 规定统一的语气和标点。

核心原则

标题应该直接点明要传达的结论，而不是话题。“将上下文写入文件，而不是提示词”，而不是“Agent 工作流中的上下文管理”。

开篇用有力的段落，用通俗的语言说清关键见解。读者应该能在 5 秒内 get 到要点。接着直接进入代码。开篇之后不要硬塞引用块或摘录；如果需要用一句话概括要点，开篇段落本身就已经做到了。

代码胜过千言。展示真实代码库中的实际示例，而不是抽象的 foo/bar 示例。如果代码一目了然，就不要过度解释。

保持文章原有的视角高度。如果草稿讲的是普遍经验，并配有真实代码示例，就不要把文章重心转移到当前项目的问题上。代码是经验的佐证，不会自动成为主题。应让可复用的见解始终处于焦点，并将项目特有的机制放在规范文档、参考文档或实现说明中。

小节标题要表明观点

小节标题应该提出论点，而不是介绍话题。读者只看标题，就应该能知道你的立场。

不佳（话题式标题）：

二进制里有什么

Go 和 Rust 有何不同

为什么很难进行 tree-shaking

较好（论点式标题）：

Go 和 Rust：你的代码就是二进制

Bun（以及 Deno/Node）：你的代码运行在虚拟机之上

对运行时进行 tree-shaking 难得离谱

第一组标题描述小节的主题。第二组标题则告诉读者小节要论证什么。只浏览标题的读者，也应该能掌握文章的核心论点。

标题本身也适用这一原则：“Bun Compile 有 57MB，因为那不是你的代码”是一个论点。“了解 Bun Compile 的二进制大小”只是一个话题。

直率、自然地交流

写得像是在向同行解释，而不是在台上做演讲。使用简短的陈述句。直截了当地表达观点。承认让步，但不要含糊其辞。

不佳（正式的文章腔）：

bun build --compile 命令生成的包体积明显偏大。经过仔细分析，我们可以找出造成这一结果的几个因素。

较好（直接、自然）：

console.log("Hello World") 编译后会有 57MB。你的代码几乎没增加体积。整个二进制就是完整的 Bun 运行时。

只要有助于表达清晰，括号中的补充说明、强调性标点和不完整句都可以。“去掉 JIT？那你的代码会慢 10-100 倍。”读起来就比正式完整的句式更好。

视觉元素是工具，不是必选项

ASCII 图、表格和前后对比代码块，都是在能比文字更清楚地说明问题时可以使用的工具，并非必备要素。

展示难以线性描述的流程或架构时，用图。确实有 3 项或更多内容需要比较时，用表格。对比本身就是重点时，用前后对比代码。文章不需要时，就都不要用。

如果有多个彼此独立的原因要说明，就用自然过渡把它们写成普通段落。不要使用编号的粗体标题（**1. 粗体标题**，后接解释）：这种写法是最明显的 AI 写作痕迹之一。

架构文章的构思

对于讨论所有权、路由、身份验证、计费、同步、多租户、API 形态或部署边界的文章，请先构建私有模型，再起草面向读者的论述。

1. 构建私有模型：所有权、边界、流程、正反示例和持久规则。
2. 将该模型转化为面向读者的论述：标题、开篇、各节主张、节奏、代码、图表和结尾。
3. 全程使用 写作风格 作为统一文风，并在最后检查标点。

除非文章有意采用笔记风格，否则不要原样发布私有模型。模型是思考的格式；文章是读者阅读的格式。

架构文章的私有模型要回答四个问题：旧模型是什么、什么迹象表明它不再适用、新模型是什么，以及需要记住的规则是什么。

节奏与行文节拍

这是最重要的一节。好的文章会交替使用文字和视觉内容。读者的视线应当来回切换：背景 → 代码 → 解释 → 图表 → 含义。无论文字还是代码，都不应长时间占据主导。

规则

1. 连续写 3～4 句文字后，最多就应插入代码块、图表或表格。 如果没有视觉上的停顿，却写了更多内容，那你就错过了一个机会。
2. 每个代码块前都要用 1～2 句话铺垫。 不要毫无背景地直接贴出代码，但也不必写成一整段。
3. 代码块后通常一句解释就够了。 如果代码一目了然，可以完全省略解释，直接衔接下一个观点。
4. 不同想法之间要换行。 不要把三个想法塞进同一段。每段只讲一个想法。

良好的节奏：文字与代码交替：

[1-2 sentences: what the problem is]

\`\`\`typescript
// code showing the problem
const result = table.find(id);  // O(n) scan every time
\`\`\`

[1 sentence: why this is bad, bridge to solution]

\`\`\`typescript
// code showing the solution
const result = index.get(id);   // O(1) lookup
\`\`\`

[1-2 sentences: what this means for the reader]

糟糕的节奏：大段文字，最后才出现代码：

[Paragraph explaining the problem]
[Paragraph explaining the approach]
[Paragraph explaining the implementation]
[Paragraph explaining the result]

\`\`\`typescript
// single code block at the bottom
\`\`\`

第一个版本让读者能边读边用代码验证每个论点。第二个版本迫使读者先记住四段文字，再在脑海中把它们与代码对应起来。

撰写开篇

开篇段落承载着整篇文章的核心。即使读者什么都不再往下读，这一段也应当让他们领会文章的洞见。

糟糕的写法（宣布主题）：

本文将探讨 Agent 工作流中的上下文管理，并讨论一些改进方法。

好的写法（开门见山地给出洞见）：

把上下文写入文件，而不是提示词。当一次对话启动多个子 Agent 时，每个 Agent 都会从一张白纸开始。如果上下文保存在磁盘上的规范文件中，每个 Agent 都能重新读取，而不必依赖那些复制粘贴后逐渐偏离原意的提示词片段。

糟糕的版本只是告诉读者文章要讲什么。好的版本直接告诉读者答案。他们会继续读下去，看看其中的缘由。

用户提供了自己的声音，就用它

如果文章源自语音转录、聊天头脑风暴，或口头推理，用户自己的措辞就是文章的声音。把这些措辞重写成“更好”的英语，会抹去让洞见产生感染力的节奏——用户也认不出页面上写的是自己的想法。他们会失去兴趣。

检验方法：一周后，用户快速浏览自己的文章时，是否还能感受到当初促使他们想写这篇文章的那股劲？如果开篇被润色成千篇一律的技术文风，答案就是否定的。

规则

1. 在第一段中使用用户的原话。 不要改述，也不要润色。只为语法做轻微调整，绝不改变语气。即使有些表达略显别扭（“我知道这是个坏味道，因为……”），也比更流畅的改写好，因为这才是用户真正的想法，也是他们记住文章的方式。

2. 如果有核心代码转换，应在前约 100 个词内展示。 转换前后的代码都要出现在首屏中。文字负责解释，代码才是文章本身。若把代码转换埋在铺垫段落下面，读者可能根本看不到。

3. 从转录内容中逐字引用具体表达。 如果用户说“我知道我做了一个 Svelte 专用版本”，就用这句话，不要改成“我创建了一个框架专用适配器”。原话的具体细节就是表达风格。

4. 忠于原话胜过润色。 根据转录内容起草时，即使有更优雅的句子，也应尽量保留用户的表达。用户曾在脑海中形成过这个想法，文章应与那个想法一致，这样他们重读时才能再次感受到它。

不佳（重构后的表达）

在实现过程中，我们发现框架专用适配器之间存在紧密耦合。我们逐渐发现，响应式跟踪被当作事件订阅机制使用，这似乎表明存在更深层的架构问题。

良好（用户的原话）

我意识到自己做了一个 Svelte 专用版本。我知道这是个坏味道，因为我只是为了跟踪 auth.token 才调用 $effect。这让我觉得自己真正想要的是一个命令式的 onTokenChange：而这个 API 之所以不存在，唯一的原因就是我一直在 Svelte 之上封装 Svelte。

第一个版本可以直接发布。第二个版本听起来像是有人在边想边说，而这正是用户提供转录内容时的状态。

撰写解释性文字

需要在代码块之间解释工作原理时，要展示具体机制。不要抽象地描述。

不佳（抽象叙述）：

系统采用分层方法来高效处理数据存储。每一层都提供不同级别的抽象，让使用者可以根据使用场景，以恰当的粒度与数据交互。

良好（展示具体机制）：

RowStore 封装 CellStore，而 CellStore 又封装 YKeyValueLww。每一层只增加一项功能：YKeyValueLww 处理冲突解决，CellStore 将单元格键解析为行列对，而 RowStore 则维护内存索引，以实现 O(1) 查找。使用者只会接触到 RowStore。

第一个版本可以用来描述任何系统。第二个版本只能描述这个系统。

约束

项目符号列表和编号列表：每篇文章最多各使用 1 到 2 个。如果需要更多列表，请改用段落或表格。

章节标题：谨慎使用。不必为每个段落都加标题。让内容通过衔接句自然展开（参见 writing-voice“不使用标题衔接观点”）。

正文中避免使用粗体。如需强调，可少量使用。

不要使用“空格-连字符-空格”。标点遵循 writing-voice：不要使用 en dash，em dash 也只在确实需要强调时使用。文章中仍应优先使用句号、冒号、分号、逗号或括号。

不要套用僵化模板：结构应服务于内容，而不是反过来。有些文章适合“问题/解决方案”的脉络，有些只需展示代码并加以解释。不要强行划分章节。

文章各有不同的形态

不要遵循单一模板。结构应与内容相匹配。以下是一些常见形态：

问题 → 修复（简短、实用）：说明问题，展示修复问题的代码，并解释原因。无需图示、表格或额外章节。30-50 行。

机制解析（中等篇幅）：解释某项机制在底层的运作方式，穿插说明文字和代码。流程不明显时可使用图示。50-80 行。

比较或权衡分析（篇幅较长）：展示两种或更多方案的真实代码。此时表格会很有用，因为比较本身就是重点。如果不同方案的架构各异，可使用 ASCII 图示。80-150 行。

文章的形态应由内容决定。如果你发现自己是在添加图示或表格来填补想象中的空缺，那就不需要添加。

好文章的特点

• 使用真实代码库中的实际代码，而非抽象示例
• 文字简洁，解释原因（WHY），而非内容本身（WHAT）；代码负责展示 WHAT
• 文字说明与视觉元素自然交替；两者都不要长时间占据主导
• 开篇段落直接给出洞见，而不是宣布主题
• 视觉元素（图示、表格）只在确有必要时使用
• 篇幅与内容相符：专注于修复的文章为 30-50 行，比较类文章为 80-150 行

糟糕文章的特点

• 僵化的章节结构与内容不匹配
• 通篇使用多组项目符号列表和编号列表
• 抽象的 foo/bar 代码示例
• 对一目了然的代码过度解释
• 在正文中零散地使用粗体格式
• 多部分论述采用加粗编号标题（**1. 加粗标题** 模式）
• 在结尾附上重复正文已有内容的总结表格
• 营销话术或明显带有 AI 痕迹的表达
• 连续使用超过 4-5 句文字说明，中间没有视觉分隔
• 开篇宣布主题，而不是直接给出内容
• 结尾强行拔高，或添加行动号召

叙事模式（罕见）

大多数“探索并获得洞见”的文章，采用简明有力的写法效果更好。只有当发现过程本身就是洞见，且无法压缩时，才使用叙事。

适合叙事时：提供具体细节（“750 行”，而不是“一份大文件”），直接陈述而非刻意制造戏剧性，逐步引出洞见，而不是一开篇就点明。

结尾

以平实的陈述说明其含义。不要强行拔高总结，也不要刻意设计俏皮的收尾。如果文章说明了 X 能解决 Y，只需用一两句话说明这对读者意味着什么。避免以最高级表达（“最优雅”“真正强大”）或行动号召（“今天就试试！”）收尾。