Zed 品牌文案评分体系:rubric.md 中的 8 维五档质量标尺

本文围绕 rubric.md 展开,这是 Zed 文档仓库中用于校验品牌文案质量的评分细则:8 个评分维度、每维 1–5 档、全维度 4 分及以上才算通过(满分 40,及格线 32)。读完本文,你可以掌握 Zed 如何把"文案语气"这件主观事情变成可量化、可复现的质检流程,并能独立地对一段 Zed 风格的文案打分、诊断失败维度并按决策规则驱动改写。

一、rubric.md 在 Zed 文档体系中的位置

rubric.md 位于 docs/.conventions/brand-writer/ 目录,与三份姊妹文件共同构成 Zed 的"品牌写作"约定:

文件	职责
SKILL.md	brand-writer 技能的核心语音原则与写作/评审工作流
rubric.md	8 项评分标准(即本文主角)
taboo-phrases.md	必须清除的词汇与句式模式
voice-examples.md	10 组改写前/后对照示例,用于评分校准

上表中 voice-examples 的正确路径为 voice-examples.md。

rubric 不是孤立存在的规范,它被两处直接引用:

• CONVENTIONS.md 开头声明:结构规范之外,"语气与写作风格见 brand-writer/ 目录",并在文末"Quality Checklist"中把 "Passes brand voice rubric (see brand-writer/rubric.md)" 列为文档完成的必要条件;
• SKILL.md 把 rubric.md 标注为 "8 scoring criteria for validation",在写稿工作流的第 3 阶段(诊断)与 --review 评审模式中逐条使用。

换句话说:CONVENTIONS.md 管文档的结构(frontmatter、章节顺序、术语、锚点),rubric.md 管文案的语气与可信度,两者一起构成 Zed 文档质量的完整门禁。

二、评分机制总览:8 维 × 5 档,全维度 4+ 才通过

