asd-ste100

ASD-STE100

使用 ASD-STE100 简化技术英语规则撰写技术文本。STE 是航空航天和国防制造商用于维护文档的受控语言。这些规则旨在避免非英语母语的疲惫读者误读指令。作为副作用，它们也会去除 AI 生成文本的常见特征：长句、同义词轮换、模糊措辞、填充语和修饰性从句。

请为这位疲惫的读者写作。每个句子都必须让读者一读就懂。

你的任务

收到撰写或改写技术文本的请求时：

1. 选择模式（务实或严格，见下文）。
2. 将每段内容分类为程序性或描述性。其他规则都取决于这一步。
3. 起草前确定用词。 为检查／验证／确认这一概念选定一个动词，为配置／设置选定一个名词。全文不得用其他词表达这些概念。
4. 应用下方规则目录中的规则。
5. 交付前进行自检。 此步骤不可省略。
6. 绝不更改代码、标识符、命令或引用的错误信息（参见不可更改内容）。

收到检查文本而非撰写文本的请求时，请按以下格式报告每处违规：规则编号、违规文本、符合规则的改写。只引用本文件中存在的规则编号。不要凭记忆引用规则编号：编号并不直观，模型可能会编造编号（经测试——一个没有本文件的 Agent 引用了“规则 3.1：短句”；真正的规则 3.1 讲的是动词形式）。

两种模式

模式	使用场景	应用内容
务实（默认）	文档、README、错误消息——用户需要清晰的文本	所有结构规则。保留领域术语（“idempotent”“webhook”）。
严格	用户提到 STE、ASD-STE100 或合规性	结构规则 + 完整的词汇规范，并告知用户：完整合规需要官方词典（可在 asd-ste100.org 免费获取）。

第 1 步：文本分类

	程序性（指令）	描述性（说明）
目的	告诉读者要做什么	说明事物是什么或有什么作用
动词形式	祈使句：“安装泵。”	一般现在时／过去时／将来时
句子长度限制	20 个词（规则 5.1）	25 个词（规则 6.3）
单位规则	每句话一条指令（5.2）	每段一个主题（6.5），每段最多六句话（6.6）

不要在同一段内容中混用两种类型。“入门”部分属于程序性内容。“架构”部分属于描述性内容。程序中的注释属于描述性内容（最多 25 个词，不使用祈使句）。

规则目录

共 53 条规则，分为 9 个部分，内容根据 ASD-STE100 第 9 版改写，并附有软件示例。官方原文可在 asd-ste100.org 免费获取。

第 1 节 — 词语（规则 1.1-1.14）

规则	指示
1.1	仅使用获准的词语、技术名词或技术动词。
1.2	仅将获准的词语用作其列出的词性。
1.3	仅按获准的含义使用获准的词语。
1.4	仅使用获准的动词和形容词形式。
1.5	可以将领域词语用作技术名词（“webhook”、“commit”、“endpoint”）。
1.6	仅在未获准的词语是技术名词或技术名词的一部分时才使用。
1.7	不要将技术名词用作动词。
1.8	使用项目或行业中的技术名词。
1.9	选择技术名词时，选用简短、清晰的词语。
1.10	不要将地区用语、俚语或行话用作技术名词。
1.11	一个事物只用一个名称。不要在一处称其为“config”，在另一处又称其为“settings”。
1.12	可以将领域动词用作技术动词（“deploy”、“compile”、“merge”）。
1.13	不要将技术动词用作名词。
1.14	使用美式英语拼写。

在实用模式下，规则 1.5、1.8 和 1.12 发挥着关键作用：领域词汇可以使用。Agent 容易违反的是规则 1.7、1.11 和 1.13。

修改前： You can webhook the event, then do a deploy.
修改后： Send the event to the webhook. Then deploy the service.

第 2 节 — 多词名词（规则 2.1-2.2）

规则	指示
2.1	多词名词最多由三个词组成。
2.2	技术名词需要超过三个词时，先完整写出一次，然后提供简称或用连字符连接各部分。

用介词（of、on、in、for）拆分过长的名词链：

修改前： the connection pool timeout configuration value
修改后： the timeout value for the connection pool

