Mcpp Docs Style

mcpp 文档规范

本规范回答六个问题:这份文档的归属(第一节)、为什么要有这一章(第二节)、 怎么写(第三至七节)、它必须对得上什么(第八节)、 它欠多少覆盖(第十节)、怎么评审它(第十四节)。

最核心的一条在第一节:用户文档是已实现功能的使用手册,不是设计说明。

代码注释与 commit message 不受本规范约束 —— 它们的读者、篇幅与目的都不同, 那里允许并鼓励叙述「为什么」以及实测过程。

一、文档的归属:三棵树与各自的准入判据

一份文档属于哪棵树,由读者决定,不由篇幅或主题决定。

用户文档是已实现功能的使用手册

这是本规范最核心的一条。

docs/** 服务的是要把事情做成的用户。它写 mcpp 已经实现的东西怎么用, 不写这些东西为什么被设计成这样,也不写什么设计了、什么还没设计。

不写进用户文档的四类内容,它们全部属于 .agents/docs/:

1. 设计理由与取舍 ——「为什么是一个机制而不是两个」「这个边界由模型的性质 决定而不是本文档的雄心」。
2. 被否掉的替代 ——「三种替代方案都不能去掉它」「某原语写出来又撤回了」。
3. 路线图与设计状态 ——「计划中」「将来会支持」「已设计未实现」「下一步是」。 用户文档里一个能力只有两种状态:能用(带版本下界)与不支持(一句话)。
4. 实现内幕 —— 除非用户不知道它就会用错。

判据(逐段问一遍):把这一段删掉,读者还能不能正确地用?

• 能 → 删掉,或移进设计记录。
• 不能 → 它不是设计论证,是使用信息;改写成事实陈述,去掉论证语气。

边界写成事实,不写成论证。 「当前边界」一节(第十节要求它必须存在)是一份 清单,不是一段说理:

理由就是不给。要理由的读者是另一类读者,他去读设计记录 —— 而用户文档 不链接设计记录(见上面的引用方向)。

已测状态(2026-09-08):九个用户章节含设计论证短语,05 21 处、13 8 处、 20 6 处,20 另有两个设计型标题。清理按 .agents/docs/2026-09-08-documentation-architecture-three-trees.md 的分阶段进行。

另外三条最容易被违反的推论

1. 用户章节不记历史。 「过去是 X,2026.8.16 起改成 Y」是设计记录的句子。 章节陈述今天是什么;版本相关写下界(2026.9.6.5+)。
2. 设计记录落地后不再编辑,除了追加状态行或一个具名带日期的更正块。 就地改写会让一份「某时刻的记录」悄悄变成「对现在的断言」。
3. 用户章节里出现「必须 / 禁止」,说明内容属于规范。 把它移进 docs/specs/,章节引用它。只有规范有规范性语气。

引用方向是规则,不是习惯

docs/          ──▶ docs/specs/        允许:引用精确语义
docs/          ─╳─ .agents/docs/      禁止
docs/specs/    ──▶ .agents/docs/      允许,仅限元数据表里的溯源行
docs/specs/    ──▶ docs/              允许
.agents/docs/  ──▶ 任何               允许
代码注释        ──▶ docs/ 或 specs/    允许,且被引用的文件必须存在

为什么那条边被禁止:设计记录描述一个时刻,不带稳定性承诺。用户章节想引用 它,只说明两件事之一 —— 章节不完整,或那份记录里的内容已经变成规范性的。两者 的修法都不是加链接,而是把内容提升上来(是操作就进章节,是保证就进规范)。

二、重构的定义,以及每章的设计规格

重构不是在既有文档上修补,是重新设计。 分组、重编号、把段落搬到别的章,这些 是重组;它们改的是索引,不是书。重构要回答的是:每一章为什么存在、给谁看、 放在哪里、按什么顺序、包含什么、传递什么信息 —— 并且把为什么写下来。

判据:拿掉某一章,读者少了哪个问题的答案?答不上来,这一章就没有被设计过。

四条产生每个决定的规则

每章的设计规格

动一章之前,先把这张表填出来。填不出来的那一格,就是还没设计的地方。

出版级的含义

这套规格施加于每一章,而不是只施加于新写的章。一份文档集合的质量由它最差的 那一章决定,因为读者不知道哪一章是被设计过的。

先设计再动手。 先重组、再设计,会得到两次重编号和一份没有被设计过的书 —— 第二次重编号的成本,就是没有先设计的代价。

三、总原则

文档是参考资料,不是博客,也不是聊天记录。判据只有一条:

一位不认识作者、只想解决自己问题的工程师,能不能在最短时间内拿到准确的事实, 并且不会误以为某个说法比实际更随意或更绝对。

由此得到四条可执行的规则:学术、陈述、精确、克制。

「学术」在这里是具体的三件事,不是气质:每个断言的强度与它的证据相符(第七节)、 每个可粘贴的东西都可复现(第八节)、每个枚举都有分母(第十节)。

四、标题

标题一律是名词短语或陈述句,不使用疑问句、不使用口语片段。

疑问句标题把「读者已经知道自己在找什么」这个前提丢掉了 —— 目录里一列问句, 读者要先把每个问句翻译成主题才能定位。

「…的原因」「…的依据」「…的范围」是把 why 型标题转成名词短语的常用形。 保留 why 本身,去掉疑问语气。

判据是疑问词,不是问号。「谁在为这个落差付账」「打什么由谁决定」都不带问号, 都是疑问句。检查脚本第一版只匹配 ? / 吗 / 呢,两句全部通过。判据是这一组词: 谁、哪、什么、多少、为何、如何、怎样、怎么。

表头单元格与标题同规。 一个列头按每一条要紧的性质都是标题:它命名一个主题、 被跳读、并且是读者扫描时看的那一行。| 部分 | 大致相当于谁的活 | 通过了当时 全部的检查,而它是全树最直白的一处违规。

这条同样管部分名与段位名,不只管章节标题。「人人都需要」描述的是受众、 是一个句子片段;「基础」是这一段是什么。受众写在每章开头的「读者」那一行, 不写在目录的骨架上。

五、词汇

不采用的类别

1. emoji 与装饰性符号:✅ ❌ ⚠️ ⭐ 🎉 🚀 💡 🔥 以及同类。 状态用词表达:已实现 / 部分实现 / 未实现、是 / 否、 已验证 / 未验证。一个符号要靠图例才能读,而词不用。
   • docs/**、docs/specs/**、README* 今天是零 emoji,保持。
   • .agents/docs/** 的既有记录里有四千余处(⚠ / ✅ / ⭐ / ❌)。 新记录不使用;既有记录不回改 —— 设计记录落地即不可变, 为统一符号去改写历史记录,改的是它唯一的价值。
2. 网络用语与口语:搞定、干活、坑、真香、翻车、打脸、一把梭、白给、 凉了、炸了、神器、黑科技、敲黑板、划重点。
3. 拟人与比喻性行话:姊妹篇、腿(fat package 的一份产物)、travel(源码 「旅行」)、picky、happy path 的中文直译。技术术语本身可以是比喻 (rpath、sysroot),但不要新造比喻。
4. 填充语:其实、说白了、简单来说、众所周知、显然、当然、值得一提的是。 如果一件事显然,就不必说;如果不显然,「显然」会让读者怀疑自己。
5. 含糊的程度词:很快、非常、极其、基本上、差不多。用数字或范围替代 —— 「2.42×」「64.77s」「四个平台中的三个」。

人称

默认不使用第二人称。写动作的对象,不写「你」。

• 不采用:你可以在 mcpp.toml 里写 …
• 采用:在 mcpp.toml 中声明 …

例外:教程体文档可以使用第二人称,因为那里读者正在跟着做。教程体是 列出来的,不是推断的:00-getting-started.md、01-examples.md、 04-build-from-source.md。其余全部按参考文档处理。

引用 mcpp 自身输出的部分不受此限:did you mean 'x86_64-linux-musl'? 与 your toolchain : … 是程序打印的原文,逐字复现是要求,不是文风问题。 检查脚本因此会先剔除行内代码段再判定。

六、句式

• 陈述句优先。 命令式仅用于操作步骤(「运行 mcpp build」)。
• 一句话一个事实。 从句套从句的长句拆开。
• 不使用反问。「难道不应该……吗?」没有信息量。
• 不使用感叹号。
• 破折号克制使用:插入语用逗号或括号;破折号留给「随后是对前半句的 重述或收束」这一种用法。

七、断言的强度必须与证据相符

这是本规范里最实质的一条,也是最容易违反的一条。

不要把推断写成实测。 反例(本仓库真实发生过):把「守卫在原生构建上失效」 写成实测结论,而它是从「targetTriple 结构上可能为空」推断的;实际运行时 它非空,结论不成立。判据:「结构上可能」不等于「运行时确实」—— 要么读运行时产物,要么不要写成实测。

同理,不要用「完全」「永远」「所有平台」这类全称词,除非确实逐个验证过; 写「已在 Linux / macOS / Windows 验证」比写「全平台可用」更有价值, 因为前者可被检验。

「支持」有三档,分开写。 同一个「是」可能意味着三件不同的事,合并写就是 把最弱的一档说成最强的:

八、文档必须对应当前实现

一份与实现脱节的文档比没有文档更坏:读者按它写出来的东西编不过,而错的是 文档,他不知道。

1. 写作与核对一律读 origin/main,不读工作树。 工作分支可能落后若干个 发布;「现在的实现是什么」只有 origin/main 能回答。

2. 每一个可粘贴的东西都必须可复现:命令、输出、报错原文、路径、版本号。 判据是「在当前发布版上跑一遍能不能得到这一行」。做不到就删掉,或标注版本 下界。诊断信息里那行可粘贴的版本号也是承诺 —— 它会被读者原样敲进去。

3. 改实现的 PR 同时改被它作废的文档。 判据:这次改动触到的每一处 docs/ 断言都重新读一遍,而不是等下一次文档 PR。

4. 用户章节不引源码行号。 读者手上没有那一版源码树。引文件与符号 (src/pack/prebuilt.cppm 的 tag_check)。规范可以引文件与符号; 设计记录可以引行号,因为它记录的是一个时刻。

5. 一份文档「对齐到哪个版本」必须可判定。 规范由元数据表的「对应实现」 回答;章节由它写出的版本下界回答。都没有,就说明没人能判断它是不是过期的。

6. 过期的判据不要用子串搜索。 「grep 到这个词就算讲过了」会在有人改一次 措辞时静默变空转。要判断一份文档是否覆盖某个能力,读结构化的东西 —— 示例的 mcpp.toml、源码里的键表、print_usage() 的正文。

7. 也不要数一个代理量。 子串搜索的孪生形态:数代码块个数来判断「是不是把 几种做法并列了」、数含某词的标题来判断「哪一章拥有这个主题」。数字是真的, 而被量的对象不是那个性质 —— 正因为数字是真的,评审很难发现。判据要直接指向 性质:并列的替代由「alternatively / 也可以 / 等价写法」这类并列标记识别, 主题归属由「这一节是不是在解释它」识别。

   本轮三次同形:用含 test 的标题数「哪几章解释测试」、用字面拼写查反查索引、用 代码块数量查并列替代。三次的数字都对,三次量的都不是那个性质。

九、梯度:一个主题的五级台阶,以及只链接相邻级

文档目录要有梯度,读者才能按自己的深度进入。同一个主题从浅到深有五级:

规则:每份文档开头用一行「相关文档:」指出它的上一级与下一级,并且只链接 相邻级。 参考文档向上链到教程与示例、向下链到规范;它不直接把读者丢进设计 记录,那是跨两级 —— 也正是第一节那条被禁止的边。

梯度本身由入口承载,不由每份文档自报级别:docs/README.md 的角色索引把 「我想做 X」映射到章节、示例与模板。一份自称「本章是第 2 级」的文档对读者没有 用处,而一条指出上下一级的链接有。

一个能力的文档化按这个顺序推进,不跳级:先有一个能跑的最小形态,再有字段参考, 再在「两个实现会不一致」时抽出规范。倒过来做会得到一份没有人验证过的规范。