technical-writing git:20260920.878daedA

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

---
name: technical-writing
description: 在起草或重构中文技术设计文档、架构笔记、源码分析、评审稿或工程分享文章时使用；先用代码、指标和约束建立论证，再按文档类型加载对应规则。只需润色短文本或调整语气时使用 style-aware-editor。
---

# 中文技术写作

把背景、观察、判断、影响和验证讲清楚，让技术同伴能复核结论并继续工作。不要用流畅措辞掩盖证据缺口，也不要把技术文档写成营销稿。

## 选择模式

先确定交付物，只读取对应参考：

| 交付物 | 参考 |
| --- | --- |
| 设计文档、架构评审、技术决策说明 | [references/design-document.md](references/design-document.md) |
| 源码深挖、调用链、语言或系统机制文章 | [references/source-analysis.md](references/source-analysis.md) |
| 操作手册、API 流程、故障处理、安全说明 | [references/controlled-instructions.md](references/controlled-instructions.md) |
| Hugo 或工程博客文章 | [references/hugo-article.md](references/hugo-article.md) |

短技术说明、评审摘要或架构笔记可直接使用下面的共同流程。只需处理 AI 味、术语或语气而不调整论证结构时，交给 `style-aware-editor`。

## 共同流程

1. 明确读者、文档类型、要推动的判断和文档覆盖范围。
2. 收集可引用的代码路径、版本、指标、issue/PR、实验和约束。缺失事实能从当前仓库或官方资料确认时先验证，不用想象补齐。
3. 按以下证据链组织内容：

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

4. 先列章节职责，再写正文。每节只承担一个主要问题，删除不能推进事实、论证或操作的段落。
5. 复核数字、日期、版本、状态、链接、术语和确定性。区分源码事实、外部来源、基于证据的推论和个人建议。
6. 最后检查影响面、失败路径、验证方式和未决问题是否缺位。

## 共同写作规则

- 先证据，后判断；证据不足时降低确定性，不反向寻找理由支持预设结论。
- 不新增来源没有提供的日期、数字、SLA、能力或成功结果；保留条件、单位、默认值、兼容性和失败行为。
- 同一对象、状态和动作使用同一首选术语，不为避免重复而轮换技术同义词。
- 用具体对象、条件、约束和关系替代“赋能、生态、闭环、打通、落地、沉淀”等抽象词。
- 默认只写目标、适用范围和会改变判断的约束。不要为了结构对称增加“非目标”“不做什么”或“范围外”章节；确有必要的排除项应写进对应方案、兼容性、安全或验收段落，并说明具体影响。
- 代码、命令、路径、字段、枚举值、配置项和响应原文保持不变。
- 图表只用于复杂控制流、状态变化或三个以上组件关系；图后补充文字解释和证据边界。
- Hugo 元数据、标签和目录规则属于目标仓库约定，优先读取仓库指令和相邻文章，不写死到全局技能。

## 输出契约

根据交付物和读者组织内容，不固定套用章节。成稿满足：

1. 读者能从必要上下文理解文档要解决的问题；短说明不重复铺陈目标和范围。
2. 每个关键判断都有前文证据、来源或明确前提。
3. 事实、推论、建议和未验证项可以区分。
4. 影响面、失败路径和验证方式只在与主题相关且会改变读者判断时展开。
5. 不为完整感虚构备选、指标、负责人或已完成验证。

用户要求编辑文件时，复读修改后的完整文档并执行目标仓库适用的格式或构建检查；只要求草稿或审查时，不擅自落盘。

本技能的受控技术说明规则基于 [Tech-Doc-Style-Chinese](https://github.com/Fenng/Tech-Doc-Style-Chinese) 提交 `a6f5b6064b92cac113e1277e5fbd266042e20577` 重新整理。上游内容由 Copyright (c) 2026 Fenng 按 MIT License 授权；本技能不声称输出符合 ASD-STE100。