第 3 节 — 动词（规则 3.1-3.7）

规则	指示
3.1	仅使用词典列出的动词形式。
3.2	仅使用：不定式、祈使式、一般现在时、一般过去时、一般将来时，以及作形容词用的过去分词。
3.3	过去分词仅可用作形容词（“the cached response”）。
3.4	复杂结构中不要使用助动词。不要使用现在完成时，也不要使用“is to be installed”。
3.5	“-ing”形式仅可用作技术名词或置于技术名词中（“logging”、“the mounting bracket”），绝不能用作动词。
3.6	使用主动语态。描述性文本中仅当执行者未知时才可使用被动语态。
3.7	用动词描述动作，而不是用名词（用“compress the file”，而不是“perform compression of the file”）。

获准的情态动词：can、will、must。禁用：should、would、may、might、could。
该标准甚至不允许用“could”表示可能性：写“an explosion can occur”，绝不要写“could occur”。对于“should”：要求应改为“must”；建议则应陈述为事实，或直接删除。这对 Agent 指令尤为重要——模型会将“should”理解为可选项。

修改前： The migration has completed and the table is being rebuilt.
修改后： The migration is complete. The database rebuilds the table.

修改前： The flag can be set in the config file, making restarts unnecessary.
修改后： You can set the flag in the config file. Then a restart is not necessary.

修改前： The temperature must be adjusted.
修改后： Adjust the temperature.

第 4 节 — 句子（规则 4.1-4.5）

规则	指示
4.1	句子要简短、清晰。
4.2	不要省略词语，也不要用缩写形式来缩短句子。保留冠词，保留“that”。
4.3	复杂内容使用纵向列表。
4.4	在主题相关的句子之间使用连接词（“Then”、“As a result”）。
4.5	在适用的情况下，在名词前加冠词（the、a、an）或指示形容词（this、these）。

规则 4.2 是反对过度简略的规则。STE 要求的是语法完整的短句，而不是电报式表达：

错误的简写： Ensure file exists before running.
STE： Make sure that the file exists before you run the command.

第 5 节 — 程序性写作（规则 5.1-5.5）

规则	指示
5.1	每个句子最多 20 个词。警告和注意事项也包括在内。
5.2	每个句子只写一条指示，除非两个操作同时发生。
5.3	使用祈使句编写指示：“运行迁移。”
5.4	将必需条件放在命令之前，并用逗号隔开：“如果构建失败，请查看日志。”
5.5	注释只提供信息，绝不包含指示。注释的上限为 25 个词。

之前： 配置客户端之前，你需要从仪表板获取 API 密钥，可以在“设置”中找到。 之后： 从仪表板的“设置”中获取 API 密钥。然后使用此密钥配置客户端。

第 6 节 — 描述性写作（规则 6.1-6.6）

规则	指示
6.1	逐步提供信息：每个句子只包含一个新事实。
6.2	使用关键词和短语，让文本具有清晰的逻辑结构。
6.3	每个句子最多 25 个词。
6.4	将相关信息归入同一段落。
6.5	每个段落只讨论一个主题。
6.6	每个段落最多六个句子。

描述性文本中不使用祈使句。描述用于解释，程序性文本用于指示。

第 7 节 — 安全指示（规则 7.1-7.3）

规则	指示
7.1	使用能表明风险等级的词语（“WARNING” = 人身伤害，“CAUTION” = 损坏）。
7.2	以清晰的命令或条件开头。
7.3	然后说明风险或可能的结果。

绝不要把指示埋在解释之后。这种模式可直接用于有破坏性的 CLI 标志、不可逆的迁移以及危险的 API 选项。

之前： 请注意，如果在生产环境中运行时恰好启用了破坏性标志，在某些情况下可能会丢失数据。 之后： CAUTION：不要在生产环境中使用 --force 标志。该标志会删除与源数据不匹配的行。

第 8 节 — 标点和词数（规则 8.1-8.7）

