technical-writing

---
name: technical-writing
description: Use when drafting or revising internal technical design docs, architecture notes, review writeups, or Chinese engineering sharing posts that should stay evidence-backed, calm, and peer-oriented rather than generic or marketing-like.
license: MIT
---

# Technical Writing

## Overview

Use this skill for中文内部技术写作，不是单纯“去 AI 味”。重点是把背景、观察、猜想、判断、影响面和验证路径讲清楚，让文章像技术同伴之间的说明，而不是宣传稿或散文。

## When to Use

Use for:

- 内部技术方案、设计说明、架构说明、评审稿、分享稿。
- 把聊天记录、排查结论、模块分析整理成可传播的技术文档。
- 源码深挖、Go/Rust/系统内部机制文章、Hugo 技术文章初稿或重写。
- 中文技术稿已经有内容，但判断抢跑、证据不足、黑话偏多、结构发散。

Do not use for:

- UI 文案、营销稿、品牌文案。
- 纯 API reference、机械操作手册。
- 只需要润色语气、不需要调整技术论证结构的短文本；那种场景优先 `style-aware-editor`。

## Core Pattern

默认按这条链路写：

`观察 / 代码 / 指标 / issue -> 归纳 -> 判断 -> 实现影响 -> 可观测性 / 验证`

不要先给结论，再回头找理由。更稳妥的顺序是：

1. 先说明看到了什么。
2. 再说明这些观察支持什么归纳。
3. 最后说明为什么更适合落到当前设计或实现上。

## Preferred Structure

长文优先按下面顺序组织：

1. 背景与目标
2. 现状拆解
3. 核心猜想或设计问题
4. 分节解答
5. 影响面与权衡
6. 可观测性、评测或验证方式
7. 收束结论

TL;DR 只保留三类信息：原因、猜想、决策。不要复述目录。

## Design Doc Mode

写或审内部设计文档时，先判断是否真的需要完整 design doc。只有改动复杂、风险高、跨团队协作、目标不清、会长期运行，或错了以后返工代价高时，才建议写完整设计文档；普通小改动用 issue、PR body 或计划说明即可。

设计文档不要覆盖所有实现细节。优先写错了代价高、后续难改、会影响接口/数据/权限/存储/部署/兼容性的决策；能在实现中低成本调整的 UI 小选择、局部命名和机械步骤不要占用评审篇幅。

设计文档优先覆盖：

1. Objective：一句话说明要解决什么问题。
2. Background：用当前事实、指标、代码路径或已有失败说明为什么要做。
3. Goals / Non-goals：明确完成后世界变成什么样，以及读者容易误解但不在范围内的事。
4. Scenarios / Interfaces：用真实场景、API、CLI、文件格式或用户路径说明系统怎么被使用。
5. Constraints / Dependencies：列出硬约束、外部依赖和难以替换的技术选择。
6. Reliability / Observability：说明 SLO、监控、告警、日志和验证方式；没有生产维度时写清楚为什么不需要。
7. Security / Privacy / Legal：只要涉及权限边界、敏感数据、外部输入或合规风险，就必须显式写。
8. Open issues / Alternatives：未决问题写问题、候选路径和下一步；已拒绝的重要备选只写为什么不选，不堆历史流水账。

评审设计文档时，重点找：

- 第一页是否能让没有上下文的人理解问题和目标。
- 目标是否写成用户、团队或系统收益，而不是实现动作。
- 非目标是否挡住了最容易发生的范围膨胀。
- 每个关键决策是否解释了约束、代价和为什么现在要定下来。
- open issues 是否有 owner 或下一步，而不是把不确定性藏起来。

## Source Deep Dive Mode

写源码分析、语言内部机制或系统实现文章时，默认进入源码深挖模式：

