6.1 团队书写规范：十二条军规
6.1 团队书写规范：十二条军规
书写规范是团队对"Markdown 怎么写"的少量硬约定，目的是让所有文档像一个人写的、让 diff 只包含真实变更。这节给出一份可直接抄走的十二条规范，每条都配"为什么"——没有理由的规范没人遵守。
规范正文
一、无序列表统一用减号，有序列表统一 1.（渲染自动编号，插入项免改号）。
二、强调只用星号，不用下划线（1.2 节的理由：词内失效与辨识度）。
三、标题用井号式，跳级禁止：二级之后直接四级是结构混乱的信号；一篇文档一个一级标题。
四、标题层级止步于四级，更深的层级改为拆分文档或改用列表。
五、块级元素前后各留一个空行：标题、列表、表格、代码块、引用块、分割线，全部适用。空行是块级语法的呼吸空间，缺了它什么怪事都会发生。
六、代码块必须标语言（纯文本标 text），行内代码不标。
七、图片必须有替代文本，禁止空方括号。
八、禁止裸链接，链接一律 [描述文字](网址) 形式。
九、英文与中文之间加空格（"使用 Markdown 编写"），数字与单位同理；全角半角标点不混用。
十、文件名用全小写加连字符：deploy-guide.md 而非 部署指南（终稿）.MD——大小写在部分系统不敏感、部分敏感，中文括号在命令行是灾难。
十一、长文档按章拆文件，入口文件只放目录与导读。
十二、格式化交给工具：保存时自动格式化 + 全员同一配置，人工不调格式。
这十二条的公共哲学：把"风格决策"从写作时挪走。写作时不想减号还是星号，格式化工具替你想；评审时只看内容 diff，不看格式噪音。
为什么"少而硬"的规范才能活
规范最常见的死法是贪多——写上五十条，三个月后没人看。上面十二条我刻意控制在每条都能被工具检查或一眼 review 出的范围：前八条可以写成自动检查脚本（事实上社区已有此类 lint 工具），后四条在代码评审里一眼扫过。能自动化的绝不靠自觉，不能自动化的必须足够少。
规范覆盖的问题域
落地建议
新规范别开会宣布，走三步：把十二条放进仓库的一个规范文档；把格式化配置和检查脚本挂进构建；旧文档只改不刷——谁因真实需求改到哪个文件，顺手按新规范整理，全量刷格式会产生巨量假 diff，淹没真正的历史。
把前八条写成检查脚本
"能自动化的绝不靠自觉"这句话的最小兑现版本，是一个十几行的检查脚本——不依赖任何外部工具，扫一遍仓库里的 Markdown，把违反前几条军规的行抓出来：
# md_lint.py：军规检查（无序列表符号 / 裸链接 / 空替代文本 / 文件名） import re, glob, sys rules = [ ("星号或加号做无序列表", re.compile(r"^\s*[\*\+] "), "第一条：无序列表统一用减号"), ("裸网址", re.compile(r"(?<!\]\()(?<!<)https?://\S+"), "第八条：链接要有描述文字"), ("空替代文本", re.compile(r"!\[\]\(")), "第七条：图片必须有替代文本"), ] violations = 0 for path in glob.glob("**/*.md", recursive=True): for n, line in enumerate(open(path, encoding="utf-8"), 1): for pattern, name, msg in [(r[0], r[1], r[2]) for r in rules]: if pattern.search(line): violations += 1 print(f"{path}:{n} [{name}] {msg}") print(f"共 {violations} 处违规") sys.exit(1 if violations else 0)
# 挂进 CI：违规即失败，规范从"文档"变成"门禁" python md_lint.py
脚本刻意保持笨拙——正则有误报就调整白名单，宁可放过不可错杀，因为 lint 的威信建立在对的结果上：脚本说违规就是真违规，大家才会当回事。前八条军规里剩余几条（空行纪律、标题跳级）的正则稍复杂，但同构可加；社区现成的 lint 工具功能更全，自写脚本的价值在于团队对每条规则的完全解释权——规范是自己的，检查器也该是自己的。上线路径按上节三步走：先进仓库、再挂门禁、存量只改不刷，两个月内违规数会自然衰减到零。
本节要点回顾
- 十二条覆盖四个域：符号统一、结构纪律、内容合规、工具兜底。
- 能自动化的交给工具，不能自动化的必须够少，规范才能存活。
- 空行纪律（块级元素前后各一空行）是十二条里防病最多的一条。
- 旧文档只改不刷，避免假 diff 淹没历史。
军规的落地节奏：从三条到十二条
十二条军规一次性推给团队，几乎注定失败——规范本身成为负担时，人会整体拒绝它。可复用的落地节奏是分三批。第一批只推三条：符号统一（星号与减号）、空行纪律（块级元素前后各一空行）、文件头必写。这三条覆盖七成常见病，执行成本近乎零，一个月内就能看到 diff 变干净。第二批加入结构纪律（层级不跳档、单一级标题、列表缩进对齐），在团队已经尝到第一批甜头时顺势推出。最后一批才是内容合规与工具兜底类（替代文本、链接描述、格式化器钩子）。每批之间留六周习惯期，规范配合格式化工具自动化执行——人只负责少数机器管不了的判断。分批的实质是让规范跟着信任一起长，而不是从天而降。
规范的例外通道：让军规不变成枷锁
任何规范都会遇到不适用的一天，硬性执行只会催生"绕过"而非"遵守"。健康的设计是给军规留一条例外登记通道：确需违反某条时（比如演示方言差异的文档必须混用符号），在文档头部 YAML 里声明豁免条目并写明理由，评审时豁免声明合规即可放行。登记制的好处有三：例外可见（统计里能看出哪条军规被豁免最多，那正是规范需要修订的信号）；例外有责（理由写不出来就不能豁免）；规范可进化（豁免数据就是下一版修订的输入）。规范与例外的关系由此从对抗变成反馈回路，军规才能活得过三年。