规则	指示
8.1	除分号外，所有常用标点符号都可以使用。请改写成两个句子。
8.2	使用连字符连接作为整体发挥作用的词语。
8.3	圆括号可用于引用、项目编号、缩写、复数形式、解释和备选项。
8.4	在纵向列表中，引导语末尾的冒号计作一个句子的结束标点。
8.5	圆括号内的文本计作一个词。
8.6	以下各项均分别计作一个词：数字、带单位的数字、缩写、字母数字标识符、引用文本、标题、标签、专有名词。
8.7	带连字符的词计作一个词。

规则 8.6 对软件文本很重要：反引号中的 sqlpipe run --config sqlpipe.yaml 属于引用文本，计作一个词。较长的标识符不会占用过多句子词数额度。

第 9 节 — 写作实践（规则 9.1-9.4，GR-1 至 GR-8）

规则	指示
9.1	逐字替换行不通时，重组句子。
9.2	正确使用每个经认可的词语：采用经认可的含义和词性。
9.3	不要构造短语动词（“go down” → “decrease”，“set up” → “install” 或 “configure”）。
9.4	在整篇文档中保持风格和术语一致。

GR-1 至 GR-8 的一般建议：保留连词 “that”，谨慎使用 “with”，明确代词的指代对象，优先使用 “this + 名词”，而不是单独使用 “this”，避免假朋友词，避免使用拉丁语缩写，使用包容性语言；只有确定所有格撇号形式正确时才使用（GR-8：如果不确定，就不要使用——非母语读者很难理解）。

软件文档中的 GR-6：“e.g.” → “for example”，“i.e.” → “that is”，并删除 “etc.”——列出具体项目，或写 “and more”。

词汇规范

ASD 拥有官方词典的版权（约 900 个核准词、约 1,200 个禁用词及其替代词），因此此处不转载。即使没有词典，其规则仍然适用：一个词，一个含义，一个词性。

已知的词性规定可用作参考模式：

单词	规定
test、check、work	仅作名词。“Do a test”，而不是“test the pump”。“Check that X”应改为“make sure that X”。
oil	在 STE 示例中仅作名词。作动词时，词典给出的词是“lubricate”。
help	仅作动词。作名词时，词典给出的词是“aid”：“with the aid of”。
fall	仅表示“因重力向下移动”，绝不表示“减少”。
follow	仅表示“接在……之后”，绝不表示“服从”。应写“obey the instructions”。
above、below	仅表示物理位置。表示限值时，应写“more than”“less than”。

情态动词梯度

你写的词	STE 的写法
should（要求）	must
should（建议）	删除，或改为陈述事实：“X is better because Y.”
may / might / could（可能性）	can
may（许可）	can
would（假设）	重组句子：“If X occurs, Y occurs.”

将浮夸措辞改为简单表达

此表由我们编写，并非 ASD 词典的一部分。它将 AI 生成的文档中过度使用的词替换为简单表达。如果某个词没有传达事实，就直接删除，不要替换。

浮夸措辞	改用
leverage、utilize	use
in order to	to
prior to	before
ensure	make sure that
it is worth noting that	（删除）
it's important to、crucially	（删除——直接陈述事实）
simply、just、easily、seamlessly、effortlessly	（删除）
robust、powerful、comprehensive、performant	（删除，或给出可衡量的属性）
functionality	function、feature
enables you to、allows you to	you can
is designed to、aims to	（删除——说明实际功能）
facilitate	help、make possible
dive into、delve into	read、examine
when it comes to	for
in the event that	if
due to the fact that	because
as needed、as necessary	（说明条件）
and/or	选一个，或写“X、Y 或两者”
e.g. / i.e. / etc.	for example / that is / （列出具体项目）
gracefully handles	（说明实际行为：“retries three times, then stops”）
out of the box	by default
under the hood	internally
blazingly fast、state-of-the-art	fast（给出数字）/（删除）
streamline	make simpler、make faster
plethora、myriad	many
addresses the issue、tackles	corrects the fault、removes the error

一致性检查

将以下常见的多种说法统一为一个术语（规则 1.11、9.4）：

• check / verify / confirm / validate / ensure → 选一个
• config / configuration / settings / options → 选一个
• delete / remove / drop / destroy → 每种含义选一个，并保持一致
• error / issue / problem / failure → 错误用“error”，操作未成功用“failure”
• run / execute / invoke / launch → 选一个
• show / display / render / present → 选一个

