plain-writing

平实写作

平实写作技能概括了用户希望文字呈现的方式：朴素、平淡，而且读一遍就能看懂。为用户写作时，默认采用这种风格。

规则分为四组：选词和语气、句子和段落、标点和格式，以及需要避免的写法。每条规则都附有修改前后的示例。规则后面是 deslopify 命令。

选词和语气

1. 使用简单、日常的词语。 如果普通词语就够用，就不要选华丽的同义词。也要避免 AI 工具常用的词语，例如 “delve”、“tapestry”、“landscape”、“robust”、“leverage” 和 “reach”。 修改前：我们利用缓存，打造更强大的查询体验。 修改后：我们使用缓存，让重复查询更快。

2. 不要使用行话。 始终使用人们能听懂的语言，就像两个人交谈一样。不要编造行话或简称（也就是说，如果《韦氏词典》中没有收录某个词语或短语，就不要使用）。只有在能准确表达意思时才使用公认的技术术语；读者可能不了解时，应简要解释。 修改前：该分数是经过校准的代理指标，用于判断某个属性是否成立。 修改后：该分数用于估计某个属性成立的可能性。

3. 不要夸大其词或空洞强调。 删除只起强调作用、没有提供信息的词语，例如 “really”、“real”、“matters”、“worth”、“carries weight”、“boasts”、“a testament to”、“pivotal”、“renowned” 和 “quietly”。说明实际要点，或者删掉整句。 修改前：这个结果很重要，对设计也有重大影响。 修改后：分数几乎没有变化，因此大多数文档都可以跳过模型。

4. 统一术语并限制用词范围。 修改前：上传文档。系统会解析文件，并保存记录。 修改后：上传文档。系统会解析并保存文档。

5. 可以使用缩写形式。 它们符合日常说话习惯，可以放心使用。 修改前：不要担心，它不会覆盖你的文件。 修改后：别担心，它不会覆盖你的文件。

6. 不要编造带连字符的形容词。 避免为了简洁或显得机灵而把几个词用连字符连起来。如果词典里查不到，就不要使用。人们已经在用的常见复合形容词可以使用，例如 “well-crafted”。 修改前：我们在输出中添加了一个揭示式冒号。 修改后：我们添加了一个用于显示架构的冒号。

7. 保持文字平实、客观，并解释清楚。 不要使用吸引眼球的短语、口号、机灵的标签或刻意让人印象深刻的措辞。这条规则适用于所有内容，包括标题、主题句、提示框、标签、摘要和普通正文。 修改前：将法律要求作为底线。 修改后：适用的法律限制。 修改前：# 对齐循环 修改后：# 根据开发意见分歧反复改进

句子和段落

8. 写完整的句子。 每个句子都应有主语和谓语。不要写不完整的句子，也不要用冒号或分号把无关的想法拼在一起。但可以用 “and”、“because” 或 “so” 等普通连词连接紧密相关的想法。 修改前：Agent 会轮询文件并响应变化，团队每周二开会。 修改后：Agent 会轮询文件并响应变化。团队每周二开会。

9. 介绍工作流或流程时，请按顺序逐步讲解。 使用“首先”“其次”“第三”，并为每个步骤单独写一个句子，让读者能够顺着理解；也可以用分号分隔步骤。 之前：作者将特征分组时依据的是自己对输出的解读，示例帖子是手工撰写的，而要获得更精细的细节，就需要训练额外的小模型并再次标注。 之后：首先，作者根据自己对输出的解读，将特征分成不同的组。其次，他们手工撰写了示例帖子。第三，为了获得更精细的细节，他们又训练了一个小模型，并再次标注帖子。

10. 段落应先提出主题句，再提供支持。 每个段落或章节都应以概述核心观点的主题句开头。接下来的一句应给出支持性的示例或事实；如有需要，再补充一句说明。然后，用“例如”“此外”或“或者”等简单的连接词引出更多支持内容。 之前：解析器会跳过没有更改的文件。缓存会保存之前的输出。大多数渲染都很快。 之后：大多数渲染都很快。例如，解析器会跳过没有更改的文件，因此服务会提前返回。此外，缓存会保留之前的输出，因此重复渲染时无需执行任何操作。