rubric 开篇即给出两条硬性规则(rubric.md#L1-L4):

• 每个标准按 1–5 分打分;
• 文案必须在所有标准上拿到 4 分及以上才算通过(Copy must score 4+ on ALL criteria to pass)。

这个"全维度门槛"设计比单纯看总分更严格:即使总分达到 32/40,只要有一项是 3 分,整篇文案就不通过。8 个标准如下:

1. Technical Grounding(技术实证性)
2. Natural Syntax(自然句法)
3. Quiet Confidence(克制的自信)
4. Developer Respect(对开发者的尊重)
5. Information Priority(信息优先级)
6. Specificity(具体性)
7. Voice Consistency(语气一致性)
8. Earned Claims(有据断言)

下面逐条继承原文档的完整评分档位表与示例,并补充每维度的判分要点。

三、八个评分维度详解

3.1 Technical Grounding(技术实证性)

评判问题:文案是否做出了具体、可验证的技术论断?

分数	档位描述
5	可验证的精确技术细节(规格、架构、可测量的结果)
4	具体且有明确含义的技术论断
3	具体与模糊的技术指代混杂
2	大体抽象,偶尔出现技术术语
1	没有任何技术实质;纯营销语言

原文档给出的对照示例:

• ✅ "Written in Rust with GPU-accelerated rendering at 120fps"
• ❌ "Blazingly fast performance that will transform your workflow"

判分要点:5 分要求"可验证"——规格、架构、可测量结果都要能落到证据上。Zed 自己的文案示例恰好都能在仓库里找到落点,见第六节的源码印证。

3.2 Natural Syntax(自然句法)

评判问题:行文是否像一个 thoughtful 的开发者自然说出的话?

分数	档位描述
5	句式多变,节奏自然,朗读顺畅
4	大体自然,有轻微节奏问题
3	可见一些 AI 腔但尚未占主导
2	明显的结构性模式(三段排比、破折号连击)
1	通篇机械节奏、模板化句式

原文档列出的红旗信号:破折号(em dash)滥用、"It's not X, it's Y" 句式、三连排比、所有句子长度雷同。这些红旗与 taboo-phrases.md 中 "AI Structural Patterns" 一节(Em Dash Chains、"It's not X, it's Y"、Triple Parallel Lists、Colon-Introduced Lists、Rhetorical Questions as Openers)一一对应,评审时可交叉扫描。

3.3 Quiet Confidence(克制的自信)

评判问题:文案是否不带吹捧与情绪操纵地陈述事实?

分数	档位描述
5	让事实自己说话;读者自行得出结论
4	自信陈述,修饰极少
3	有一定克制,但偶有 hype 渗入
2	频繁使用最高级或情绪诉求
1	激进营销腔,直接告诉读者"你应该有感觉"

原文档对照示例:

• ✅ "Zed renders every frame on the GPU. You'll notice the difference when you scroll."
• ❌ "Experience the revolutionary speed that will absolutely transform how you code!"

3.4 Developer Respect(对开发者的尊重)

评判问题:文案是否把读者当同行(peer),而不是待转化的潜在用户(prospect)?

分数	档位描述
5	同行间的对话;默认读者具备技术能力
4	有尊重,技术深度得当
3	略有居高临下或过度简化
2	说教式解释或强行热情
1	把读者当作需要被说服的门外汉消费者

原文档对照示例:

• ✅ "Tree-sitter provides incremental parsing, so syntax highlighting updates as you type."
• ❌ "Don't worry about the technical details — just know it's fast!"

这一维度的正面示例再次指向 Tree-sitter 增量解析这一真实机制,Zed 仓库的 language crate 确实直接依赖了多个 Tree-sitter 语法(如 crates/language/Cargo.toml 中的 tree-sitter-rust、tree-sitter-python、tree-sitter-typescript 等)。

3.5 Information Priority(信息优先级)

评判问题:最重要的信息是否放在最前面?

分数	档位描述
5	关键事实或变化先行,背景自然跟随
4	重要信息靠近开头,仅有少量铺垫
3	导语被埋,但仍可恢复
2	实质内容前有显著铺垫
1	关键信息被埋没或完全缺失

原文档对照示例:

• ✅ "Inline completions now stream token-by-token. Previously, you waited for the full response."
• ❌ "We've been thinking a lot about the developer experience, and after months of work, we're thrilled to share that..."

3.6 Specificity(具体性)

评判问题:论断是否具体、可测量?

分数	档位描述
5	每一条论断都具体且可验证
4	大多具体,偶有抽象
3	具体与模糊的论断混杂
2	以抽象收益描述为主
1	所有论断都含糊或不可验证

原文档对照示例:

• ✅ "Startup time under 100ms on M1 Macs"
• ❌ "Lightning-fast startup that respects your time"

3.7 Voice Consistency(语气一致性)

评判问题:全文语气是否统一?

分数	档位描述
5	从头到尾单一、连贯的音色
4	轻微语气波动,不造成干扰
3	章节之间漂移明显
2	多种音色相互竞争
1	语气断裂刺眼

原文档给出的检查项:casual 与 formal 之间、technical 与 marketing 之间、confident 与 hedging(含糊其辞)之间的切换。

3.8 Earned Claims(有据断言)

评判问题:断言是否有支撑、或至少可以被支撑?

分数	档位描述
5	每条论断都可以被演示或验证
4	论断合理且大体可验证
3	存在部分无支撑的断言
2	多处无法验证的最高级
1	大胆断言却毫无依据

原文档对照示例:

• ✅ "Built by the team behind Atom and Tree-sitter"
• ❌ "The most advanced editor ever created"

正面示例 "Built by the team behind Atom and Tree-sitter" 并非修辞:仓库根目录的 README.md 第一屏即写明 "a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter"。这正是 rubric 对"断言"的验收标准——能回到事实源。

四、快速评分模板与决策规则

rubric 末尾提供了可直接抄用的评分表(rubric.md#L153-L178):

| Criterion           | Score | Notes |
|---------------------|-------|-------|
| Technical Grounding |   /5  |       |
| Natural Syntax      |   /5  |       |
| Quiet Confidence    |   /5  |       |
| Developer Respect   |   /5  |       |
| Information Priority|   /5  |       |
| Specificity         |   /5  |       |
| Voice Consistency   |   /5  |       |
| Earned Claims       |   /5  |       |
| **TOTAL**           |  /40  |       |

Pass threshold: 32/40 (all criteria 4+)

配套的四条决策规则(Decision Rules):

• All 4+:文案通过,可做少量润色;
• Any 3:重写被标记的段落,重新评分;
• Any 2 or below:需要整体重构(full reconstruction);
• Multiple failures:推翻重来,换一种全新的写法。

这套规则把"改多少"也定量化了:单项 3 分只要求段落级改写,2 分以下升级为全文重构,多维度失败则直接放弃当前版本。它避免了评审中常见的"整体感觉不对"式模糊反馈。

五、rubric 如何落地:brand-writer 技能的两遍制工作流

rubric 的实际执行者是 SKILL.md 定义的 brand-writer 技能。其工作流分四个阶段:

阶段 1(Understand the Ask):澄清文案用途(首页、发布说明、文档、社媒)、受众、核心信息与约束。

阶段 2(Gather Context):加载三份参考文件——rubric.md(8 项评分标准)、taboo-phrases.md(待清除的模式)、voice-examples.md(改写模式与事实保留规则),并按需检索功能文档或代码中的技术细节。

阶段 3(Draft,两遍制)(SKILL.md#L122-L164):

• Pass 1 初稿 + 事实标记:写初稿时给所有事实性论断打 [FACT] 标签,覆盖技术规格、专有名词与产品名、版本号与日期、快捷键与 URL、归属引用与引语。示例:

  Zed is [FACT: written in Rust] with [FACT: GPU-accelerated rendering at 120fps]. Built by [FACT: the team behind Atom and Tree-sitter].

• Pass 2 诊断:把初稿对照 rubric 的全部 8 项标准逐条打分,同时扫描禁忌短语并记录行号;

• Pass 3 重构:对任何低于 4 分的标准或发现的禁忌短语,定位问题 → 重写对应段落 → 核对 [FACT] 标记是否存活 → 重新评分,循环直到全部 4+。

阶段 4(Validation):输出最终文案加记分卡(8 项分数与总分)、禁忌短语零命中声明、逐条事实核对清单(如 [FACT: Rust] ✓、[FACT: 120fps] ✓)。

技能还提供 --review 评审模式(SKILL.md#L211-L249):对既有文案先按 8 项标准打分,再逐行列出禁忌短语(如 Line 2: "revolutionary" (hype word)),给出"通过/不通过"结论,分数低于 4 的维度则套用 voice-examples.md 的改写模式重写。

评分校准来自 voice-examples.md:它收录 10 组 before/after 改写,每组都显式标注了维度分数,例如 "Before (Score: 2/5 Technical Grounding)" → "After (Score: 5/5)"、"Before (Score: 2/5 Developer Respect)"、"Before (Score: 1/5 Quiet Confidence)" 等。评审者可以拿这些样例做锚定,避免 3 分与 4 分之间打分漂移。

事实保留规则是重构时的硬约束:技术规格("120fps"、"8ms latency"、"Rust")、专有名词、版本号、快捷键、URL、归属引用、日期、引语共 8 类元素"Never Change"。重构完成后要与原稿的 [FACT] 标记做 diff 核对:删除的事实必须说明理由,改动过的事实一律标记为错误。这与 rubric 的 Technical Grounding、Specificity、Earned Claims 三个维度互为表里——语气可以重写,事实不能漂移。

六、rubric 的"正面示例可溯源":与仓库源码互证

rubric 及其配套文件反复用 Zed 自身的技术事实作为"好文案"的正例,而这些正例恰好都能在当前仓库中溯源:

文案正例(出自 rubric / voice-examples)	仓库内证据
"written in Rust"	整个仓库是一个 Cargo workspace,编辑器与 UI 框架均为 Rust 实现(Cargo.toml、crates/ 下 170+ 个 crate)
"GPU-accelerated rendering"	crates/gpui/Cargo.toml 中 description = "Zed's GPU-accelerated UI framework";crates/gpui/README.md 将 GPUI 描述为 "GPU accelerated, UI framework for Rust"
"Tree-sitter provides incremental parsing"	crates/language/Cargo.toml 依赖 tree-sitter-rust、tree-sitter-python、tree-sitter-typescript 等语法 crate
"Built by the team behind Atom and Tree-sitter"	README.md 首段 "from the creators of Atom and Tree-sitter"

从源码结构看,这种"示例即可验证"并非巧合,而是 rubric 设计思路的一部分:第 1 维(技术实证性)与第 8 维(有据断言)要求每条论断都能演示或验证,而 taboo-phrases.md 的 Detection Checklist 把它落成一句可执行的规则——"If you can't prove it or measure it, rewrite it"(无法证明或测量的,就重写)。需要说明:rubric 示例中的具体数值(120fps、8ms、100ms)是其作为文案样例的表述;实际撰写文案时,这些数字应当替换为当前版本可验证的真实数据,这正是该标准对写作者的要求。

七、rubric 在文档流水线中的位置

对 Zed 的文档贡献者而言,rubric 是质量检查单的最后一道闸门。CONVENTIONS.md 的 Quality Checklist 依次要求:frontmatter 含 title/description、主关键词自然出现、设置项"先 UI 后 JSON"、动作使用 {#action}/{#kb} 语法、无孤儿页面、通过 Prettier(80 字符宽度)检查,以及最后一条"Passes brand voice rubric"。

文档系统本身是 mdBook 加自定义预处理器 docs_preprocessor(见 docs/AGENTS.md),负责把 {#kb action}、{#action action} 展开为动态渲染的键位与命令引用。结构层(CONVENTIONS.md)保证"形式正确",rubric 保证"语气正确",两者叠加后才算一篇合格的 Zed 文档或发布文案。

八、实操速查:评审一篇文案的完整步骤

综合 rubric 本体与三个配套文件,对任意一段 Zed 风格文案的评审可以按以下顺序执行:

1. 自动失败项先行扫描(来自 taboo-phrases.md 的 Quick Reference):任何感叹号、"We're excited/thrilled"、"revolutionary"/"game-changing"、单段落内破折号出现 2 次以上、"It's not X, it's Y" 句式——命中任意一条直接不通过;
2. 8 维打分:按第三节的档位表逐项给 1–5 分,填进第四节的模板,计算总分;
3. 对照决策规则:全 4+ 通过;有 3 分则段落级重写;有 2 分以下整体重构;多项失败则推倒重来;
4. 事实核对:确认改写后所有 [FACT] 标记对应的事实仍然存在、未被改动;
5. 复评:对重写段落重新打分,直至 8 维全部 4+。

这套体系的本质,是把"品牌语气"从一种凭感觉的审美判断,拆解为 8 个可独立判定、可复评、可回归的标准,并用全维度门槛与决策规则保证执行不走样。对任何需要统一对外文本风格的开源项目,rubric.md 加 SKILL.md 两遍制、taboo-phrases 黑名单、voice-examples 校准样例这四件套,是一套可以直接参照移植的文案质检模板。