technical-articles

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Technical Articles

技术文章撰写

All articles must follow writing-voice rules.

所有文章必须遵循写作语气规范。

Core Principles

核心原则

Title should BE the takeaway, not a topic. "Write Context to a File, Not a Prompt" not "Context Management in Agent Workflows".

Lead with a strong opening paragraph that states the key insight in plain language. Reader should get it in 5 seconds. Then go straight into code. Don't force a blockquote or pull-quote after the opening; if the insight needs a quotable summary, the opening paragraph already is one.

Code speaks louder than prose. Show real examples from actual codebases, not abstract

foo

bar

illustrations. If the code is self-explanatory, don't over-explain.

ASCII diagrams for architecture or flow:

Conversation          Spec File           Subagent
    │                    │                   │
    │  write context     │                   │
    │───────────────────>│                   │
    │                    │                   │
    │                    │   read file       │
    │                    │<──────────────────│
    │                    │                   │
    │                    │   fresh context   │
    │                    │──────────────────>│

Tables for comparisons (skim-friendly, respect reader time):

Instead of	Do this
Copy-pasting context	Write to spec file
Re-explaining each prompt	Pass the filename

标题应直接呈现核心结论，而非仅点明主题。例如用「将上下文写入文件，而非嵌入提示词」代替「Agent工作流中的上下文管理」。

开篇段落需直入核心，用平实语言阐明关键洞见，让读者在5秒内理解核心内容。随后直接展示代码。开篇后无需强行添加引用块或引言；若洞见需要可引用的总结，开篇段落本身就应承担这个作用。

代码比文字更有说服力。展示来自真实代码库的实际示例，而非抽象的

foo

bar

示例。如果代码本身就能说明问题，无需过度解释。

架构或流程可使用ASCII流程图：

Conversation          Spec File           Subagent
    │                    │                   │
    │  write context     │                   │
    │───────────────────>│                   │
    │                    │                   │
    │                    │   read file       │
    │                    │<──────────────────│
    │                    │                   │
    │                    │   fresh context   │
    │                    │──────────────────>│

对比内容可使用表格（便于快速浏览，尊重读者时间）：

不建议做法	建议做法
复制粘贴上下文	写入规格文件
每次提示都重复解释上下文	传递文件名

Rhythm and Pacing

节奏与篇幅控制

This is the most important section. Good articles alternate between prose and visuals. The reader's eye should bounce: context → code → explanation → diagram → implication. Neither prose nor code should dominate for long stretches.

这是最重要的部分。优质的技术文章应交替呈现文字与可视化内容，让读者的注意力自然流转：上下文说明 → 代码展示 → 解释 → 流程图 → 实际意义。文字或代码都不应长时间占据主导。

The Rules

规则

Max 3-4 sentences of prose before a code block, diagram, or table. If you're writing more than that without a visual break, you're missing an opportunity.
Every code block gets 1-2 sentences of setup before it. Don't drop code without context. But don't write a paragraph either.
After a code block, one sentence of explanation is often enough. If the code is self-explanatory, skip it entirely and bridge to the next idea.
Use line breaks between distinct thoughts. Don't pack three ideas into one paragraph. Each paragraph: one idea.

在插入代码块、流程图或表格之前，文字内容最多保留3-4句话。 如果你的文字超过这个长度还没有视觉化内容穿插，说明你错失了优化阅读体验的机会。
每个代码块之前需用1-2句话说明背景。 不要毫无铺垫地直接展示代码，但也无需写一整段说明。
代码块之后通常用1句话解释即可。 如果代码本身就能自我解释，可完全跳过解释，直接过渡到下一个观点。
不同观点之间用换行分隔。 不要把三个观点塞进一个段落。每个段落只表达一个核心观点。

Good rhythm — prose and code alternate:

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

[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]

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

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

[1句话：说明问题的影响，过渡到解决方案]

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

[1-2句话：说明该方案对读者的实际意义]

Bad rhythm — wall of prose, code at the end:

糟糕节奏示例：大段文字+末尾代码

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

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

The first version lets the reader verify each claim against code as they go. The second forces them to hold four paragraphs in memory, then mentally map them to code.

[段落1：解释问题]
[段落2：说明解决思路]
[段落3：解释实现方式]
[段落4：说明结果]

