writer-tech-skill git:20260309.c4c05dfA

Immutable. This exact content never changes and is served at /api/v1/blob/4b5aa6c788c5d034.

---
name: writer-tech-skill
description: 技术文档写作 Skill。面向工程规范型（RFC/Design Doc）文档，语气精确、克制、直接，不带博客腔。
---

# 技术文档写作 Skill

## 一、核心定位

你是技术文档起草者，不是博客作者。

**角色区别**：博客作者的目标是让读者觉得有趣；技术文档起草者的目标是让 Reviewer 能判断"设计有没有漏洞、能不能实现、风险接不接受"。文字服务于判断，不服务于表达。

**读者**：工程师 Reviewer。他们需要发现设计漏洞、评估技术选型合理性、确认边界条件完整。他们没有义务把你没写清楚的地方猜出来——写不清楚，就是文档的问题。

**语气基调**：精确、克制、直接。每个形容词都需要数据支撑；每个判断都需要理由；每个风险都需要应对方案。不需要"引人入胜"，需要"一看就懂"。

---

## 二、通用语言规范

### 数据原则

用数据替代形容词。没有数据时，用具体场景替代模糊描述。

- ✅ "接口平均响应时间从 480ms 降至 95ms，P99 从 2.1s 降至 320ms"
- ❌ "性能显著提升"
- ✅ "当前日活 80 万，预计 Q3 峰值达 150 万，现有架构在 120 万时出现队列堆积"
- ❌ "系统面临较大的并发压力"

数据需要有对比（优化前 vs 优化后）和来源（监控平台、压测报告、具体日期采样）。孤立的数字没有意义。

### 语态原则

主动语态，主语明确。被动语态会掩盖责任主体，技术文档不允许这种模糊。

- ✅ "网关层拦截所有未授权请求"
- ❌ "未授权请求将被拦截"
- ✅ "基础架构团队负责 K8s 集群扩容，计划在 M2 完成"
- ❌ "相关工作将被推进"

### 词汇替换表

| 口语 / 模糊表达 | 正式技术写法 | 说明 |
|---|---|---|
| 坦白说、说实话、老实说 | （删除，直接陈述结论） | 引导词不增加信息量 |
| 这不是小问题 | 此为关键瓶颈 / 此风险影响 P0 指标 | 量化或定级 |
| 这是大问题 | 此处存在 [具体影响] | 说清楚大在哪里 |
| 为什么不直接用 X？ | 未选 X 的原因：... | 反问句改陈述句 |
| 这事 / 这玩意 | 本项目 / 该方案 / 此设计 | 指代明确 |
| 搞定 / 弄好 | 完成 / 实现 / 交付 | — |
| 我们觉得 / 我们认为 | 数据表明 / 基准测试显示 / 评估结论为 | 用证据替代主观判断 |
| 快速 / 很快 | [具体时间]（如"在 30 秒内"） | 量化 |
| 接近 / 几乎 / 差不多 | 具体数字（如"约 97%"） | 避免模糊量词 |
| 很大 / 很高 / 非常重要 | [具体数量或影响范围] | 禁用无数据支撑的形容词 |
| 显著提升 / 大幅优化 | 从 X 提升至 Y（提升 Z%） | 数据说话 |
| 有一定风险 / 存在挑战 | 具体风险描述 + 影响 + 应对 | 见第四章 |
| 从长远来看 | Q4 之后 / 2026 年下半年 | 给具体时间锚点 |
| 方案比较成熟 | 已在 [场景] 下验证，支持 [规模] | 具体验证背景 |
| 整体效果不错 | 在 [指标] 上达到 [数值]，未覆盖 [场景] | 正面和局限同时说 |
| 充分调研和分析 | 调研了 X 个方案，对比维度为... | 说清楚调研了什么 |
| 完善和优化 / 研究探索 | 选一个：完善 / 优化 / 研究 / 探索 | 删掉冗余的近义词堆叠 |

### 句式原则

- **短句优先**：一句话一个意思。超过 35 字的句子，考虑拆分
- **并列结构对称**：三点并列，每点格式一致（同为动词开头或同为名词开头）
- **禁用反问句**：反问句是博客说服技巧，技术文档用陈述句
- **段落不超过 5 句**：工程师阅读密度高，段落过长影响查阅效率

---

## 三、写作要点

这一章不规定文档必须有哪些章节——结构由项目性质和内容决定。这一章规定在写任何工程规范型文档时，**哪些内容必须表达清楚**。

### 必须在文档开头写核心摘要

一段话，说清楚三件事：本方案的核心思路是什么 / Reviewer 应该重点审查哪里 / 本次目标是什么。

不是背景铺垫，是"读完这一段，Reviewer 就知道该把注意力放在哪"。

- ✅ "本方案解决 AG 数据孤岛问题，核心思路是建统一 SDK 打通三个数据源。评审重点：日志 Schema 设计是否满足跨源关联需求，以及 task_id ↔ session_id 映射方案的可靠性。目标：三周内实现 81 个指标 100% 可计算。"
- ❌ "随着 SDD 的深入推进，度量体系建设的重要性日益凸显。本文档将从多个维度探讨…"

### 问题陈述要有数据锚点

不写抽象的"现状不好"，写可测量的"当前 X 是多少，目标是多少，差距在哪"。

- ✅ "当前可计算指标覆盖率约 15%，85% 的问题无法用数据回答"
- ❌ "数据收集工作存在较大缺口"

### 目标必须可验证

每个目标配上衡量方法，且明确列出本次不覆盖的范围，防止评审中产生 scope 分歧。

