简化技术英语 是做什么的？
概述
Jarrett 规则第一条：聊天输出、生成的文档、代码注释和提交消息使用简化技术英语。该风格基于 ASD-STE100 的原则。读者能更快找到信息。非英语母语的读者能更少误解。
此技能是我们自己的总结。它并非 ASD-STE100 标准，也不包含其词典。
何时使用
- 编写或编辑规范、计划、ADR、README、词汇条目或其他文档。
- 编写代码注释或提交消息。
- 审查文本是否符合规则第一条。
不适用于：代码标识符、引用的输出（错误信息、日志、命令输出）、技能文件或用户撰写的文本。
流程
先撰写文本。然后逐条检查每条规则。
| # | 规则 | 错误示例 | 正确示例 |
|---|---|---|---|
| 1 | 每句一个主题。 | 钩子读取文件，如果文件缺失，则打印警告，用户会看到该警告。 | 钩子读取文件。如果文件缺失，钩子打印警告。用户看到该警告。 |
| 2 | 指令不超过20个单词。描述不超过25个单词。 | 确保在推送分支之前，你已经运行了完整的测试套件并检查了输出。 | 运行 ./scripts/test.sh。然后推送分支。 |
| 3 | 使用主动语态。 | 规则由钩子加载。 | 钩子加载规则。 |
| 4 | 指令使用祈使句。 | 测试应在提交前运行。 | 在提交前运行测试。 |
| 5 | 一个单词只有一个含义。使用 .claude-work/docs/VOCABULARY.md 中的术语。 | 先“警告”，随后对同一动作使用“标记”、“提醒”或“通知”。 | 每次都使用“警告”。 |
| 6 | 使用简单时态：现在时、过去时、将来时。 | 钩子本来应该正在检查输入。 | 钩子检查输入。 |
| 7 | 使用单个动词，而不是动词短语或习语。 | 启动构建。找出原因。 | 开始构建。查找原因。 |
| 8 | 保留“the”和“a”等冠词。 | 运行脚本，检查输出。 | 运行脚本。检查输出。 |
| 9 | 每个步骤只包含一个指令。 | 1. 打开文件并更改版本。 | 1. 打开文件。2. 更改版本。 |
| 10 | 每个段落不超过6个句子。 | 一个包含十个句子的段落。 | 两个简短段落或一个列表。 |
更多规则：
- 在适用步骤之前编写警告或注意事项。以危险开头：“警告：此操作将删除分支。”
- 使用数字而非文字表示数值：“72个字符”，而不是“七十二个字符”。
- 当给出三个或更多项目时，使用列表或表格。
- 不要使用同义词来变化文本。重复同一术语。
- 当名词不明确时，不要使用“它”或“这”。重新指明该名词。
- 当术语不在词汇表中且含义不明确时，询问用户。然后将该术语添加到词汇表中。
常见误解
| 误解 | 事实 |
|---|---|
| “短句子听起来像机器人。” | 短句子阅读快速且难以误读。读者的速度比风格更重要。 |
| “同义词使文本不单调。” | 同义词会让读者怀疑是否指代不同的事物。 |
| “这条注释太小，不适合规则。” | 注释和提交消息都在适用范围内。小文本容易修正。 |
| “被动语态更正式。” | 被动语态隐藏了执行动作的主体。指明动作的执行者。 |
红色标记
- 使用“and”、“which”或“so that”连接不同主题的句子。
- 指令中出现“should”、“could”或“might”。
- 同一事物在文档中有两个名称。
- 一个步骤包含两个动作。
- 警告出现在其适用的步骤之后。
验证
- 每个句子只有一个主题。
- 所有指令不超过20个单词。所有描述不超过25个单词。
- 所有指令使用祈使句和主动语态。
- 所有术语与词汇表匹配。
- 每个列表步骤包含一个指令。
- 没有段落超过6个句子。