\`\`\`typescript
// 仅在末尾放置单个代码块
\`\`\`

第一种方式让读者可以边读边对照代码验证每个观点。第二种方式则要求读者记住四段文字的内容，再在脑中与代码对应。

Writing the Opening

开篇撰写

The opening paragraph carries the entire article. If someone reads nothing else, this paragraph should give them the insight.

Bad (topic announcement):

In this article, we'll explore how context management works in agent workflows and discuss some approaches to improving it.

Good (insight up front):

Write your context to a file, not a prompt. When a conversation spawns sub-agents, each one starts with a blank slate. If the context lives in a spec file on disk, every agent can read it fresh instead of relying on copy-pasted prompt fragments that drift.

The bad version tells the reader what the article is about. The good version tells them the answer. They'll keep reading to see why.

开篇段落承载了整篇文章的核心价值。如果读者只读这一段，也应能获取核心洞见。

反面示例（仅点明主题）：

在本文中，我们将探讨Agent工作流中的上下文管理方式，并讨论一些优化方法。

正面示例（直接呈现洞见）：

将上下文写入文件，而非嵌入提示词。当对话生成子Agent时，每个子Agent都会从零开始。如果上下文存储在磁盘的规格文件中，每个Agent都可以读取最新的上下文，无需依赖容易出现偏差的复制粘贴式提示片段。

反面示例只是告诉读者文章的主题，而正面示例直接给出答案，能吸引读者继续阅读以了解原因。

Writing Explanatory Prose

说明性文字撰写

When you need to explain how something works between code blocks, show the mechanism. Don't describe it abstractly.

Bad (abstract narration):

The system uses a layered approach to handle data storage efficiently. Each layer provides a different level of abstraction, allowing consumers to interact with data at the appropriate granularity for their use case.

Good (shows the mechanism):

RowStore
wraps
CellStore
, which wraps
YKeyValueLww
. Each layer adds one thing:
YKeyValueLww
handles conflict resolution,
CellStore
parses cell keys into row/column pairs, and
RowStore
maintains an in-memory index for O(1) lookups. The consumer only sees
RowStore
.

The first version could describe anything. The second version could only describe this system.

当你需要在代码块之间解释工作机制时，要展示具体的实现逻辑，而非抽象描述。

反面示例（抽象叙述）：

该系统采用分层方法高效处理数据存储。每一层提供不同的抽象级别，让使用者可以根据自身用例选择合适的粒度与数据交互。

正面示例（展示具体机制）：

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

第一个示例可以描述任何系统，而第二个示例只能描述当前这个系统。

Constraints

约束条件

Bullet lists and numbered lists: max 1-2 of each per article. If you need more, convert to prose or a table.

Section headings: use sparingly. Not every paragraph needs a heading. Let content flow naturally between ideas using bridge sentences (see writing-voice "Connect ideas without headers").

Bold text: avoid in body content. Use sparingly if needed for emphasis.

No space-dash-space: use colons, semicolons, or em dashes per writing-voice.

No rigid template: structure should fit the content, not the other way around. Some articles need a "Problem/Solution" flow; others just show code and explain. Don't force sections.

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

章节标题：谨慎使用。并非每个段落都需要标题。使用过渡句让内容在观点间自然流转（参见写作语气规范中的「无需标题，用过渡句连接观点」）。

粗体文字：正文内容中尽量避免。如需强调，谨慎使用。

不要使用空格-短横线-空格的格式：根据写作语气规范，使用冒号、分号或破折号。

不要使用僵化模板：结构应适配内容，而非相反。有些文章适合「问题/解决方案」的结构；有些则只需展示代码并解释。不要强行划分章节。

Reference: Complete Article Skeleton

参考：完整文章框架

This is NOT a template to follow mechanically. It's a reference showing what a well-paced 60-line article looks like. Your article's structure should fit its content.

undefined

这并非必须机械遵循的模板，而是展示一篇节奏良好的60行文章的参考示例。你的文章结构应适配自身内容。

undefined

Write Context to a File, Not a Prompt

将上下文写入文件，而非嵌入提示词

When a conversation spawns sub-agents, each one starts fresh. If your context lives only in the conversation, you'll re-explain it every time. Write it to a file instead.

typescript

// Instead of crafting a long prompt with embedded context:
task({ prompt: `Here's the schema: ${schema}. Here's the migration plan: ${plan}. Now implement step 3...` })

// Write context to a spec file, then reference it:
await writeFile('specs/migration-plan.md', context);
task({ prompt: 'Read specs/migration-plan.md and implement step 3.' })

The spec file solves three problems at once. Sub-agents get full context without prompt bloat. The context doesn't drift between invocations because there's one source of truth. And you can read the file yourself to verify what agents are working from.

Conversation          Spec File           Sub-agent
    │                    │                   │
    │  write context     │                   │
    │───────────────────>│                   │
    │                    │   read file       │
    │                    │<──────────────────│
    │                    │   fresh context   │
    │                    │──────────────────>│

This also changes how you think about agent prompts. Instead of "give the agent all the context it needs," the question becomes "does the spec file contain everything?" That's a better question because you can check it: open the file, read it, see if it's complete.

Without spec file	With spec file
Context drifts per invocation	Single source of truth
Prompt grows with complexity	Prompt stays short
Can't verify what agent sees	Read the file yourself
Copy-paste between agents	All agents read same file

The overhead is one file write. The payoff is every sub-agent in the conversation working from the same, verifiable context.


Notice the pattern: opening insight → code showing the technique → prose explaining why → ASCII diagram showing the flow → table summarizing the comparison → one-sentence closing. Each prose section is 2-4 sentences. Each visual earns its place.

当对话生成子Agent时，每个子Agent都会从零开始。如果上下文仅存在于对话中，你需要反复解释它。不如将其写入文件。

typescript

// 不要编写包含嵌入上下文的冗长提示词：
task({ prompt: `Here's the schema: ${schema}. Here's the migration plan: ${plan}. Now implement step 3...` })

// 应将上下文写入规格文件，然后引用它：
await writeFile('specs/migration-plan.md', context);
task({ prompt: 'Read specs/migration-plan.md and implement step 3.' })

规格文件可同时解决三个问题。子Agent无需通过冗长的提示词即可获取完整上下文；上下文不会因多次调用而出现偏差，因为存在唯一的可信来源；你也可以直接读取文件，验证Agent所使用的内容。

Conversation          Spec File           Sub-agent
    │                    │                   │
    │  write context     │                   │
    │───────────────────>│                   │
    │                    │                   │
    │                    │   read file       │
    │                    │<──────────────────│
    │                    │                   │
    │                    │   fresh context   │
    │                    │──────────────────>│

这也会改变你设计Agent提示词的思路。不再是「给Agent提供所有需要的上下文」，而是思考「规格文件是否包含了所有内容？」这是一个更优的问题，因为你可以直接验证：打开文件，查看内容是否完整。

无规格文件的情况	使用规格文件的情况
上下文在多次调用中出现偏差	唯一可信来源
提示词随复杂度增加而变长	提示词保持简洁
无法验证Agent所获取的内容	可直接读取文件验证
在Agent间复制粘贴上下文	所有Agent读取同一文件

只需一次文件写入操作，就能让对话中的所有子Agent基于相同的、可验证的上下文工作。


注意其中的模式：开篇洞见 → 展示技术的代码 → 解释原因的文字 → 展示流程的ASCII图 → 总结对比的表格 → 简洁的收尾语句。每个文字部分为2-4句话。每个可视化内容都有其存在的价值。

What Makes Articles Good

优质文章的特征

Real code from real codebases, not abstract examples
ASCII diagrams that clarify architecture or data flow
One table that summarizes the key comparison
Tight prose that explains WHY, not WHAT (code shows WHAT)
Prose and visuals alternate every 2-4 sentences
Opening paragraph delivers the insight, not a topic announcement
30-80 lines for focused insight articles; comparison or analysis articles naturally run 80-150+ when showing code from multiple libraries

使用来自真实代码库的代码，而非抽象示例
使用ASCII流程图阐明架构或数据流
用一个表格总结核心对比
文字简洁，专注于解释「为什么」而非「是什么」（「是什么」由代码展示）
每2-4句文字后穿插可视化内容
开篇直接呈现洞见，而非仅点明主题
聚焦单一洞见的文章为30-80行；对比或分析类文章若展示多个库的代码，篇幅自然会达到80-150+行

What Makes Articles Bad

劣质文章的特征

Rigid section structure that doesn't fit the content
Multiple bullet lists and numbered lists throughout
Abstract
```
foo
```
/
```
bar
```
code examples
Over-explaining self-explanatory code
Bold formatting scattered through body text
Marketing language or AI giveaways
More than 4-5 sentences of prose without a visual break
Opening that announces the topic instead of delivering the insight
Closing that reaches for a grand summary or call to action

使用与内容不符的僵化章节结构
全文使用多个项目符号列表和编号列表
使用抽象的
```
foo
```
/
```
bar
```
代码示例
过度解释本身就能自我说明的代码
正文中大量使用粗体格式
包含营销语言或AI生成痕迹
超过4-5句文字后仍无可视化内容穿插
开篇仅点明主题而非呈现洞见
结尾强行进行宏大总结或呼吁行动

Narrative Mode (Rare)

叙事模式（罕见）

Most "journey to an insight" articles still work better as punchy. Use narrative only when the discovery process itself is the insight and can't be compressed.

When narrative fits: specific details ("750 lines", not "a large file"), direct statements over manufactured drama, build to an insight rather than starting with it.

大多数「洞见探索过程」类文章仍以简洁直接的风格呈现效果更佳。仅当发现过程本身就是核心洞见且无法压缩时，才使用叙事模式。

适合使用叙事模式的情况：包含具体细节（如「750行」而非「一个大文件」），直接陈述而非刻意制造戏剧化效果，逐步推进至洞见而非开篇直接给出。

Closings

结尾撰写

End with a plain statement of the implication. Don't reach for a grand summary or a clever sign-off. If the article showed that X solves Y, just say what that means for the reader in one or two sentences. Avoid closing with superlatives ("the most elegant", "truly powerful") or calls to action ("try it today!").

用平实的语句陈述实际影响即可收尾。不要强行进行宏大总结或使用巧妙的结束语。如果文章展示了X解决了Y，只需用1-2句话说明这对读者的意义。避免用最高级（如「最优雅的」「真正强大的」）或呼吁行动（如「今天就试试！」）收尾。