技术方案写作用词规范：技术方案写作用词规范指南
做好技术方案写作用词规范，核心就一句话：砍掉所有“大概、可能、优化、赋能、高可用”这类虚词，把动作、对象、量化指标和异常边界全部写死，直接用“确定性词汇字典 + 标准化句式模板 + 自动化脚本卡点”落地交付。
平时看多了那种满篇“全面提升系统性能”、“实现数据生态闭环”的PPT式技术方案，评审会上问一句“QPS能扛多少、超时怎么熔断”就当场哑火，上线后开发和运维互相甩锅。技术方案不是写给外行看的宣传稿，每个模糊的形容词，都是线上故障的定时炸弹。
一、 核心方案速览
要在一个研发或运维团队里快速跑通技术方案写作用词规范，别搞几十页的文档制度让人背诵，直接按下面三步落地：
- 建立“禁用词黑名单”：凡是出现“优化、提升、左右、尽快、尽量、支持高并发”等无定语词汇，评审直接打回。
- 强制套用“四要素句式”：所有核心设计描述必须满足
触发条件 + 执行动作 + 量化目标 + 异常兜底。 - 接入 CI/CD 文本门禁：用 Python 正则脚本扫描 Git 仓库里的 Markdown 方案文档，扫到未量化的模糊词直接阻止合并，逼着写方案的人把话说清楚。
二、 实操细节深度拆解
1. 干掉虚词：用量化指标替换模糊形容词
最常见的问题是方案里满眼都是“大幅优化”、“明显降低”、“安全可靠”。这种词在验收时就是扯皮的根源——响应时间从 2 秒降到 1.9 秒算不算“优化”？
适用场景：所有架构设计、性能改造、数据库调优类方案的“背景与目标”、“核心改造点”章节。
避坑点：不要只写结果数值，必须同时写明基准测试环境（并发数、数据量级）和统计口径（P95 还是平均值），否则开发拿空表跑出 1ms 也算达标。
直接套用下面的改写对照模板：
# ❌ 踩坑写法（虚无缥缈，无法验收）
1. 对订单查询接口进行深度优化，大幅提升响应速度。
2. 引入 Redis 缓存，保证系统的高可用和稳定性。
3. 定期清理历史日志，释放服务器磁盘空间。
# ✅ 规范写法（可测试、可监控、可验收）
1. 通过联合索引覆盖与分页游标改造，在 500 万行数据量、500 QPS 压测条件下，将 `/api/v1/order/list` 接口的 P99 响应耗时从 480ms 降至 80ms 以内。
2. 引入 Redis Sentinel 主从集群（1主2从3哨兵），单节点宕机时 15 秒内完成自动故障转移；缓存击穿场景下通过互斥锁限制回源并发 ≤ 10。
3. 每日凌晨 03:00 执行 Cron 任务，压缩 7 天前的 Nginx 访问日志并归档至对象存储（OSS），物理删除本地超过 30 天的归档文件，确保根分区使用率低于 75%。2. 动作与状态确权：把容易歧义的动词写死
很多线上事故不是代码能力不行，而是方案里的动词大家理解不一致。我以前踩过最大的坑：方案里写了一句“下线旧版商品，清理关联冗余数据”，结果后端开发直接写了 DELETE FROM 物理删除，没做状态标记也没留备份，业务方第二天要恢复数据时全员傻眼。
适用场景：数据迁移、接口定义、权限变更、上下游联调文档。
避坑点：禁止单独使用“清理、同步、兼容、支持”这四个万金油动词，必须加上定语限定其底层行为。
建议直接在团队文档库置顶这份词汇确权字典（YAML 格式，方便团队查阅或工具读取）：
# 技术方案核心动词确权规范
data_operations:
删除:
banned: "删除数据 / 清理数据"
required: "必须明确为【逻辑删除（更新 is_deleted=1）】或【物理删除（先导出冷备至OSS再执行DELETE）】"
同步:
banned: "同步数据 / 实时同步"
required: "必须明确为【同步阻塞调用（HTTP/RPC）】或【异步最终一致（基于Kafka延迟<5s）】"
compatibility:
兼容:
banned: "兼容老版本 / 兼容多端"
required: "必须明确为【向后兼容（老客户端不升级可正常解析新字段）】或【双写过渡（维持14天后下线旧接口）】"
consistency:
一致性:
banned: "保证数据一致"
required: "必须明确为【强一致性（本地数据库事务ACID）】或【最终一致性（对账任务T+1补偿）】"3. 异常与降级话术：写方案必须先写“炸了怎么办”
新手写方案只写正常流程（Happy Path），资深老兵看方案先翻异常处理章节。千万别写“如果接口报错则友好提示用户”，这等于没写。
适用场景：第三方 API 对接、微服务调用、MQ 消费、批处理脚本设计。
避坑点：异常话术里必须包含超时时间、重试次数与退避策略、降级兜底动作、告警级别与阈值，缺一不可。
可以直接复制下面这段 Markdown 模板填进你的技术方案里：
### 异常与熔断降级策略
- **超时设置**：调用第三方支付网关接口连接超时（Connect Timeout）设为 `1000ms`，读取超时（Read Timeout）设为 `3000ms`。
- **重试机制**：仅针对网络超时及 `HTTP 502/503/504` 状态码触发指数退避重试，最多重试 `2` 次（间隔 `500ms`、`1500ms`），针对 `HTTP 4xx` 业务错误**严禁重试**。
- **熔断降级**：当连续 60 秒内错误率超过 `20%`（且样本请求数 ≥ 30）时触发熔断，持续 `30` 秒；熔断期间直接返回兜底错误码 `PAY_CHANNEL_BUSY` 并提示“支付通道维护中，请 1 分钟后重试”，同时将请求写入本地降级重试队列。
- **监控告警**：触发熔断时立即向【核心交易运维群】发送 `P1` 级企微机器人告警，日志记录级别为 `ERROR`，日志中必须包含 `trace_id` 与上游原始 `err_code`。4. 技术专有名词与单位拼写规范
虽然这看起来像强迫症，但一份连 MySQL 写成 mysql、KB 和 Kb 乱用的方案，极其影响专业度，甚至会闹出带宽和存储容量差 8 倍的乌龙（MB/s 和 Mbps 混用是行业重灾区）。
实操规则如下：
- 大小写严格按官方拼写：
MySQL、Redis、Nginx、Kubernetes（或简称K8s）、JavaScript、JSON、HTTP、API。别写成Mysql、redis、json。 - 单位必须区分大小写：存储容量用
KB / MB / GB / TB（1 Byte = 8 bits）；网络带宽速率用Kbps / Mbps / Gbps。写限流规则时，务必写明10 MB/s还是10 Mbps。 - 中文与英文/数字之间保留半角空格：例如
部署 3 台 Nginx 节点，可读性会比挤在一起高一个档次。
5. 自动化落地：用 Python 脚本卡死低级错误
靠人肉 Review 规范是反人性的，时间一长大家都会松懈。把下面的脚本丢进你们的 GitLab CI 或 GitHub Actions 里，每次提交 .md 格式的技术方案自动跑一遍。
适用场景：使用 Git 管理技术文档（Docs-as-Code）的团队，或者在本地写完方案发评审前自检。
避坑点：正则匹配不要搞得太死板，允许“禁用词 + 具体数字”豁免，否则误报太多大家会直接绕过检查。
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import re
import sys
from pathlib import Path
# 定义高危模糊词及修改建议
BANNED_PATTERNS = [
(r"(大幅|显著|明显|极大)(提升|降低|优化|减少)", "禁止使用模糊程度副词，请替换为具体前后对比数值（如：从 300ms 降至 80ms）"),
(r"(大概|大约|左右|差不多|尽量|尽可能)", "禁止使用不确定词，请给出明确边界或阈值（如：≤ 50ms、最多 3 次）"),
(r"保证(系统)?高可用", "请明确高可用量化指标与容灾方式（如：SLA 99.95%、单机房故障 30s 内切流）"),
(r"(尽快|及时)(处理|告警|恢复)", "请明确时间 SLA（如：1 分钟内触发告警、15 分钟内完成恢复）"),
(r"(删除|清理)(历史|过期)?数据(?)", "必须注明是【逻辑删除】还是【物理删除】及备份策略"),
(r"(?<!\w)(mysql|nginx|redis|k8s|json|api)(?!\w)", "专有名词大小写不规范，请按官方写法修正（如 MySQL、Nginx、Redis、K8s、JSON、API）"),
]
def check_markdown(file_path: Path) -> int:
error_count = 0
lines = file_path.read_text(encoding="utf-8").splitlines()
in_code_block = False
for line_num, line in enumerate(lines, start=1):
# 跳过代码块内部内容，避免误伤日志示例或代码注释
if line.strip().startswith("```"):
in_code_block = not in_code_block
continue
if in_code_block:
continue
for pattern, msg in BANNED_PATTERNS:
matches = re.finditer(pattern, line)
for m in matches:
print(f"[规范告警] {file_path}:{line_num} -> 命中 '{m.group(0)}' | 建议: {msg}")
error_count += 1
return error_count
if __name__ == "__main__":
if len(sys.argv) < 2:
print("用法: python check_doc.py <方案文件路径.md>")
sys.exit(1)
target = Path(sys.argv[1])
if not target.exists():
print(f"文件不存在: {target}")
sys.exit(1)
errors = check_markdown(target)
if errors > 0:
print(f"\n校验失败！共发现 {errors} 处用词不规范，请修改后再提交评审。")
sys.exit(1)
print("校验通过！文档符合技术方案写作用词规范。")三、 高频关联问题拓展
1. 方案既要给业务老板看，又要给研发落地看，用词怎么兼顾？
这是最容易两头不讨好的场景：写得太底层，产品和老板看不懂直接跳过；写得太业务化，开发照着写全是漏洞。
解决方案：采用“双层映射结构”。文档最开头的【一、核心收益与变更摘要】用业务影响词，正文【二、技术实现细节】严格执行硬核技术量化词。千万不要把两种词混在同一个段落里。
# 正确示范
## 一、方案摘要（面向业务/管理层）
本次重构解决大促期间下单页面卡顿问题，将核心提交链路抗压能力提升至日常流量的 5 倍，预计可支撑单场活动 10 万笔/分钟的峰值成交，异常情况下可自动降级保障主流程不崩溃。
## 二、技术指标与架构设计（面向研发/测试/运维）
- 峰值目标：订单创建接口 `/v2/order/create` 支持 `1667 QPS` 稳定写入，P99 耗时 ≤ `150ms`。
- 降级开关：基于配置中心动态下发 `degrade_coupon_check=true`，大促阻塞时关闭优惠券实时校验，改为异步发券补偿。2. 怎么区分“必须做”和“建议做”的强制力？
方案里经常写“建议对参数做校验”、“需要记录日志”，结果开发觉得“建议”就是不用做，测试觉得“需要”就是强需求，最后又吵一架。
解决方案：直接引入互联网和国际标准（RFC 2119）的强制力分级词，在方案开头声明定义，全篇加粗使用：
- 【必须】/【严禁】（MUST / MUST NOT）：底线要求，不满足直接阻断上线。例：用户输入参数【必须】经过 SQL 注入与 XSS 过滤；【严禁】在日志中明文打印用户手机号与身份证号。
- 【应当】/【不建议】（SHOULD / SHOULD NOT）：标准最佳实践，除非有充分理由并在评审会备案，否则按此执行。例：列表查询【应当】使用游标分页替代深分页
OFFSET。 - 【可选】（MAY）：锦上添花的功能，排期紧张时优先砍掉。例：导出报表【可选】支持异步邮件通知。
3. 团队积习难改，怎么低成本推行这套规范？
别一上来就搞“历史文档大清洗”，几百篇旧文档改到猴年马月去，还会引起全员抵触。
正确推法只有三步：
- 老人老办法，新人新办法：只卡增量。从下周一的新需求开始，不用新模板、不过脚本校验的方案，架构师/TL 直接拒绝参加评审会。
- 先抓“P0级重灾区”：不要求全文档无瑕疵，初期只卡死接口契约、数据库变更、监控告警这三个最容易出线上事故的章节。
- 提供可直接抄的模板库：工程师不是不想写规范，而是懒得从头排版。把上面给的异常模板、YAML 字典放进公司 Wiki 或 Git 模板仓库，新建文档直接一键引用，推行阻力能少 80%。
四、 结尾总结
把技术方案写作用词规范真正落地，从来不是为了追求文字有多优美，而是为了降低团队的沟通熵增，把本该在评审会上暴露的模糊地带，消灭在敲代码之前。记住核心原则：形容词全部换成数字，动作全部限定边界，异常必须配齐超时与降级。
现在就可以把文中的 Markdown 异常兜底模板 和 Python 自动检测脚本 直接复制进你的项目仓库，下次写方案或做 Code Review 时跑一遍，你会发现无意义的口水仗至少少一半。