name: 技术文章 description: 撰写技术文章和博客帖子。在创建文档/文章或博客内容以解释模式、技术或经验教训时使用。

技术文章

所有文章必须遵循writing-voice规则。

核心原则

标题应该是要点，而不是主题。“写入上下文到文件，而不是提示”而不是“代理工作流中的上下文管理”。

以强有力的开场段落开头，用平实语言陈述关键见解。读者应在5秒内理解。然后直接进入代码。不要在开场后强制添加引用块或拉引号；如果见解需要一个可引用的摘要，开场段落已经是一个。

代码比散文更有说服力。展示来自实际代码库的真实示例，而不是抽象的foo/bar插图。如果代码自解释，不要过度解释。

章节标题是论点

章节标题应该提出主张，而不是宣布主题。读者应该从标题 alone 知道你的立场。

坏（主题标题）：

二进制中包含什么

Go 和 Rust 比较如何

为什么树摇困难

好（论点标题）：

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

Bun（和 Deno/Node）：你的代码运行在 VM 之上

为什么树摇运行时极其困难

第一组描述了章节是关于什么。第二组告诉你章节论证什么。只浏览标题的读者应该带走文章的核心论点。

这也适用于标题：“Bun 编译是 57MB 因为它不是你的代码”是一个论点。“理解 Bun 编译二进制大小”是一个主题。

对话式直接性

写作像向同行解释，而不是向观众展示。短声明句。观点直率陈述。让步承认而不回避。

坏（正式文章语）：

bun build --compile 命令的结果包大小显著大。通过仔细分析，我们可以识别几个贡献因素。

好（直接，对话式）：

console.log("Hello World") 编译到 57MB。你的代码几乎不添加任何东西。二进制是整个 Bun 运行时。

括号旁白、破折号强调和句子片段都可以，当它们服务于清晰性时。“剥离 JIT？现在你的代码运行慢 10-100 倍。”比正式构造的替代品读起来更好。

多部分论点的编号粗体点

当解释 WHY 某事是这种情况，并且有多个独立原因时，使用编号粗体点。每个点得到一个粗体标题、简短解释和可选的代码块。

**1. JavaScriptCore 是单体的（~40MB+ 的二进制）**

它是苹果的 JS 引擎。Bun 不拥有它。你不能移除“你不使用的部分”，因为它是一个紧密耦合的 C++ 代码库。

**2. `eval()` 和动态导入破坏静态分析**

Go 和 Rust 在编译时确切知道调用了什么函数。
JavaScript 不：

\`\`\`js
const module = await import(userInput)
\`\`\`

**3. Node.js 兼容性是一个巨大的表面积**

Bun 承诺 Node 兼容。那意味着所有 node:fs, node:http, 等。

这个模式有效，因为每个原因独立存在。读者可以浏览粗体行并得到要点，或深入阅读感兴趣的部分。保留这个用于 3-5 个原因；少于 3 个应该只是散文，多于 5 个需要合并。

用于架构或流的 ASCII 图：

对话          规范文件          子代理
    │                    │                   │
    │  写入上下文        │                   │
    │───────────────────>│                   │
    │                    │                   │
    │                    │   读取文件        │
    │                    │<──────────────────│
    │                    │                   │
    │                    │   新鲜上下文      │
    │                    │──────────────────>│

用于比较的表格（浏览友好，尊重读者时间）：

而不是	做这个
复制粘贴上下文	写入规范文件
重新解释每个提示	传递文件名

节奏和步调

这是最重要的部分。好文章在散文和视觉之间交替。读者的眼睛应该跳跃：上下文 → 代码 → 解释 → 图 → 含义。散文或代码都不应该长时间主导。

规则

在代码块、图或表格之前最多 3-4 句散文。 如果你写更多而没有视觉中断，你错过了一个机会。
每个代码块在之前得到 1-2 句设置。 不要没有上下文地放置代码。但也不要写一个段落。
代码块后，一句解释通常足够。 如果代码自解释，完全跳过它并桥接到下一个想法。
在不同思想之间使用换行。 不要将三个想法打包到一个段落。每个段落：一个想法。

好节奏 — 散文和代码交替：

[1-2 句：问题是什么]

\`\`\`typescript
// 代码显示问题
const result = table.find(id);  // O(n) 每次扫描
\`\`\`

[1 句：为什么这不好，桥接到解决方案]

\`\`\`typescript
// 代码显示解决方案
const result = index.get(id);   // O(1) 查找
\`\`\`

[1-2 句：这对读者意味着什么]

坏节奏 — 散文墙，代码在末尾：

[段落解释问题]
[段落解释方法]
[段落解释实现]
[段落解释结果]

\`\`\`typescript
// 底部的单个代码块
\`\`\`

第一个版本让读者在过程中验证每个主张对代码。第二个强制他们记住四个段落，然后心理映射到代码。

写开场

开场段落承载整篇文章。如果有人什么都不读，这个段落应该给他们见解。

坏（主题宣布）：

在本文中，我们将探讨上下文管理如何在代理工作流中工作，并讨论一些改进方法。

好（见解在前）：

写入你的上下文到文件，而不是提示。当对话产生子代理时，每个都从空白开始。如果上下文只存在于对话中，你会每次重新解释它。写入到文件，这样每个代理可以读取新鲜上下文，而不是依赖漂移的复制粘贴提示片段。

坏版本告诉读者文章是关于什么。好版本告诉他们答案。他们会继续阅读以看为什么。

写解释性散文

当你需要在代码块之间解释某事如何工作时，展示机制。不要抽象描述。

坏（抽象叙述）：

系统使用分层方法来高效处理数据存储。每层提供不同级别的抽象，允许消费者以适合他们用例的适当粒度与数据交互。

好（展示机制）：

RowStore 包装 CellStore，它包装 YKeyValueLww。每层添加一件事：YKeyValueLww 处理冲突解决，CellStore 解析单元键为行/列对，RowStore 维护内存索引用于 O(1) 查找。消费者只看到 RowStore。

第一版可以描述任何东西。第二版只能描述这个系统。

约束

项目符号列表和编号列表：每篇文章最多 1-2 个。如果需要更多，转换为散文或表格。

章节标题：谨慎使用。不是每个段落都需要标题。让内容在思想之间自然流动，使用桥接句（见writing-voice “无标题连接思想”）。

粗体文本：避免在正文内容中使用。如果需要强调，谨慎使用。

无空格-破折号-空格：使用冒号、分号或破折号 per writing-voice。

无刚性模板：结构应该适合内容，而不是反之亦然。一些文章需要“问题/解决方案”流；其他只显示代码和解释。不要强制章节。

参考：完整文章骨架

这不是一个机械遵循的模板。它是一个参考，展示一个节奏良好的 60 行文章看起来像什么。你文章的结构应该适合其内容。

# 写入上下文到文件，而不是提示

当对话产生子代理时，每个都重新开始。如果你的上下文
只存在于对话中，你会每次重新解释它。写入到文件。

```typescript
// 而不是用嵌入式上下文制作长提示：
task({ prompt: `这里是模式：${schema}。这里是迁移计划：${plan}。现在实现步骤 3...` })

