| name | technical-writing |
| description | Use when drafting or revising internal technical design docs, review notes, architecture writeups, or sharing posts in Chinese, especially when the tone should stay evidence-backed, calm, and suitable for peers or leaders rather than marketing or literary writing. |
Internal Technical Writing
Overview
Use this skill when the writing target is an internal技术方案、评审稿、架构说明、分享文稿，重点在于把背景、猜想、证据、抽象、实现影响面讲清楚。
这类写作更接近技术汇报，不是宣传稿，也不该写成散文。语气要平稳，判断要有来路，段落要能顺着问题往下读。
When to Use
- 在写内部技术方案、设计说明、评审文档、分享稿
- 在改一篇已经有内容、但文风过满、结论过快、证据不足的技术文章
- 在解释代码、模块边界、架构演进、可观测性、评测方法
- 在把聊天记录、讨论结论整理成可传播的技术文档
When not to use
- UI 文案、按钮文案、产品营销稿
- 面向外部用户的帮助文档
- 纯粹的 API reference 或机械说明书
Core Stance
先接住读者，再往下解释。
常见写法是作者替读者抢先下判断，像 很清楚、说明了、显然、真正。这里更适合换成三步：
- 我们观察到了什么
- 基于这些观察，可以归纳出什么
- 这些归纳暂时更适合落在哪类实现或组织方式里
如果要给出更强的判断，至少满足下面任一条件：
- 前文已经提出了对应的猜想，这一段是在 callback
- 同一段上下文里已经有交叉验证的 evidence
- 已经引用了具体模块、代码、issue、trace、指标或实验结果
这些 bad case 往往有同一种共性：
- 句子承担的是“主持文章”的功能，不是“推进论证”的功能
- 句子在表达作者感受，不是在交代条件、对象、约束或判断
- 句子把英文抽象写作习惯直接投到了中文里
- 句子删掉以后，不影响事实，不影响论证，也不影响结构
遇到这类句子，默认处理方式不是“换个更文雅的说法”，而是：
- 先判断这句是否真的提供信息
- 如果不提供信息，直接删除
- 如果提供信息，就把信息改写成条件、对象、关系、结果
Preferred Structure
写长文时，优先用这条主线：
背景 -> 拆解现状 -> 提出猜想 -> 分节解答 -> 回指前文 -> 影响面 -> 可观测性 / eval -> 收束
如果文章围绕一个系统展开，可以把每一节都写成“在回答前面哪个问题”。这样读者会知道当前段落在解决什么，而不是只看到一串观点。
更具体一点，常见结构会是：
- 先交代背景和目标
- 拆现状，尤其是已有系统的优势、局限、宏观规律
- 把猜想或设计问题提出来
- 逐节解释每一层能力怎样补上
- 回到代码、模块、数据流、观测面和评测面
如果某一节表面上在讲模块，实际目的是在替另一个概念安家，可以优先用这种结构：
- 先用一个很短的 quote 收住上下文
- quote 里优先放
mindmap 或极简结构图
- 再给一个生命周期或时序图
- 最后才进入正文，解释这个概念为什么放在这里、怎样和现有模块对上
如果要给 leader 或评审一个放在最开头的 TL;DR，优先用三段结构：
- 先讲启发来源或背景变化
- 再讲当前系统已经具备哪些输入、还缺哪一层结构
- 最后讲新模块设计和架构决策
这个 TL;DR 只保留三类信息：
不要在 TL;DR 里复述整篇目录，也不要解释作者接下来会怎么写。
Language Rules
中文语气以自然、平实、技术同伴之间的说明为主。
- 中文引用统一用
「」
- 少用修辞和比喻，尤其是面对前线开发和内部评审
- 少用居高临下的口吻，避免说教感
- 少写成议论文式对抗句，优先顺着读者的理解路径展开
- 专有概念按正式名字书写，大小写保持稳定，例如项目里的
Collector、Scheduler、Alert 这类专名，全文统一一种写法
- 指标、能力、链路这些名词先钉住，再配动词和形容词；优先复用已经确定的词系，例如
流通性、筛选、聚合、命中，不要临时拼接近义词
- 不要写口语化的过场句，例如
聊到这里、继续往下看、这条方向很值得继续推开、先把这件事单独拿出来说、最后可以用一句话收住；如果一句话只是在主持文章，不承载信息，就直接删掉
- 少用空评价词，例如
很现实、很重、很轻、很顺；改成具体约束、具体风险、具体影响
下面这类句型要主动收一层：
不是……而是……不在……而在……为什么？原因其实很直接这条路径已经很清楚了说明了一件事自然会真正
更稳妥的写法通常是：
也许你会先想到……把视线收回到今天的代码里，会先看到几组比较稳定的规律顺着这些模块往回看，可以归纳出……前面提到的猜想，在这里开始有了一个更具体的回答先把判断放轻一些，后面再结合代码或指标继续说明
遇到段落里的关键问题句，可以适度用 **...** 强调，但只留给真正的主问题，不要把普通判断句全部加粗。
Buzzword Blocklist
下面这些词在中文技术文档里几乎都是「让句子看起来有信息，但读完不知道发生了什么」。看到先停一下，能换成具体动作 / 对象 / 约束就换掉。
原则：不是逐词替换，而是逐句重写。原句里如果只有黑话词承载信息，整句通常没信息。删掉看论证少不少东西，少了再补具体的，没少就让它消失。
抽象抢戏词
生态 / 生态位 / 产品生态 → 列出具体依赖关系、用户类型或集成方赋能 / 赋能用户 → 让用户能 X / 把 X 能力开放给 Y闭环 / 形成闭环 → X 之后 Y 也接进去了 / 现在能从 A 走到 B 再回到 A抓手 / 核心抓手 → 我们能改的那一个变量是 X心智 / 用户心智 / 心智模型 → 用户在第一次看到 X 时会怎么想 / 怎么操作链路打通 / 打通 → A 现在能调用 B / A 写入的数据 B 也能读到沉淀 / 沉淀经验 / 沉淀方法论 → 记录到 docs/X / 整理成 skill / runbook落地 / 落地能力 / 落地场景 → 在 A 模块实现 / 在 B 业务用上心力 / 认知负担 → 需要记住 X 个步骤 / 上手要先理解 Y收口 / 统一收口 → 所有 X 都走 Y 一个入口加持 / AI 加持 → 加了 X 之后能 Y / 在 X 步用了 LLM底座 / 底层逻辑 → 基础设施层是 X / 这件事成立的前提是 Y
评价腔 / 主持腔
很值得 / 非常值得 → 给具体理由：值得在哪个维度上极致 / 极致体验 → 改成具体指标：延迟降到多少、步骤减到几步丝滑 / 顺畅 → 改成具体约束：哪步原本卡，现在跳过了深度集成 / 深度对接 → 改成集成点的具体范围一站式 → 在 A 入口能完成 B / C / D颠覆 / 重塑 → 默认不用；真要用得有 before / after 对比
Evidence-First Writing
写代码和架构时，避免直接把实现细节翻译成抽象结论。
推荐顺序：
代码 / issue / trace / metric -> 宏观规律 -> 抽象归纳 -> 设计判断
例如，不要直接写：
当前代码里，这条路径已经很清楚了。
更适合写成：
把视线收回到今天的代码里，会看到几组比较稳定的宏观规律。顺着这些模块往回看，可以先归纳出一个较稳定的结构。前面提到的几层能力，也因此开始有了几种更适合继续承接的实现位置。
Reader-Aware Explanations
很多技术分歧来自“作者默认读者已经接受了自己的前提”。这里更适合先猜测读者可能会怎么想，再把误会拆开。
常用句法：
也许你会先想到定时巡检，像是……顺着这个方向想下去，会发现我们更关心的是……这样理解，会更贴近这次设计的边界
适合接一个 quote：
一条巡检任务如何按预定周期扫描每个指标
然后再转入你真正要讨论的问题：
持续涌入的原始日志，怎样在不拖慢写入链路的情况下，被判定成一条值得通知的告警
Few-Shot Fixes
下面这些例子比抽象规则更重要。写作时如果遇到类似句式，优先按这个方式改。
1. 不要把英文里的 real / realize / reality 直接翻进中文
原句：
一旦把告警规则接到多个采集端上，粒度问题会马上变得很现实。
问题：
现实 在这里不是合适的表语- 主语是
粒度问题，谓语是 变得，搭配不成立
- 句子像是在表达感受，不是在说明约束
改写：
可以预见的是，告警规则接入多个采集端之后，规则粒度的控制会很重要。
为什么这样改：
- 先写条件：
接入多个采集端之后
- 再写对象：
规则粒度的控制
- 最后写判断：
会很重要
2. 不要用空评价词替代约束
原句：
这样的组合很顺。
问题：
很顺 只有情绪，没有信息- 读者不知道顺在成本、链路、延迟还是模块边界
改写：
这种组合更接近实际分工。
或者：
这种组合能把日志写入链路和告警判定链路拆开。
为什么这样改：
- 直接说分工关系
- 或者直接说结构变化
- 不用作者主观感受替代技术判断
3. 不要用对立句法硬造强调
原句：
它值得认真看的地方，不在宣传语，而在它把一组采集与告警机制组织得很完整。
问题：
不在……而在…… 容易写出说教感- 读者还没进入正文，就先被作者带去站队
改写：
更值得认真拆开的，是它把一组采集与告警机制组织得比较完整。
为什么这样改：
- 少掉对立结构
- 句子仍然保留重音
- 读者更容易直接进入后文
4. 不要用过场句替代内容
原句：
聊到这里，告警去重相关的模型也该放进来一起看了。
问题：
- 这是主持人口吻，不是技术文档
- 删掉这句，论证不会损失任何信息
改写：
告警去重相关的模型也需要放进来一起讨论。
为什么这样改：
同类句子也直接删掉，不做“温和改写”：
原句：
先把「压缩」这件事单独拿出来说。
问题：
- 这是主持句，不提供任何新信息
- 删掉之后，后文论证不受影响
处理：
直接删除，让下一句作为段落开头
5. 不要把“主持文章”的句子写进正文
原句：
这张图想说明的事情很简单。
问题：
- 这是主持句，不提供图外的新信息
- 读者真正需要的是图后的结论，不是作者先出面做导语
处理：
直接删除，下一句直接解释图里的结构关系
原句：
接下来进入这一节真正关心的问题：
问题：
- 这句话只是在带节奏，没有补充任何事实
- 如果下一句本身已经是问题句，这一句就没有存在价值
处理：
直接删除，或者把下一句改成完整的问题句
原句：
最后可以用一句更轻一点的话结束：
问题：
- 这句话只是在管理作者自己的写作动作
- 正文里不需要暴露作者“现在准备收尾”
处理：
直接删除，让引文或结论直接出现
6. 论证有顺序，就直接写成 1. 2. 3. 4.
原句：
第一，采集端很多，但日志最终还是会被收束到告警引擎。
第二，采集层已经承担了日志归一化……
第三，告警引擎自己已经天然拥有一组规则边界……
第四，外围模块已经把不少有价值的事件散落出来了……
问题：
- 如果只是散写四段，读者不容易看出这是一组并列论据
- 论据顺序和论证强度不够醒目
改写：
- 采集端很多，但日志最终还是会被收束到告警引擎。
- 采集层已经承担了日志归一化、字段提取、标签注入、来源标注。
- 告警引擎自己已经拥有一组稳定的规则边界。
- 外围模块已经给出了足够多的事件与状态。
为什么这样改：
- 论证顺序被显式标出来
- 每一点都能单独成立
- 后文更容易 callback
7. 指标名和动作词要属于同一套语义系统
原句：
第一组命题靠近转化率。不同 source 类型进入系统之后，有多少被 dedupe 掉，有多少在 cooldown 里停住，有多少被 policy 接住，最后又有多少真的升级成一条告警。
问题：
转化率、dedupe 掉、停住、接住、升级 混了多套词- 指标名和动作词不在一个语义系统里
改写：
- 计算流通性。
不同 source 类型进入系统之后：
- 有多少被 dedupe 筛选
- 有多少进入 cooldown 聚合
- 有多少被 policy 命中
- 最后又有多少升级成一条告警
为什么这样改：
- 先钉住指标名：
流通性
- 再统一动作词：
筛选 / 聚合 / 命中 / 升级
- 这一组词能互相支撑，不会彼此打架
8. 表面在讲模块，实际是在给概念安家时，先给短图
原句：
从采集入口到告警判定层……
后面直接开始解释告警引擎、采集层、规则模块……
问题：
- 读者还不知道这节到底想回答什么
- 容易把“解释模块”写成“复习已有系统”
改写结构：
- 先点明问题：
这一节表面上在讲告警引擎，真正要回答的是去重模块应该放在哪里。
- 用一个很短的
mindmap 收住周边模块
- 再给一个生命周期图
- 最后才写
1. 2. 3. 4. 论据，把概念安到现有系统上
为什么这样改：
- 图负责建立工作机理
- 正文负责回答设计问题
- 模块介绍不会挤掉概念论证
9. TL;DR 先讲启发来源，再讲问题定义，最后讲模块设计
原句结构：
当前系统已经具备了大量可利用的信息来源……
我们的猜想是……
基于这个判断，我们的决策是……
问题：
- 起手就落在“系统现状”，重心太平
- 启发来源没有先出现，读者不容易立刻进入问题
基于这个判断，我们的决策是 也带一点主持口吻
更合适的结构：
第一段：先讲外部启发或上游项目带来的变化
第二段：再讲日志、指标、trace、事件等输入已经存在，系统接下来要整理的是反复出现、需要聚合的重复告警
第三段：直接提出新模块设计，以及消息队列、异步消费框架这类架构决策
例子：
上游某个监控项目让大家看到了另一种告警形态……
当前系统也已经具备了足够多的输入和状态来源……
这里提出一个新的模块设计……
为什么这样改：
- 第一段先建立背景和动机
- 第二段再定义问题
- 第三段直接落到决策
- 读者扫三段就能抓住全文主轴
10. 不要把作者感受写成技术判断
原句：
这样的组合很顺。
原句：
这条路径很清楚。
原句：
这会马上变得很现实。
问题：
顺、清楚、现实 都是作者感受，不是技术判断- 读者不知道到底顺在什么、清楚在哪里、约束是什么
改写方向：
先写条件
再写对象
最后写判断
例如：
可以预见的是，告警规则接入多个采集端之后，规则粒度的控制会很重要。
11. 不要把结构写成隐喻动作
原句：
散落出来了
原句：
收拢出来
原句：
往一层里收
原句：
延展下去
原句：
停在 action skipped
原句：
落在 failed
问题：
- 这些词在脑子里成立，是因为作者把系统想成了“流动中的东西”
- 一旦写成中文，主谓和宾语关系经常不成立
- 它们会把“状态”“结构”“结果”误写成“位置”或者“动作”
改写方向：
提供了整理出来集中到同一层处理继续追加后续处理最终生成了 action skipped最终生成了 failed
Lists, Quotes, and Flow
不要为了“像文章”而硬把所有东西写成整段 prose。内容本来就是 list-shaped 时，直接列出来更清楚。
适合列出来的内容：
- 设计目标
- 猜想
- 模块影响面
- 待补充实现点
- 评测命题
- 适用 / 不适用场景
如果一组判断本身带有论证顺序，优先直接写成 1. 2. 3. 4.，不要把它们散落成几段并列 prose。
适合用 quote 的内容：
- 想强调的命题
- 读者可能先想到的另一种问题定义
- 控制论 / 系统论 / issue 摘录中的关键句
适合用箭头的内容：
event -> dedupe -> alertbackground -> hypothesis -> answercollect -> match -> notify
Module-Level Writing
只谈抽象很容易飘。只谈代码又会失去设计视角。内部技术文档通常需要两层一起出现：
- 抽象层：概念、边界、语义、主张
- 实现层：模块、类型、采集器、规则、存储、trace、eval
写实现层时，尽量把模块面摊开：
- 哪些模块已经存在
- 哪些模块只体现出局部规律
- 哪些模块更适合作为后续替代实现
- 哪些地方需要补偿、迁移、压缩、解耦
如果一段在说“改造”或“补充实现”，优先给出可扫描的块，例如：
可能涉及到的补充实现：
- 告警存储层 CRUD 拓展
- 告警编排从 inline 转向异步消费
- tracing 压缩与聚合策略
- 可观测面板的链路展示与命题聚合
Tone Calibration
面向内部评审、leader、前线开发时，语气以「一起拆问题」为主。
- 少下定论，多给出推演路径
- 少用绝对化副词，多用
先、可以、暂时、顺着这个观察
- 少写审判式句子，多写解释式句子
- 少写“作者赢了”的结尾，多写“读者可以继续往下跟”的结尾
Editing Checklist
交稿前，逐项扫一遍：
- 有没有没有证据支撑的强判断
- 有没有
不是……而是…… 一类对立句法
- 有没有
很清楚 / 说明了 / 显然 / 真正 这种抢结论的词
- 有没有把代码直接翻译成抽象结论
- 有没有只讲概念，不讲模块和影响面
- 有没有该列清单的地方却硬写成长段
- 有没有前文提出的猜想，后文却没有 callback
- 指标名、动作词、状态词有没有混用，名词和动词是不是同一套语义系统
- 有没有过场句在替内容占位置；如果删掉一句话不影响论证，就直接删掉，不改写成另一句过场话
- 中文引号有没有统一成
「」
Default Prompting Pattern
收到草稿时，先做三件事：
- 标出文中最强的几个判断
- 检查这些判断有没有 callback 或 evidence
- 按
背景 -> 猜想 -> 解答 -> 回指 重排结构，再改句子
如果需要给出改写建议，优先直接改成可用的句子，不要只做抽象点评。
