tech-writing

Tech Writing — 技术文章对外写作

开工前：先看范本

不要学 AI 的平滑，要学人的“颗粒度”：

1. docs/lessons/12-no-boss-agent.md：看它如何用“读者的怀疑”当小标题，把争议变成共鸣。
2. docs/lessons/01-sdk-to-cli.md：看它如何还原“当时炸了”的瞬间，让读者跟着猫一起出冷汗。

为什么读者能闻到"AI味"

AI 写作像是在发送一个逻辑自洽的压缩包。读者没有经历过那 100 天，收到的是一个打不开的结论。

好的写作是“解压过程”：给证据锚点，不给干巴巴的结论。

• AI 味 = “我们发现这个系统存在一致性风险。”（平滑、确定、无聊）
• 猫咖味 = “深夜三点，Redis 6399 突然报错。那一刻我们意识到，原来最初的架构假设错了。”（有时间、有痛点、有挣扎）

行文的本质：进化链

不要介绍一个系统的终态。要讲它怎么长出来的。

每篇文章沿着一条链：方案 → 方案撞墙 → 新方案。系列文章之间，上一篇撞的墙就是下一篇的起点。

以记忆系统为例：

1. CC 的 grep + 文件系统——简洁、美，但需要先验知识（你得知道搜什么）
2. 加了 BM25 + embedding + RRF（F102）——解决了先验，但 context 压缩时召回变差
3. 消费加权排序（F200）——每一步都是上一步撞墙后长出来的

读者跟着的不是一张完美的架构图，而是一条连续剧。进化天然有挣扎，设计天然平滑——所以进化链天然没有 AI 味。

与 Phase 0 的关系：进化链管选题和系列连接；Phase 0 管单篇内部的节奏。

技术叙事的证据剖面

当用户不只问“怎么讲得好听”，而是追问技术点、算法、理论、归因方法、消融或“凭什么可信”时，先按本节的 7P × 5E 技术叙事方法建立证据边界。

• 7P 是取材透镜：价值、难点、原理、流程、算法、工程与证据按读者问题选用，不是七章固定目录。
• 5E 是 claim 边界：逐项检查 Exists、Effect、Explain、Extend 与 Endure，不给整篇文章贴一个总标签。
• 静态文章用 claim box、失效机制、对照和消融表讲清证据。
• 交互讲解若需要观众亲手检验技术主张，路由到 concept-demo-design 的条件式“可证伪技术剖面”。

故事负责获得注意力；实验台负责赢得信任。

不要让理论名词承担证据职责。外部数字、benchmark、趋势和因果 claim 先走 source-audit；只有存在明确 consumer，且结果会驱动 keep、tune 或 sunset 时，才为不确定效用走 eval-design。

这层不是每篇文章的必填清单。纯品牌叙事、人物故事和已经由确定契约回答的问题，不为显得技术化而补 7P、5E 或 Claim Bench。

Phase 0: 锁定叙事姿态

写文章前，先在心里画出这条弧线：

1. 起点：读者现在的痛苦/误区是什么？（代入感）
2. 转折：我们当时是怎么踩坑的？（认知挣扎，不要跳过痛苦直接给答案）
3. 高潮：哪一个具体的证据/瞬间让我们想通了？（解药的质感）
4. 终点：读者拿走这个方法论后，能解决他自己的什么问题？

开篇锁预期：弧线画完后，在文章前 3 段内给出核心观点的一句话摘要。读者有了锚点才不会歪楼——场景钩子拉进来，核心命题马上锁住方向。

Phase 1: 故事工具箱

铁律：先场景，后概念。 故事是藤蔓，概念是果实。没有藤蔓，果实就是悬空的。

• 坏写法：我们发现模型会降智。
• 好写法：引用当时的群聊：”视觉把关猫说这行代码调了个根本不存在的 API”——那一刻我们确认了降智。

以下手法从范本提炼——不是”不要做什么”，是怎么做：

给质感（让读者相信真的发生过）：

• 时间锚点：丢具体时间戳或 commit hash。”2026-02-04 23:47”比”某天晚上”真实 10 倍。
• 对话还原：用当时的对话重建发现瞬间——读者跟着一起顿悟。
• 并排对比：把”之前”和”之后”放一起，让差异自己说话。表格、diff、ASCII 图都行。
• 案例脱敏：用真实案例但模糊客户/内部细节——保留接地气感，去掉敏感信息。

造紧张（让读者想继续读）：

• 先展示”对的”再打碎：一段看着正常的代码，然后揭示它为什么不行。预期翻转，注意力锁定。
• 追问链：用递进的问题带读者走向真相，不要一步给答案。
• 迎接怀疑：”那猫猫不会打架吗？——会。我们认为这是特性。”用读者的质疑当小标题。