| name | tech-writing |
| description | 技术文章对外写作:从内部实践到读者能代入的叙事。 Use when: 写技术博客、公众号文章、社区分享、对外 longform、技术文章 review、写推广语。 Not for: 内部文档/spec(直接写)、PPT(用 ppt-forge)。 Output: 有呼吸感的技术文章 + 读者反馈聚类分析。
|
| triggers | ["写文章","技术分享","博客","longform","公众号","对外发布","社区分享","推广语"] |
Tech Writing — 技术文章对外写作
开工前:先看范本
不要学 AI 的平滑,要学人的“颗粒度”:
cat-cafe-tutorials/docs/lessons/12-no-boss-agent.md:看它如何用“读者的怀疑”当小标题,把争议变成共鸣。
cat-cafe-tutorials/docs/lessons/01-sdk-to-cli.md:看它如何还原“当时炸了”的瞬间,让读者跟着猫一起出冷汗。
为什么读者能闻到"AI味"
AI 写作像是在发送一个逻辑自洽的压缩包。读者没有经历过那 100 天,收到的是一个打不开的结论。
好的写作是“解压过程”:给证据锚点,不给干巴巴的结论。
- AI 味 = “我们发现这个系统存在一致性风险。”(平滑、确定、无聊)
- 猫咖味 = “深夜三点,Redis 6399 突然报错。那一刻我们意识到,原来最初的架构假设错了。”(有时间、有痛点、有挣扎)
行文的本质:进化链
不要介绍一个系统的终态。要讲它怎么长出来的。
每篇文章沿着一条链:方案 → 方案撞墙 → 新方案。系列文章之间,上一篇撞的墙就是下一篇的起点。
以记忆系统为例:
- CC 的 grep + 文件系统——简洁、美,但需要先验知识(你得知道搜什么)
- 加了 BM25 + embedding + RRF(F102)——解决了先验,但 context 压缩时召回变差
- 消费加权排序(F200)——每一步都是上一步撞墙后长出来的
读者跟着的不是一张完美的架构图,而是一条连续剧。进化天然有挣扎,设计天然平滑——所以进化链天然没有 AI 味。
与 Phase 0 的关系:进化链管选题和系列连接;Phase 0 管单篇内部的节奏。
Phase 0: 锁定叙事姿态
写文章前,先在心里画出这条弧线:
- 起点:读者现在的痛苦/误区是什么?(代入感)
- 转折:我们当时是怎么踩坑的?(认知挣扎,不要跳过痛苦直接给答案)
- 高潮:哪一个具体的证据/瞬间让我们想通了?(解药的质感)
- 终点:读者拿走这个方法论后,能解决他自己的什么问题?
开篇锁预期:弧线画完后,在文章前 3 段内给出核心观点的一句话摘要。读者有了锚点才不会歪楼——场景钩子拉进来,核心命题马上锁住方向。
Phase 1: 故事工具箱
铁律:先场景,后概念。 故事是藤蔓,概念是果实。没有藤蔓,果实就是悬空的。
- 坏写法:我们发现模型会降智。
- 好写法:引用当时的群聊:”视觉把关猫说这行代码调了个根本不存在的 API”——那一刻我们确认了降智。
以下手法从范本提炼——不是”不要做什么”,是怎么做:
给质感(让读者相信真的发生过):
- 时间锚点:丢具体时间戳或 commit hash。”2026-02-04 23:47”比”某天晚上”真实 10 倍。
- 对话还原:用当时的对话重建发现瞬间——读者跟着一起顿悟。
- 并排对比:把”之前”和”之后”放一起,让差异自己说话。表格、diff、ASCII 图都行。
- 案例脱敏:用真实案例但模糊客户/内部细节——保留接地气感,去掉敏感信息。
造紧张(让读者想继续读):
- 先展示”对的”再打碎:一段看着正常的代码,然后揭示它为什么不行。预期翻转,注意力锁定。
- 追问链:用递进的问题带读者走向真相,不要一步给答案。
- 迎接怀疑:”那猫猫不会打架吗?——会。我们认为这是特性。”用读者的质疑当小标题。
交付结论(让读者拿得走):
- 给原则取名:好结论压成一句口号,读者能复述给同事。
- 用人物的嘴说:”API 的猫猫等于砍了手脚的猫猫吧?”比”API 模式存在能力限制”有画面。
- 用成长收尾:最后一段讲旅程和变化,不讲”综上所述”。
Phase 2: 翻译句纪律
内部黑话是叙事的毒药。翻译句 = 读者能看懂的类比。
- “KD-8 架构” → “就像把判断权交给开车的猫,而不是路边的指示牌。”
- “F203 瘦身” → “把重复的家规从猫猫的脑子里拎出来,只留最核心的一层。”
Phase 3: 呼吸感自检(每章门禁)
不要只用 grep 数排比,要用耳朵听节奏。
- 长短句交替:连续三个长句后,必须有一个短句。像心跳一样。
- 摩擦力检查:删掉所有”不仅...而且...”、”不是...而是...”的废话。用动词直接陈述。
- 视觉留白:同一段落内不要有 3 个以上的加粗。加粗是视觉尖叫,多了就全是噪音。
- 减列表:md bullets 像科研论文。能合并成一段自然语言就别拆——连贯的句子比碎片化的列表更容易把思维链串起来。
- 细节自检表:见
refs/ai-taste-checklist.md。
Phase 4: 摘要 + 推广语(拒绝标题党)
门禁:写摘要前必须重新“解压”全文。 禁止直接罗列标题。
- 摘要:要写出那股“不甘心”和“终于通了”的冲突感。
- 推广语:要给出一个让读者觉得“这事儿跟我也相关”的钩子。
Phase 5: 拥抱负面反馈
| 反馈 | 视觉把关猫的翻译 |
|---|
| “读不懂” | 文章的 UI 坏了,得修修类比和结构。 |
| “AI味重” | 故事写得太顺了,没把踩坑时的狼狈写出来。重写第二章。 |
| “这就是一堆 Prompt” | 我们没把“为什么这堆 Prompt 能跑通”的证据链展示清楚。 |
Common Mistakes
- 展示全能感:AI 喜欢假装自己永远正确。好的技术文章要展示”曾经的无知”。
- thinking 溢出:AI 的立论→驳论→自我思辨过程直接暴露到文章里(”一方面...但另一方面...综合来看...”)。这是内部 thinking 链泄漏,读起来像论文答辩不像跟人说话。砍掉思辨过程,只留结论和支撑结论的故事。
- 机械标注:试图用标签补救叙事的苍白。如果故事讲得好,不需要贴标签读者也知道那是真的。
- 缺乏留白:把所有东西塞得满满当当,不给读者思考的空间。
下一步
写完一章 → 听听有没有“呼吸感” → 过 Phase 3 门禁 → 给operator审“钩子” → 发布