53条规则记不住SimpleEnglish真正起作用的8条杀手级规则详解20/25词上限与一词一义【免费下载链接】SimpleEnglishAgent skill: make LLMs write docs in ASD-STE100 Simplified Technical项目地址: https://gitcode.com/gh_mirrors/si/SimpleEnglishSimpleEnglish 是一个开源 Agent Skill让 AI 按照 ASD-STE100简易技术英语Simplified Technical English编写技术文档——这是飞机维修手册沿用 40 多年的受控语言。它让 AI 写出的 README、错误信息、运维手册短小、清晰、无歧义顺带消灭 AI 味废话。标准一共有 53 条规则记不住你只需要搞懂下面 8 条杀手级规则就能拿到 90% 的效果。✈️ 先搞懂为什么航空文档不可能被误读ASD-STE100 的设计目标只有一个让一个疲惫的、非英语母语的读者不可能误读一条指令。为此它对写作做了硬约束词汇来自约 900 个批准词表一个词只有一个含义句子有字数上限只允许简单时态、主动语态每个 if 条件必须写在指令之前。SimpleEnglish 把标准的 53 条规则整理成 9 大章节的规则表并补充了软件文档场景的改写示例全部在 skills/simple-english/SKILL.md 里。项目作者对这件事的总结很精辟Clearly写清楚是一种观点单句不超过 20 词才是规范。Agent 只会跟规范走。️ 快速上手三种方式安装 SimpleEnglish方式一一条命令通用所有 Agent 客户端Claude Code、Cursor、Codex、Gemini CLI 等 25 客户端npx skills add AminBlg/SimpleEnglish方式二Claude Code 插件额外附带会话 hook 与输出样式claude plugin marketplace add AminBlg/SimpleEnglish claude plugin install simple-englishsimple-english方式三客户端不支持 skill把 prompts/system-prompt.md 粘贴进你的系统提示词或 AGENTS.md 即可文末还附了 60 token 的超短版本适合上下文预算紧张的场合。装好后直接让 AI 写技术文档或加一句rewrite this with simple-english。 杀手级规则一20/25 词句子上限标准里最著名的一条对应规则 5.1 和 6.3文本类型单句上限程序性文本告诉读者做什么20 词描述性文本解释某物是什么25 词软件开发者最关心的细节反引号里的命令、标识符、带单位的数字都只算 1 个词规则 8.6。所以sqlpipe run --config sqlpipe.yaml只算 1 词长标识符不会撑爆句子预算。来自 examples/before-after.md 的真实示例Before一句话 40 词If sqlpipe hangs or fails withdial tcp: i/o timeout, check that the host running sqlpipe can reach the Postgres port (usually 5432) — this is often a security group or firewall rule blocking the connection...After拆成多句每句 ≤20 词Make sure that the host that runs sqlpipe can connect to the Postgres port. A firewall or security group usually blocks it.长句是 AI 味的第一来源字数上限是最直接的手术刀。 杀手级规则二一词一义One Word, One Meaning规则 1.11一个东西一个名字。同一个东西不能一会儿叫 config、一会儿叫 settings。这是 AI 的死穴模型喜欢轮换同义词check、verify、confirm、validate 在文档里混着出现——人读着觉得是一回事AI 自己执行时却会当成四个不同操作。SimpleEnglish 要求动笔前先选定词汇全篇保持一致还附带了一张AI 味词 → 平实词对照表references/word-swaps.md覆盖 leverage、robust、seamlessly 等 30 多个高频 AI 味词。另一类典型错误——名词动词混用Before:You can webhook the event, then do a deploy.After:Send the event to the webhook. Then deploy the service.⏳ 杀手级规则三只允许简单时态只允许不定式、祈使句、一般现在时、一般过去时、一般将来时。没有现在完成时没有 is being installed 进行时被动规则 3.2、3.4。Before:The migration has completed and the table is being rebuilt.After:The migration completed. The database rebuilds the table.这条对事故报告特别有用We have identified an issue...现在完成时会藏住问题发生的时间点而简单过去时逼你给出明确时间线——Between 14:02 and 14:31 UTC, 12% of requests failed. 杀手级规则四禁用 -ing 动词形式-ing 形式只能当技术名词用如 logging永远不能当动词规则 3.5。它针对的正是 AI 最爱往句尾挂的装饰性分词从句Before:The flag can be set in the config file, making restarts unnecessary.After:You can set the flag in the config file. Then a restart is not necessary.️ 杀手级规则五主动语态谁做的必须写出来。被动语态只在描述性文本中、执行者确实未知时可用且也建议改用 you 或 we 作主语规则 3.6Before:The temperature must be adjusted.After:Adjust the temperature.Before:Indexes are not used on this table.After:We do not use indexes on this table.这一条直接消灭 it should be noted that、was designed to 这类 AI 味被动句。⚖️ 杀手级规则六禁用 should/would/may/might/could只留 can/will/must标准的情态动词阶梯非常干净你写的改成should表要求mustshould表建议删掉或陈述为事实may / might / could表可能性can标准严格到连可能性都不许用 could必须写 an explosion can occur。这对 AI Agent 指令尤其关键模型会把 should 读成可选项然后悄悄跳过那一步。 杀手级规则七条件在指令之前规则 5.4每个 if/when 条件必须写在指令之前中间用逗号分隔Before:Increase the timeout if the network is slow.After:If the network is slow, increase the timeout.为什么重要拖在句尾的条件...if the flag is set读者经常执行完命令才看到——条件已经晚了。条件前置读者才会先判断、再行动。 杀手级规则八一句话只给一个指令规则 5.2一句话一个动作除非两个动作同时发生。步骤可以跟一句补充但只用于说明直接结果或限制条件Before:Youll want to grab the API key from the dashboard before configuring the client, which you can do under Settings.After:Get the API key from the dashboard, under Settings. Then configure the client with this key.这是运维手册和聊天消息的分界线前者必须能在凌晨 2 点、值机压力下照着执行。 加餐两条反电报体 禁止破折号保留冠词、保留 that规则 4.2STE 是短句但语法完整不是电报体。Ensure file exists before running. 应写成 Make sure that the file exists before you run the command.禁止破折号skill 自加的额外检查破折号把两个分句拼在一起却隐藏了逻辑关系读者只能猜这是因果对比举例。写成 because、but、for example或拆成两句Before:The deploy failed — the disk was full.After:The deploy failed because the disk was full.⚙️ 为什么这些规则起作用两种模式 五步自检SimpleEnglish 不是一张词表而是一套完整写作流程选模式默认 pragmatic 模式结构规则 保留你的领域词你点名 STE/ASD-STE100 时进入 strict 模式加完整词汇纪律先给每段文本分类为程序性或描述性——20/25 词上限和动词形式都依赖这个分类先定词汇再动笔只选一个检查动词、只选一个配置名词全篇一致应用规则后做五步自检数最长的三句、搜违禁词、检查每个 if 的位置、检查列表格式——这一步不可跳过绝不改代码标识符、CLI 命令、引用的报错信息都是不可触碰物原样保留。只想审计现有文档而不是重写用 references/checklist.md 里的完整检查清单每条违规都有搜索模式 → 修复方法的对照表。 效果有数据背书违规率下降 74.6%项目团队用确定性正则 linter 做了 7 个 Claude 模型 × 8 个写作任务的 A/B 基准测试共 112 次生成每百词 STE 违规平均减少 74.6%其中 claude-opus-5 单项降幅 85%盲测对比另一模型当裁判、不标注标签56 组文本中45 组更偏好 skill 的输出所有模型的输出 token 数都下降了——文本越清晰用词越少。全部数字都能从仓库提交的原始文件复现基准方法与注意事项见 evals/results/RESULTS.md。 延伸阅读资料路径完整规则表53 条 / 9 章节skills/simple-english/SKILL.mdAI 味词 → 平实词对照表references/word-swaps.md完整审计清单references/checklist.md扩展场景错误信息、Runbook、事故报告、发布说明references/use-cases.md真实 Before/After 改写示例examples/before-after.md最后提醒一句STE 适用于技术事实与指令不适用于营销文案和品牌写作——它按设计会删掉一切说服力。博客用你自己的声音写文档交给 SimpleEnglish。【免费下载链接】SimpleEnglishAgent skill: make LLMs write docs in ASD-STE100 Simplified Technical项目地址: https://gitcode.com/gh_mirrors/si/SimpleEnglish创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