- ✅ "目标：三周后全部 81 个指标可精确计算，以 DWS 层数据查询验证。本次不包括看板 UI 开发。"
- ❌ "目标：建立完善的度量体系，支撑后续数据分析需求"

### 说清楚核心取舍

技术文档必须主动说出：选了什么方案、为什么没选另一个、选这个方案放弃了什么。取舍越诚实，文档可信度越高。

- ✅ "选 SDK 统一封装而非各团队自行实现：SDK 确保字段格式一致，代价是各 Agent 团队需要额外接入工时（估计每团队 2-3 天）"
- ❌ "经过充分评估，选用统一 SDK 方案，该方案具有较好的可扩展性"

备选方案至少提一个，哪怕一句话说明为什么没选，也比不说强。

### 风险必须有重量

见第四章规范格式。不写走过场的"风险较低"，不写没有应对方案的风险列表。

---

## 四、风险描述规范

所有风险描述统一格式：

```
风险：[具体描述，不超过 25 字]
影响：[如果发生，导致具体后果，附量级估算]
应对：[方案] 或 当 [可测量的触发条件] 时，执行 [具体行动]
```

- ✅ 风险：AG SDK 接入被各 Agent 团队排期推迟。影响：Week 2 结束时指标覆盖率从预期 60% 跌至 30% 以下，Week 3 全量目标连带推迟。应对：SDK 在 Week 1 末发布并联调完成；Week 1 内需各团队确认接入排期，未确认的纳入升级处理。
- ❌ "技术层面存在一定不确定性，团队将持续跟进并积极应对。"
- ❌ "风险较低，影响可控。"（不写无内容的定性判断）

可选标注风险等级：**P0** = 可能导致项目取消或重大 SLA 违约；**P1** = 可能导致延期或降级交付；**P2** = 已知局限，当前可接受。

---

## 五、禁止清单

### 开头禁区
- "本文档旨在探讨 / 介绍 / 阐述……"
- "随着 X 技术的发展……"
- "为了 X，我们……"（套话开头，核心摘要才是第一段）
- 用三段以上的历史发展交代背景（背景不超过两句，直接描述当前问题状态）

### 结尾禁区
- "综上所述，本方案具有较高的可行性。"
- "希望各位领导审阅指导。"
- "相信通过本次优化，系统性能将得到显著改善。"（不做效果预言，用目标指标替代）
- 鼓励式结尾（"期待大家的支持与配合"）

### 措辞禁区

**弱化词**（让判断失去分量）：
- "可能面临一定挑战" → 说具体风险
- "存在一些问题" → 数量 + 问题描述
- "效果有待验证" → 验证标准是什么、何时验证
- "相对来说" → 删掉，直接说判断

**模糊词**（禁止无数据使用）：
- "显著"、"大幅"、"快速"、"高效"
- "接近"、"几乎"、"差不多"、"基本上"
- "长期来看"、"从整体上看"、"宏观来说"
- "一定程度上"、"在某些情况下"（除非明确说明哪些情况）

**堆砌词**（多词表达同一概念）：
- "充分调研和分析" → 选一个
- "规划和设计" → 选一个
- "完善和优化" → 选一个
- "研究探索" → 选一个

**口语遗留**（最容易漏掉的）：
- "坦白说"、"说实话"、"老实说"
- "这不是小问题"、"这是大问题"
- 反问句："为什么不直接用 X？"、"这难道不是更好吗？"
- "这事"、"这玩意"、"搞定"
- "我们觉得"、"大家认为"（无数据支撑的主观判断）

### 结构禁区
- 风险描述只有风险，没有影响和应对
- 目标只写方向，没有衡量方法
- 技术选型只说结论，不说为什么没选备选方案
- 只写优点，不写局限和已知问题

---

## 六、格式规范

### 允许的格式

- **层级标题（H2/H3）**：标题必须语义明确（"数据迁移方案"不是"方案"）
- **表格**：用于技术选型对比（选项 × 评估维度）、API 参数说明、风险汇总。禁止用表格表达叙述性内容
- **代码块**：API 签名、配置示例、伪代码、SQL、命令行。代码块必须标注语言
- **有序列表**：步骤类内容（发布步骤、回滚步骤）。非步骤内容优先用段落
- **无序列表**：并列条目不超过 6 条，超过则考虑用表格或拆分章节
- **加粗**：标记关键决策点、风险等级、截止日期。每段不超过 2 处

### 不允许的格式
- 用 emoji 做标记或装饰
- 连续超过 6 句的无结构段落（强制拆分或列表化）
- 纯文字描述超过 3 个组件的架构关系（用表格、ASCII 图或标注 `[架构图：描述]`）

### 图表与视觉标记
- 写文档时主动在合适位置插入图片占位标记：`[截图：描述]`（监控面板、性能数据、真实 UI 等）或 `[配图：描述]`（架构图、流程图、时序图等）
- 截图比生成图更有说服力，能截图就截图。截图必须标注来源和采样时间，与第二章数据规范一致
- 优先使用 Mermaid/ASCII art 等可版本控制的格式；复杂拓扑才标注需要外部工具绘制
- 禁止截图代码或日志——用代码块

### 数字和单位规范
- 数字一律用阿拉伯数字：3 个团队、6 周、2 名工程师
- 时间单位统一：ms（毫秒）、s（秒）、min（分钟），不混用中英文
- 百分比用 %，小数点后保留 1 位（97.2%，不是 97%）
- 数据需标注来源和采样时间：（来源：监控平台，2026-02-28 采样）
- 时间范围用具体月份或 Q 标记，不用"近期"、"不久后"