plain-language-writing

plain-language-writing

两套独立的规则集。调用方需说明适用哪一套——COMMS 适用于只读一次、实时阅读的文本；ARTIFACT 适用于保存在持久文件中、会被重新阅读和审阅的文字。不要交叉应用；这两套规则针对不同的阅读条件进行了调整。

这些规则将有可靠依据的标准（ISO 24495-1、Kimble 的浅白语言研究、EARS、INCOSE 的《需求编写指南》）转化为可操作的做法，但每条规则都没有单独得到证实——应将其视为目前证据最充分的方法，而非保证有效的解决方案。请参阅上方的研究文档，了解哪些规则有充分依据（代词规则、COMMS #4 / ARTIFACT #3），哪些合理但尚未得到证实。COMMS #5（结构）完全没有实证依据——它的早期版本（A5）因缺乏证据而从研究中删除；此处保留该规则仅作为文风默认做法，而非已证实的规则。

COMMS — 面向用户的实时 Agent 文本

访谈问题、确认／回顾提示、状态更新、引导问题、阻塞／暂停／停止消息。

1. 句子长度。 大约不超过 20 个词。拆分更长的句子。

2. 每句一个分句。 不要用“并且／但是／这……”连接两个不同的想法。

3. 不要使用习语、隐喻或幽默。 直接陈述字面意思（不要说“让我们深入探讨”“提醒一下”“大概范围”）。

4. 避免使用指代不明确的代词。 如果一个句子引入了两个重要程度相近的事物，就不要用“它／这／那”指代前文；应明确说出所指对象。无需彻底删掉所有代词，只需避免存在多个合理指代对象的情况。

5. 因果／多步骤解释应使用带标签的结构，而非密集段落。 解释根本原因或多步骤过程（为何失败、因此会发生什么）时，应拆分为简短的全大写小节标签，并配上编号步骤，或用 IF/THEN 表示分支逻辑。简短的访谈问题或单行状态更新不受此规则约束——这些内容应保留为普通句子；强行套用结构会显得生硬。

   采用以下形式：

   PROBLEM.
   <one or more sentences naming what's wrong>
   
   WHY THIS HAPPENS.
   <mechanism, as numbered steps if there's a sequence>
   1. ...
   2. ...
   
   THE ROOT CAUSE.
   IF <condition> THEN <result>.
   IF <other condition> THEN <other result>.
   
   CONCLUSION.
   <one sentence confirming or correcting the user's read>
   
   NEXT STEP.
   <what happens next, or what's still open>
   

ARTIFACT — 持久文档中的文字

proposal.md、specs/*.md、design.md、tasks.md、align.md 中的自由行文。不得覆盖这些文档已要求采用的结构格式（### Requirement / #### Scenario 块、WHEN/THEN、复选框语法、差异操作标题、SHALL/MUST 用法）。

1. 不要使用含糊或留有余地的词语。 避免使用“足够”“合理”“酌情”“尽可能”“等等”。应说明可衡量的标准或明确的列表。
2. 每句只表达一项义务或一项决定。 不要用“和／或”连接两项要求或决定。
3. 避免使用指代不明确的代词。 适用条件与 COMMS #4 相同。
4. 规范性关键词只能出现在需求块中。 SHALL/MUST/SHOULD 仅在实际的 ### Requirement 语句中使用全大写形式——不得在叙述性文字中大写（proposal.md、design.md 的理由说明）。
5. 一个概念只用一个术语。 在 proposal.md、specs/*.md、design.md 和 tasks.md 中使用相同名称——不要在同义词之间来回切换（例如“用户”／“行为者”／“使用者”）。