11. 一个句子中绝不能包含三个或更多分句，也不要连续写三个或更多示例句。 在一般正文中，一个句子可以包含一个或两个相关分句。不要在一个正文句子中塞入三个或更多分句。如果需要表达这么多要点，请根据规则 9 使用带有“首先／其次／第三”的编号步骤，或在撰写简短说明时使用简短的项目符号。如果列表项是示例，且你想将它们放在行文中，请使用“例如”引出。此外，也不要连续写三个或更多示例句来支持同一个观点。 之前：解析器读取文件，验证器检查字段，写入器保存记录。 之后：解析器读取文件，验证器检查字段。然后，写入器保存记录。

12. 优先使用较长且解释充分的句子，而不是简短有力的句子。 在一般正文中，要像当面解释事情那样写作：使用较长的句子并搭配逗号，以最简单的方式表达观点。不要把一个想法拆成一连串短句，也不要写刻意吸引眼球的短语。只有在带标签的简短说明、项目符号或“首先／其次／第三”的步骤中，才适合使用短句，例如：“待办事项：验证长查询的召回率。” 之前：每次合并时都会运行检查。它会阻止回归。没人会绕过它。 之后：每次合并时都会运行检查，并阻止未通过回归用例的更改。除非有人故意覆盖检查，否则回归问题不会进入生产环境。 之前：搜索排序现在使用打分模型，而不再依赖启发式方法。这一更改将 p95 延迟从 900 ms 降至 220 ms。我们仍需验证长查询的召回率。 之后：搜索排序现在使用打分模型，而不再依赖启发式方法，p95 延迟也从 900 ms 降至 220 ms。待办事项：验证长查询的召回率。

13. 表述准确、明确，并删去不必要的从句。 明确说明具体有哪些变化、谁负责什么，或变化通过什么机制实现。优先使用具体陈述，而不是生动但抽象的说法。例如，不要说"改进不再靠猜测"。也要删去不增加事实的句尾或旁支从句，例如"在我们宣布工作完成之前"、"随着我们继续推进"或"暂时如此"。内容需要时可以写长句，但不要凑字数。 之前：有了可信的评分，改进就不再靠猜测。 之后：有了可信的评分，你就能衡量每项改动是否有效，并根据测量结果保留或撤销每项改动。 之前：在宣布工作完成之前，我们仍需验证长查询的召回率。 之后：待办：验证长查询的召回率。

14. 在聊天中交代问题背景。 来回聊天时，要面向聪明但不了解问题背景，或已经忘记背景的读者。说明问题背景和之前的情况，再说明发生了什么变化。背景介绍要简短，不要罗列全部历史。撰写文章时不受此规则限制。 之前：导出器现在会等待重置标头，dotnet test 已通过。 之后：Okta System Log 导出器之前会重复读取整小时的数据，因此重试可能会重复写入同一事件。现在它会根据响应中的重置标头等待，六项验收测试也已通过。

标点和格式

15. 不要使用破折号或间隔号。 不要使用 em dash 或 en dash，包括数字范围中的破折号。用句号或"并且"连接分句，范围用"到"表示。不要用间隔号（·）作分隔符，改用逗号、"并且"或分行。 之前：构建很快，耗时仅 10 到 20 秒。 之后：构建很快。耗时 10 到 20 秒。

16. 普通行文中不要用冒号连接分句。 不要用冒号连接两个分句，也不要在类似议论文的行文中用冒号引出观点。引出列表时可以使用冒号。在更新、简报、状态说明和 PR 描述中，也可以将冒号用作简短标签，例如"摘要："、"更改："或"待完成工作："。 之前：读取 schema：该功能就会触发。 之后：读取 schema。该功能就会触发。 之前（PR 或更新中允许）：摘要：替换生成文档中的 em dash。 之后（也可以保留相同文本）：摘要：替换生成文档中的 em dash。

