--- name: technical-writing description: "分层技术写作标准:Diátaxis 结构、Google 开发者风格句子、STE 指令规则和全球英语句法。用于 /technical-writing,或编写、审查文档、RFC、README、PR 描述与提交信息时。" disable-model-invocation: true --- # 技术写作 在 Claude Code 中,每个会话在遵循此技能前,先阅读一次 [Claude Code 适配器](../../docs/harness/claude-code.md)。它将 pstack 技能中的 Cursor 名称映射到 Claude Code。 写得让疲惫的工程师也能读一遍就理解。应用下面全部四层。 有三条规则高于这些层次: - **删掉每个没有作用的词。** 去掉一个词后句子仍成立,就删掉它。“In order to”只需“to”。“It is important to note that”不提供任何内容。 - **用简短、日常的词。** 用“use”,不用“utilize”;用“help”,不用“facilitate”;用“do”,不用“perform”。长词必须用准确性证明其长度值得。 - **规则让句子变差时,换一种方式修改,或保持原样。** 一个遵守全部规则、却像机器写的句子仍然失败了。 代码库就是词表。写真实的符号、文件、标志或命令名,不用同义词或描述替代。 不要发明术语。用开发者会说出口的词:“移动”“删除”“只会减少的预算”,不用“撤离”“棘轮”或“终局”。有名称的模式可以使用,但文档首次提到时必须说明含义。在回复里给出新的问题用词及其替代词,附上 diff,建议将其加入 `unslop` 的抽象比喻规则。不要编辑该技能。 ## 让节奏有变化 文档可能符合每一层,读起来仍像机器写的:所有句子都被切得很短,没有观点,也没有具体内容。 - 有意混合句子长度。短句突出要点,长句承载事实及其条件或后果。 - 每句一个意思不等于每句一样长。承载两个意思的句子要拆开,只承载一个意思的长句则保留。 - 写作模式允许时要有观点。解释需要权衡取舍,所以说明你如何判断,而不只是罗列优缺点。参考资料保持客观。 - 选择具体表达,避免空泛。“重命名一列会让构建失败”比“Schema 变更可能导致问题”更明确。 ## 先选择模式(Diátaxis) 一份文档只采用一种模式。用两个问题决定:内容服务于行动,也就是做事,还是理解,也就是思考?它服务于学习还是工作? - 行动加学习:**教程**。 - 行动加工作:**操作指南**。 - 理解加工作:**参考资料**。 - 理解加学习:**解释**。 用这个判断工具检查整份文档,也可以检查单个句子。 **教程:在行动中学习。** 学习者能否成功是你的责任。开头说明学习者将构建什么,不要只说将“学到”什么。每一步都产生可见结果,而且尽早、频繁出现。说明他们应该看到什么:预期输出、提示符变化或日志行。将解释缩短为一个分句和一个链接。保持具体。用“我们”和指令来写:“首先做 x,现在做 y。” **操作指南:通向目标的步骤。** 解决一个人面临的问题,而不是介绍机器能够执行的一项操作。假定读者具备能力,不展开教学。只写行动:不岔开话题,不介绍背景,不为完整而完整。需要这些内容时链接过去。允许分支和判断:“如果你要 x,就做 y。”用任务命名指南:“如何校准雷达阵列”,而不是“雷达阵列校准”。 **参考资料:供查阅的事实。** 只描述,不指导、不劝说、不表达意见。客观、完整、确定地写出事实、选项、限制与错误,不含糊措辞。对应被描述对象的结构,让代码和文档可以一起导航。把内容放在读者预期的位置。能从代码生成就生成。 **解释:理解与原因。** 一个有边界的话题,离开产品本身也能阅读。每个标题前都应该可以隐含地加上“关于……”。围绕一个真实的“为什么”问题,提供设计决定、历史、约束和替代方案等背景。只有这种模式允许表达意见。 不要混合模式:教程里不放参考表,参考资料里不进行手把手教学,操作指南里不争论。拆开,再相互链接。 ## 面向读者写句子(Google 开发者风格) - 用“你”称呼读者,使用现在时。只有真正稍后才发生的事情才用“将会”。 - 说明谁做什么:“编译器检查”,而不是“被检查”。只有执行者未知或无关紧要时才用被动语态。 - 将操作写成命令:“点击提交。”直接陈述事实,不写“应该被完成”。 - 把条件放在指令之前:“要删除文档,点击删除。” - 先写常见情况,再写例外。 - 像一位懂行的朋友。没有流行词、比喻,也不在指令里加“请”。流程中不用“只需”“简单”“快速”等措辞。如果事情真的简单,读者就不需要来这里。 - 不预告尚未交付的能力,例如“我们很快就会支持……”,也不要让连续句子以相同短语开头。 - 链接文字应说明去哪里:页面标题或简短描述,不用“点击这里”。相比跳转到别处,优先在本页提供一句背景。 - 标题表达要点,而不只是主题:“先选择模式”,不是“模式”。英文用句首字母大写。任务标题使用简洁动词短语,例如“创建实例”;概念标题使用名词短语。每页一个 h1,不跳标题层级。 - 顺序使用编号列表,其他内容使用项目列表。用完整句子引出列表,条目保持并列结构。 - 代码使用代码字体,UI 元素使用**粗体**。英文使用牛津逗号。去掉“等等”,在开头说明列表只列出部分情况。 ## 让每次陈述只承载一项内容(STE 规则) - 每个句子只给一条指令。其他句子也只表达一个意思。 - 指令超过约 20 个词、其他句子超过约 25 个词时拆分。 - 把警告或条件放在其保护的步骤之前:“热油接触皮肤可能导致受伤。” - 保留英文中的“the”和“a”。“Remove backup file”有两种读法,“Remove the backup file”只有一种。 - 每个词只有一个意思和一个用途,并保持一致。如果“check”表示检查,就不要同时用它表示约束。 - 每个动作选择一个词并一直使用,例如始终用“start”,不要这里用“start”、那里改成“initiate”。 - 将操作写成直接命令,不写叙述或被动句:“安装组件”,而不是“组件必须被安装”。 - 可以避免时,不使用英文以“-ing”结尾的词。 ## 不让句子有两种读法(全球英语) - 把“only”“not”这样的词放在它们修饰的词旁边:“only fails on growth”与“fails only on growth”含义不同。 - 拆开长串名词:“the proto import budget check script”改成“the script that checks the proto-import budget”。 - 每个“它”“它们”“这”都应指向一个清楚的对象。不确定时重复名词。不要用“这”或“which”指代整个分句。 - 不省略动词。“阶段 1 移动转换器,阶段 2 运行时”让阶段 2 没有动词,应补上。 - 保留说明结构的小词,例如“Ensure that the switch is off”里的“that”。不要为了字数牺牲清晰度。 - 能避免误读时,在并列项中重复冠词:两件东西写“the client and the host”,不用“the client and host”。 - 句子可能有两种分组时,说明“and”或“or”连接哪些部分。“both...and”“either...or”“if...then”都可以消除歧义。 - 用句号,不用分号。将破折号替换成新句子。 - 括号中的文字应构成完整语法单位,或另起一句。不要用“(s)”表示可选复数。 - 不用斜杠:用“a、b 或两者”,不用“a/b”或“and/or”。 - 所有地方对同一对象只用一个名称。同一对象一会儿叫“门禁”、一会儿叫“棘轮”、一会儿叫“预算检查”,等于让读者学三件事。没有变化的内容不要改来改去。 - 避免习语、俗语、拉丁缩写和比喻。 ## 语气与仓库具体约定 - 将 **unslop** 技能用于本技能处理的每份文档。该技能负责维护模式目录:AI 词汇、废话、含糊措辞及格式痕迹。 - PR 描述与提交信息也是写作,除 Diátaxis 外,其余各层都适用。PR 正文是一份审查者可以在一分钟内读完的简报,不粘贴 swarm 日志、SHA 列表或指标表,而是链接过去。 - 产品 UI 文案不是文档。对这些文字使用产品文案指南。 - 代码片段用制表符缩进。写真实路径。每个数量或目录树主张在落地的提交上都必须正确,并附上重新生成它的命令。 ## 完整示例 修改前: > proto 导入棘轮预算脚本参数的配置通过 budget.json 执行。注意,重要的是要记住,运行 --write 会更新已提交的预算来反映当前数量,这项操作应该只在降低预算时执行。如果超过,CI 就会失败。 修改后: > `budget.mjs` 从 `budget.json` 读取已提交的预算,并统计导入 proto 的文件。如果数量超过预算,CI 就会失败。仅在降低预算时运行 `budget.mjs --write`。