---

name: zh-tech-writing
description: 中文技术写作与「去 AI 味」润色。写技术博客、发布公告、架构文档、故障复盘、README、API 文档时使用，也用于把一段明显是大模型生成的中文改写成人话。触发词：技术博客、发布公告、更新日志、架构文档、故障复盘、复盘报告、README、接口文档、去 AI 味、AI 腔、润色、改写、这段话太像 AI 写的。不负责英文写作、营销文案（走 wechat-mp-article / xiaohongshu-note）和小说创作。

中文技术写作与去 AI 味

中文技术写作的敌人有两个：一个是翻译腔，一个是大模型腔。前者来自英文文档直译，后者来自模型对「显得专业」的误解。两者的共同症状是：字很多，信息很少。

一、先定文体

动笔前先确定四件事，缺一件就会写跑偏。

要素	问自己	举例
读者	他知道什么，不知道什么	「已经在用这个 SDK 的人」≠「第一次听说的人」
目的	读完他要能做什么	决定升不升级 / 照着接完 / 知道昨晚为什么挂了
篇幅	他愿意花几分钟	公告 1 分钟，复盘 5 分钟，架构文档 20 分钟
姿态	你在通知、说服，还是道歉	公告是通知，选型是说服，故障复盘是交代

姿态错了最伤。故障复盘写成技术炫耀，或者破坏性变更公告写得轻描淡写，读者的火气比 bug 本身大。

二、去 AI 味清单

大模型写中文有一套很稳定的坏习惯。按这张表逐条扫，命中就改。

词汇层

• 删掉「赋能、抓手、闭环、链路（非技术含义时）、生态位、心智、颗粒度、对齐（非日程含义时）」。这些词在技术文里几乎不承载信息。
• 删掉「值得注意的是、需要指出的是、总的来说、综上所述、在当今这个……的时代」。它们是过门，不是内容。
• 「进行 + 动词」改成动词本身。「进行优化」→「优化」，「进行了一次部署」→「部署了一次」。
• 「性、化、度」后缀连用要拆。「提升系统的可维护性与可扩展性程度」→「让系统更好改、更好加功能」。
• 形容词堆叠砍到一个。「强大而灵活的高性能框架」→ 说清楚它到底快在哪。

句法层

• 一句一个意思，20 到 35 个字。超过 45 字就找逗号断开。
• 长定语前置是翻译腔重灾区。「一个由三个独立部署的、通过消息队列通信的服务组成的系统」→「系统由三个服务组成，各自独立部署，之间走消息队列」。
• 被动句改主动。「该问题被修复」→「我们修了这个问题」或「这个问题已修复」。
• 「的」在一句里不要超过两个。

结构层

• 三段以上的排比就是模型在凑字数，砍到两段。
• 每个小节开头第一句就是结论，不要铺垫。
• 「首先/其次/最后」这种连接词，能靠分点符号表达就删掉。
• 全文不要出现「本文将介绍……」，直接介绍。

信息层（最重要）

• 每个形容词后面要跟一个数字或一个可验证的事实。说「显著提升」必须给出从多少到多少。
• 说「最佳实践」要说明在什么约束下最佳。
• 不确定的事情要标出来，不要用笃定的语气糊过去。

三、几种常见文体的骨架

发布公告 / 更新日志

一句话说清这个版本干了什么
## 破坏性变更     ← 有就必须放第一位，没有就整节删掉
## 新增
## 修复
## 升级方式

破坏性变更要写三件事：改了什么、为什么必须改、老代码怎么迁。少一件读者就会来问。

故障复盘

## 影响       什么时间段、哪些用户、损失多少。先说这个。
## 时间线     用表格，精确到分钟，只写动作不写心情
## 直接原因   代码/配置层面那一行
## 根本原因   为什么这行能被写出来并上线
## 改进项     每条带负责人和截止日期，没有这两样的不算改进项

复盘不写人名，只写系统和流程的问题。写了人名，下一次就没人报故障了。

架构文档

## 要解决什么问题   包括「不解决什么」
## 方案            一张图 + 数据怎么流
## 为什么不选别的   至少两个被否决的方案和否决理由
## 代价            这个方案换来了什么，也失去了什么
## 待定

「为什么不选别的」是架构文档里唯一无法被代码替代的部分，别省。

README

前五行必须回答：这是什么、给谁用、怎么跑起来。安装说明放在功能介绍前面。徽章不超过三个。

四、润色工作流

拿到一段待改的中文，按顺序做：

1. 读一遍，找结论。 结论如果在第三段，把它提到第一句。
2. 删空转句。 逐句问「删掉这句读者会少知道什么」，答案是「不会」就删。通常能删掉三到四成。
3. 拆长句。 超过 45 字的断开。
4. 换词。 扫上面的词汇黑名单。
5. 补事实。 每个形容词找一个数字。找不到就把形容词删掉。
6. 朗读。 念着别扭的地方就是读者会卡的地方。

改完对比一下字数。技术文正常能压掉 30% 到 50%，压不动说明第 2 步没做狠。

五、验收

交付前自查：

• 第一句话能不能单独当摘要
• 有没有任何一个数字是我编的
• 破坏性变更有没有漏
• 代码块能不能直接复制运行
• 全文有没有出现「赋能」「闭环」「值得注意的是」

五条全过再发。