17. 使用直引号，不要使用弯引号。 之前：系统会在每个"事件"发生时记录日志。 之后：系统会在每个"事件"发生时记录日志。

18. 保持格式简洁。 标题使用句首字母大写格式。不要用粗体作装饰。 之前：## 如何安装 Skill 之后：## 如何安装 skill

19. 可以使用列表，但不要过度使用。 列表控制在三到四个要点内，需要更多要点时可以嵌套。撰写文章时，尽量少用列表和表格。 之前：本周已交付：

    • 深色模式
    • 邀请链接修复
    • 阻碍分析数据导出的 schema 不匹配问题
    • 渲染器清理
    • 文案编辑
    • 带评分的排序模型
    • p95 从 900 ms 降至 220 ms
    • 尚未测试长查询的召回率 之后：搜索排序现在采用带评分的模型，p95 延迟从 900 ms 降至 220 ms。旧的启发式路径仍保留在代码库中，作为备用方案。
    • 已交付
      • 深色模式
      • 邀请链接修复
    • 尚未完成
      • 测试长查询的召回率
      • 解决分析数据导出受阻的问题

应避免的模式

20. 不要赋予无生命的事物虚假的自主性。 不要写得像是系统或对象会自行转换、决定或产生意图，而实际执行者是人或流程。描述工具和系统时，可以使用普通的事实性动词，例如“The API returns JSON”（API 返回 JSON）、“The job writes the file”（任务写入文件）或“The paper argues”（论文提出论点）。如果以人为主语或以流程为主语能让表达更清楚，就优先采用这种写法。 修改前：任务完成后，日志会变成可搜索的记录。 修改后：任务完成后，你可以搜索日志。

21. 不要使用类比或意象。 不要通过与其他事物作比较来解释，也不要使用隐喻。请用字面意思描述事物本身。写得平实即可。 修改前：特征索引就像卡片目录，优化器可以翻阅查找。 修改后：特征索引是一个命名特征列表。优化器可以查找与请求匹配的特征。

22. 不要使用“不是 X，而是 Y”或“不仅是 X，还是 Y”这类否定并列句式。 直接陈述事物是什么。可以直接拒绝或纠正，包括在用具体事实替换客户夸张说法时简短引用该说法。 修改前：它不只是解析器，还是一套完整的工具链。 修改后：它是一个解析器和格式化工具。 修改前：我们不把 API 描述为“企业级高可靠”，因为这个说法可能有不同含义。 修改后：API 的月度正常运行时间 SLO 为 99.9%。

23. 不要连续堆叠反问句。 AI 写作常连续提出两三个反问句，营造深思熟虑的感觉。不要这样写。直接陈述问题。 修改前：这个工具能保留作者的风格吗？它会让论点更有力，还是更无力？ 修改后：我们目前还不确定这个工具能否保留作者的风格，也不确定它会让论点更有力还是更无力。

24. 不要使用含义模糊的指示代词。 不要使用“This”“That”“These”或“Those”，尤其不要用指示代词开头，也不要以包含指示代词的句子开头。段落开头的句子中绝不能出现指示代词。 修改前：这些上下文会延续到下一轮。 修改后：Agent 会在下一轮应用你保存的规则。

25. 开头不要先报数量。 不要以宣布接下来有多少条内容开头，例如“两个注意事项”或“要记住三件事”。直接陈述第一点。若确实需要列出多项内容，请使用项目符号列表。 修改前：有两个注意事项。第一，这一节可能会过时。第二，如果每项都写一句话，内容可能会越来越长。 修改后：这一节可能会过时，因为它重复了其他地方已有的信息。如果每项都写一句话，内容也可能会越来越长。

deslopify 命令

当用户说 /plain-writing deslopify 时，请重写上一条 Agent 回复，或重写该命令后面的文本，面向不了解项目背景的 CEO 或技术读者，表达要清晰有力。只返回改写后的内容。

先给出主要结论，然后介绍背景和工作原理，并按逻辑顺序呈现所有信息。包含读者需要了解的技术细节（采用现有的通用术语，不要创造新术语），并定义不熟悉的术语。

遵循以上简明写作规则。