硬规则为强制要求，不可随意豁免：同一实体统一命名，消除模糊代词；删除 “适当、显著” 等无法核验形容词；名词修饰控制两层 “的” 以内，去除 “进行、处理” 这类名词化冗余表达；操作条件、警告前置，单步仅保留一个动作；不得编造缺失业务数据，信息缺口单独记录，不篡改原有业务事实与风险。
软规则建议达到 80% 遵守率，若不满足，必须写明豁免理由：尽量精简缩写、短句、段落；优先主动语态，时序与句式保持统一；原理备注与操作指令分离，警告精简，排版便于扫描阅读。
规范适用 README、操作手册、API 文档等技术文本，营销文案不适用。落地遵循五步流程：判定文档类型、对齐项目术语、改写文本、脚本预检查、交付正文 + 修改说明与缺口清单。
设计理念浓缩为十句禅语，核心原则是保留业务复杂度，消除晦涩表达，简化不等于删减风险与条件。项目约定优先级高于这套规范，脚本仅做筛查，最终仍需人工核验业务事实。
主要思想：不是让 AI 随便 “写清楚一点”，而是给 AI 一套可执行、可校验的受控中文写作规则，约束措辞、消除歧义，同时严禁 AI 脑补编造业务事实；目标是让人和 Coding Agent 都能唯一解读文档。
一、准备工作（前置）
-
获取技能本体 仓库：https://github.com/hylarucoder/hai-stack/tree/main/skills/hai-simplified-technical 主规则文件： SKILL.zh_CN.md，包含 46 条规则（28 硬规则 + 18 软规则）、正反示例、检查逻辑。 -
准备项目基线（优先级高于 hai 规范） 规则优先级：项目约定 > hai-simplified-technical
-
项目术语表：同一个对象固定唯一名称（例如统一叫 “配置文件”，不再混用设置 / 参数） -
已有项目写作规范、命名约定 -
确认文档类型：只用于技术类文档（README、runbook、API 文档、迁移指南、设计文档、代码注释、PR 描述、报错信息）；营销文案、演讲稿、科普散文不适用。
二、两种使用模式
模式 A：前置约束（生成文档前，推荐）
把 hai 规范作为系统提示词喂给大模型，让 AI 在写文档的过程就遵守规则，而不是写完再改。 指令模板示例：
加载 hai-simplified-technical 技能，参考 SKILL.zh_CN.md。 你正在编写技术文档，必须遵守这套中文受控技术写作规范：
-
优先使用项目术语表；项目约定优先级高于 hai 规则。 -
遵守硬规则；软规则尽量满足，不满足时记录理由。 -
遵循十原则：复杂胜于晦涩、明确胜于隐含、名字胜于代词、一个东西一个名字、动词胜于名词、具体胜于笼统、扁平胜于嵌套、条件 / 警告前置、面对缺口拒绝编造、规矩胜于感觉。 -
禁止使用指代不清的代词；同一实体只用一个名称；去掉 “进行、处理” 这类名词化包装；删掉无法量化的形容词（显著、适当）。 -
保留全部业务条件、风险、例外；不能为简短删减警告；不编造数据、不脑补系统行为。 -
输出两部分：①最终文档正文；②交付说明，列出信息缺口、违反软规则项与理由。 现在编写【你的文档主题】。
模式 B：后置改写校验（AI 已经生成文档，最常用）
对 AI 产出的初稿做评审 + 改写，也就是原文里的 5 步标准流程：
- 判断范围
确认文本是技术文档，排除营销 / 宣传段落；混合文档只修改技术操作部分。 - 读取项目约定
加载项目术语，对齐命名。 - 改写优化（只改措辞，不改事实）
⚠️重要：业务事实、风险、前置条件全部原样保留；简化≠删减业务复杂度，只是去掉晦涩表达。
-
替换模糊代词「它」，替换成组件 / 服务全名； -
名词化句式改造：把 “对日志进行压缩处理”→“压缩日志”； -
删除笼统修饰词：“适当、显著、尽快”； -
拆分嵌套长句，名词前面控制 “的” 不超过 2 层； -
调整语序：条件放指令前面，警告放在步骤前面； -
同一实体全程统一名称，不切换别名。 - 机器预检查：运行 check.py
脚本只标记可疑句子，不做最终判定： -
脚本检出项：歧义代词、笼统形容词、冗余名词化句式、超长嵌套句等； -
脚本没报错 ≠ 文档合格，脚本无法校验指代逻辑、业务事实真假。 - 交付输出
-
修改点简述； -
信息缺口清单（缺少数字、未确认行为，不在正文编造）； -
软规则例外清单 + 每一条例外理由； -
输出优化后的正文； -
附带交付说明： -
仅当缺失信息直接会导致操作失败，才在正文标注待补，其余缺口只写在交付说明。
三、落地避坑要点
-
❌ 误区：简化 = 写短。✅ 正确：保留所有必要条件、风险、例外，仅剔除晦涩包装。不能为缩短句子删掉警告。 -
❌ 误区：AI 可以自动补齐缺失信息。✅ 正确：面对缺口，拒绝编造。不确定的系统行为、缺失参数，不能脑补，全部交给作者确认。 -
❌ 误区：脚本可以替代人工评审。✅ 正确：脚本是辅助筛查；指代是否唯一、业务逻辑正确性，仍然要人 / 业务 Agent 复核。 -
❌ 误区：所有文档一刀切套用。✅ 正确：博客、发布文案的介绍段落不要套用，只处理里面操作 / 技术说明部分。
四、人工快速自查清单
可以交给人或者 Agent 逐条核对：
-
多主体场景，没有单独使用 “它” 这类代词 -
同一个组件 / 配置，全文只用同一个名称 -
没有 “适当、显著、尽快” 这类无法验证形容词 -
句式多用动词开头，无大量 “进行 XX 处理” -
操作步骤：条件前置，警告放在步骤之前 -
句子嵌套少，名词前不超过两个 “的” -
业务风险、例外条件完整保留，没有删减 -
没有编造任何不确定参数、系统行为 -
软规则例外都记录了理由
五、典型改写样例
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
六、进阶：把规范集成到自动化流水线
可以嵌入 CI / 文档工作流：
-
AI 生成初稿； -
Agent 加载 hai-simplified-technical 做文本改写； -
调用 check.py自动扫描，输出标记； -
人工审阅标记项 + 交付说明中的信息缺口； -
确认后合并文档；缺口项由开发补齐后再二次校验。
如果你想要，我可以直接输出一份可复制的完整系统提示词（直接粘贴给 coding agent），或者精简成一页可打印的文档评审 Checklist。
七、hai-simplified-technical 规范的软规则有哪些？
基础定义：
- 硬规则（28 条）：必须严格遵守，不能随意豁免
- 软规则（18 条）：建议遵守 80%；如果不遵守，必须写明理由，记录在交付说明
来源：hylarucoder 的 hai-simplified-technical（中文受控技术写作规范，基于 ASD-STE100），规则分为 9 个章节：词、名词短语、动词、句子、操作步骤、说明文字、警告、标点和长度、写作习惯。
说明：GitHub 仓库
SKILL.zh_CN.md原文里没有直接把 18 条软规则单独摘成独立清单，而是在 9 个章节里，每条标注【硬 / 软】。下面是从原文提取、归类整理的全部 18 条软规则，附带释义与例子。
一、词（2 条软规则）
-
尽量少用外来缩写；首次出现时附带全称。 例外理由：行业通用标准缩写（HTTP、JSON）可以不展开。
-
优先选用动词含义清晰、单义中文词汇，尽量避免一词多义口语词。 不是禁止所有多义字；如果上下文可以唯一锁定含义，允许保留。
二、名词短语（2 条软规则）
-
名词短语尽量简短，不堆叠多层修饰（硬规则：名词前最多 2 个 “的”；本条软规则进一步：尽量控制到 1 个）。 -
优先使用项目术语表已收录名词；新增术语时，在文档首次出现处定义。
三、动词（1 条软规则）
-
优先选用主动语态；被动语态仅用于执行者不重要、无法确定的场景。 例：不推荐 “日志被压缩”；推荐 “压缩日志”；但执行者未知时可以保留被动。
四、句子（3 条软规则）
-
单句尽量控制长度，句子过长优先拆分成短句；不强制卡死字数，以读起来无歧义为准。 -
同一段落，尽量保持主语稳定；频繁切换主语时，显式写出主体名称（硬规则禁止裸代词；本条软规则是段落层面的可读性优化）。 -
尽量不用反问、设问、修辞性否定；技术说明采用直白陈述。
五、操作步骤（3 条软规则）
-
一条步骤只写单一动作；多个独立动作尽量拆成多条步骤（硬规则：一条指令一个动作；本条是步骤可读性的补充）。 -
步骤按时间顺序排列；不要打乱时序写操作。 -
操作步骤尽量统一句式，优先动词开头；混合句式允许，但要记录理由。
六、说明文字（2 条软规则）
-
解释性背景、原理，放在操作步骤之后；前置背景尽量精简。 -
补充说明、备注单独放置，不要混在核心操作指令行内。
七、警告（1 条软规则）
-
警告文字简短，只写风险、后果与约束；不堆砌额外背景故事。
八、标点和长度（2 条软规则）
-
尽量少用长破折号、长分号串联多条件句子；改用短句、列表。 -
段落不要过长；大段文字拆成短段落或列表，提升 Agent 和人的扫描阅读效率。
九、写作习惯（2 条软规则）
-
保持全文语气一致；不要在同一份技术文档随意切换口语 / 书面风格。 -
文档写完，做一次逆向校验：把文档交给不熟悉项目的读者 / Agent，看是否会产生误解；如条件不具备，可省略，但需要写明理由。
软规则的使用约束（非常关键）
- 达标要求：软规则整体做到 80% 即可，不需要 100% 全满足
- 任何一条软规则如果选择不遵守，必须在交付文档的「修改说明」写明豁免理由，不能直接跳过
-
示例理由：为保留代码引用原文、项目历史固定写法、行业标准固定句式，不改动。 - 优先级：项目术语约定 > hai 硬规则 > hai 软规则
check.py脚本会标记软规则可疑项；但软规则标记项可以被人工 / Agent 豁免，只要写理由；硬规则标记项原则上不能豁免。
区分：硬规则 vs 软规则一句话
- 硬规则：关乎歧义、指代、事实编造，破坏就会造成读错、执行出错 → 强制，不能随便豁免
- 软规则：关乎阅读流畅度、排版、句式风格；就算违反，一般不会产生两种解读，只是可读性变差 → 推荐，可豁免，但是要写理由
配套：十句禅语和软规则关系
十句口诀是高层原则摘要，不是规则本身；46 条（28 硬 + 18 软）才是可逐条检查的底层规则。