1. 先确认源码来源、版本、commit 或文档链接；如果用户要求最新状态，先重新获取或验证。
2. 从真实源码路径开始讲，不用泛化描述替代实现。
3. 解释关键类型、字段、函数、调用链、状态变化和失败路径。
4. 对复杂控制流、调度、并发、网络链路、状态机使用 Mermaid 或 ASCII 图，并在图后补文字解释。
5. 明确区分：源码事实、基于事实的推论、个人建议或最佳实践。
6. 补充常见误解、边界行为、生产使用注意事项和可验证实验。

如果用户已经指出“太浅”“没有细节”，不要局部加几段概念解释；应回到源码证据，重建文章结构。

## Hugo / Blog Notes

- Hugo/front matter/tag taxonomy 属于目标仓库约定，写作前优先读取该仓库的 AGENTS、README、相邻文章和 archetype。
- 不要把某个 blog 的 tag 规则写死到全局 skill；需要时在目标 blog 仓库自己的 AGENTS 中维护。
- 导入外部技术文档时，保留来源链接和上下文，区分原文事实、代码分析和自己的结论。

## Writing Rules

- 先证据，后判断；没有对应证据时，把判断放轻。
- 不新增来源没有提供的日期、数字、时限、SLA、能力或确定性结论；保留条件、例外、单位、默认值、兼容性和失败处理。
- 同一对象、状态和动作使用同一首选术语，不为避免重复而轮换技术同义词。
- 少用“显然”“其实很直接”“真正”“说明了一件事”这类抢结论句。
- 少用黑话，能写成具体对象、条件、约束、关系，就不要写成抽象口号。
- 中文引用统一用 `「」`。
- 结构信息优先用列表；论证顺序优先用 `1. 2. 3.`。
- 长段落里如果一句话删掉后不影响事实、论证或结构，优先直接删。

## Controlled Technical Instructions

当长技术文档包含操作步骤、API 流程、故障排查、运维 Runbook 或安全说明时：

1. 将读者执行前必须知道的条件、风险和停止条件放在动作之前。
2. 一个编号步骤只保留一个主要动作，并写清执行者和动作对象。
3. 区分人工操作与系统自动行为；必要时写出可观察的预期结果。
4. 故障排查先安排低风险、可逆、证据价值高的检查，再根据证据给出原因。
5. 将现象、证据、可能原因、恢复操作和验证方式分开，不把推测改成确定事实。
6. API 参数说明覆盖类型、是否必填、单位、默认值、允许范围、缺省行为和依赖关系；状态文案按实际语义翻译，不逐词映射。
7. 代码、命令、路径、字段、枚举值、配置项和响应原文保持不变。

以上规则基于 [Tech-Doc-Style-Chinese](https://github.com/Fenng/Tech-Doc-Style-Chinese) commit `a6f5b6064b92cac113e1277e5fbd266042e20577` 重新整理。上游内容由 Copyright (c) 2026 Fenng 按 [MIT License](https://github.com/Fenng/Tech-Doc-Style-Chinese/blob/a6f5b6064b92cac113e1277e5fbd266042e20577/LICENSE) 授权。该方法受受控语言思想启发，但不表示输出符合 ASD-STE100。

## 常见黑话替换

| 避免 | 更好的写法 |
|---|---|
| 赋能、生态、闭环、抓手 | 改成具体能力、依赖关系、入口、变量 |
| 很顺、很重、很轻、很丝滑 | 改成具体成本、风险、步骤、延迟 |
| 打通、落地、沉淀 | 改成哪个模块实现、哪个链路接通、记录到哪里 |

## Output

输出时至少保证：

1. 背景和问题清楚。
2. 每个关键判断都有前文证据或明确前提。
3. 影响面和验证方式没有缺位。
4. 如果是设计文档，明确哪些决策值得提前评审，哪些细节应留到实现阶段。

## Common Mistakes

- 先写结论，再补论据。
- 用评价词代替约束。
- 把英文技术抽象直译成中文判断句。
- 一直主持文章，却没有推进论证。
- 把 design doc 写成实现清单，或把低代价细节伪装成架构决策。