不可更改的内容

这些是技术名称（规则 1.5、8.6）。即使不符合词汇规则，也必须原样保留：

• 代码块、行内代码、标识符、CLI 命令、标志、文件路径
• 引用的错误消息和日志行
• 产品名称、API 端点名称、配置键
• 带单位的数字——在句子字数限制中，每个都计为一个词

超越文档

规则相同，目标不同。完整的改写内容见 references/use-cases.md：

• 错误消息：说明发生了什么（一般过去时）、已知原因，以及作为祈使句的修复方法。不要写“哎呀”，不要写“请确保”，也不要添加道歉填充语。
• 运行手册：STE 的主场。使用祈使步骤，先写条件，警告要放在步骤之前。
• 事件报告：只用一般过去时。“我们已发现一个可能造成影响的问题”改为“UTC 时间 14:02 至 14:31 期间，12% 的请求失败。”
• 发行说明：按警告模式说明重大变更——先写命令，再写风险。
• Agent 指令（提示词、AGENTS.md）：系统提示词是给无法提问的读者看的流程。每个句子只写一条指令，不要使用“应该”，条件前置。
• 翻译准备：STE 的本职工作。每个词只表达一种含义，并补全语法，可消除大部分翻译歧义。

交付前自查

这一步不可省略。对草稿进行以下四项检查：

1. 统计三个最长句子的词数。超过 20/25 词 → 拆分。
2. 搜索草稿中的：'ll、're、's（缩写形式）、has been、have been、should、逗号后使用的 -ing 动词、分号。
3. 搜索每一个 if 和 when。每个词都应位于句首，且在命令之前。“Increase the timeout if the network is slow” → “If the network is slow, increase the timeout.”
4. 搜索 Your Task 第 3 步中你未选用的动词（check/verify/confirm 这一组）。将所有匹配项替换为你选定的动词。

修正发现的问题，然后交付。如需完整审查，请运行 references/checklist.md。

完整示例

修改前（真实的、未经编辑的 AI 输出）：

连接超时。 如果 sqlpipe 挂起，或因 dial tcp: i/o timeout 而失败，请检查运行 sqlpipe 的主机能否访问 Postgres 端口（通常为 5432）——这通常是安全组或防火墙规则阻止了连接。如果你连接的是托管数据库（RDS、Cloud SQL 等），请确认该实例允许来自 sqlpipe 所用 IP 的连接。你也可以尝试在配置中增大 source.connect_timeout_seconds，因为网络路径缓慢时，即使连接最终成功，也可能触发默认超时。

修改后（分类后的流程，动词为 “make sure”，条件前置，每个句子一条指令）：

连接超时。 如果 sqlpipe 无法访问 Postgres 端口（默认 5432），它会因 dial tcp: i/o timeout 而停止。

1. 确保运行 sqlpipe 的主机可以访问 Postgres 端口。通常是防火墙或安全组阻止了访问。
2. 如果数据库由他人托管（RDS、Cloud SQL），确保该实例接受来自 sqlpipe 所用 IP 的连接。
3. 如果网络缓慢，请增大配置中的 source.connect_timeout_seconds。

改动内容：将 40 词的句子拆分为少于 20 词的句子；展开 “you're”；将 “check/confirm” 统一为 “make sure that”；将每个条件移到命令之前；删除 “etc.”；代码和错误字符串保持不变。

限制

STE 适用于技术事实和指令。不要将其用于营销文案、博客语气或品牌写作——它的设计目的就是消除说服性表达。当用户要求将营销文本改写为 STE 时，请说明这一点，并提出可将其用于文档。

此技能是非官方辅助工具，与 ASD 或 STEMG 无关联，也未获其认可；没有任何工具能够保证符合 STE。ASD-STE100 是 ASD 的注册商标。可从 asd-ste100.org 免费下载官方标准。

参考资料

• references/checklist.md — 完整验证流程，包含可搜索的模式，适用于检查模式和最终审查
• references/use-cases.md — 长篇改写示例：错误消息、运行手册、事件报告、提交说明、UI 文案、i18n