// 写入上下文到规范文件，然后引用它：
await writeFile('specs/migration-plan.md', context);
task({ prompt: '读取 specs/migration-plan.md 并实现步骤 3。' })
```

规范文件一举解决三个问题。子代理获得完整上下文而不
提示膨胀。上下文在调用之间不漂移，因为有一个
真理源。你可以自己读取文件以验证代理工作基于什么。

```
对话          规范文件          子代理
    │                    │                   │
    │  写入上下文        │                   │
    │───────────────────>│                   │
    │                    │   读取文件        │
    │                    │<──────────────────│
    │                    │                   │
    │                    │   新鲜上下文      │
    │                    │──────────────────>│
```

这也改变你如何思考代理提示。而不是“给代理
所有它需要的上下文”，问题变成“规范文件包含
一切吗？” 这是一个更好的问题，因为你可以检查它：打开文件，
读取它，看它是否完整。

| 无规范文件             | 有规范文件              |
| ----------------------------- | --------------------------- |
| 上下文每次调用漂移      | 单真理源                |
| 提示随复杂性增长        | 提示保持短              |
| 不能验证代理看到什么    | 自己读取文件            |
| 代理间复制粘贴          | 所有代理读取相同文件    |

开销是一个文件写入。回报是对话中的
每个子代理工作于相同的、可验证的上下文。

注意模式：开场见解 → 代码显示技术 → 散文解释为什么 → ASCII 图显示流 → 表格总结比较 → 一句结束。每个散文部分 2-4 句。每个视觉赢得其位置。

什么使文章好

来自真实代码库的真实代码，不是抽象示例
阐明架构或数据流的 ASCII 图
一个总结关键比较的表格
解释 WHY 而不是 WHAT 的紧密散文（代码显示 WHAT）
散文和视觉每 2-4 句交替
开场段落传递见解，而不是主题宣布
30-80 行用于聚焦见解文章；比较或分析文章自然地运行 80-150+ 当显示来自多个库的代码时

什么使文章坏

不适合内容的刚性部分结构
整个多项目符号列表和编号列表
抽象 foo/bar 代码示例
过度解释自解释代码
正文中分散的粗体格式
营销语言或 AI 赠品
超过 4-5 句散文没有视觉中断
开场宣布主题而不是传递见解
结束试图宏大总结或行动号召

叙事模式（罕见）

大多数“洞察之旅”文章仍然更好地作为 punchy。仅在发现过程本身是见解且无法压缩时使用叙事。

当叙事适合时：具体细节（“750 行”，不是“一个大文件”），直接陈述 over 制造戏剧，建立到见解而不是以它开始。

结束

以含义的平实陈述结束。不要试图宏大总结或聪明结束。如果文章显示 X 解决 Y，只说这对读者意味着什么在一两句话中。避免以最高级（“最优雅”、“真正强大”）或行动号召（“今天试试！”）结束。