language-spec-author

编写可实现的语言规范

帮助作者将粗略的语言构想打磨成足够精确的规范，使得完全无法联系作者的开发者仅凭文档就能构建出符合规范的实现。产出是一份类似于 GraphQL 规范的规范，涵盖语法、语义、验证、执行和一致性要求，供其他开发者据此实现并实现互操作。

语言规范最难的不是写作，而是消除作者没意识到自己留下的歧义。两位实现者读到一句含糊的话，就可能产出两种不兼容的语言。因此，这项技能采用的方法是刨根问底：一次提出一个尖锐的问题，推荐一个默认方案，并拒绝记录任何经不起陌生人、边界情况和双实现者检验的答案。它附带脚手架脚本、完整性检查工具，以及介绍规范结构、形式化记法和访谈过程的参考文档。

适用场景

• 用户想要设计或形式化一种语言：DSL、查询语言、配置或数据格式、模板语言、表达式语言或线缆协议。
• 用户已有可运行的构想或原型，需要编写规范，供其他人据此实现，例如“为我的查询语言编写规范”或“形式化这种语法”。
• 用户需要语法、语言规范或可实现的定义，并希望理清词法、句法和语义结构，而不只是列举示例。
• 用户已有规范草案，但实现者不断提出疑问——需要找出并补齐其中的漏洞。

不要用于：编写 Python 语言提案（使用 python-pep-author）、内部公司 RFC 或设计文档（使用 dev-rfc / feature-spec），或记录已有固定定义的 API 接口。

前置条件

• 两个脚本需要 Bash + coreutils（awk、sed、grep、date）；macOS/Linux 默认已提供。起草或检查规范不需要任何语言运行时。
• 作者需能回答问题。这项技能以访谈为核心；它不能替语言作出决定，只能提取、检验并记录作者的决定。

工作流概览

访谈会逐步梳理每份可实现规范都必须描述的流程——源文本 → 词元 → 语法树 → 已验证的语法树 → 结果，并在每个阶段刨根问底。第 0 阶段决定哪些部分适用；并非每种语言都需要全部内容。

0. Frame ──► 1. Purpose &   ──► 2. Lexical   ──► 3. Syntactic
   the         principles        grammar          grammar
   language    (tie-breakers)    (chars→tokens)   (tokens→AST)
                                                       │
                                                       ▼
8. Conformance ◄─ 7. Output & ◄─ 6. Execution ◄─ 5. Validation ◄─ 4. Semantic model
   (MUST/SHOULD/    error format   (algorithms +    (static rules +   / type system
    MAY, normative) (result+errors) error model)    counter-examples) (optional)
        │
        ▼
   Scaffold (new-spec.sh) filled section by section ──► Lint (check-spec.sh) ──► Cold-read test

尽早搭建一次脚手架，让确定下来的答案都能写入结构化文档：

scripts/new-spec.sh --title "AcmeQL" --goal-symbol "Document" --editors "R. User <[email protected]>"

0. 界定语言

在编写任何语法之前，先确定这是什么类型的语言——查询语言、配置语言、命令式语言、声明式语言、协议还是模板语言——因为这决定了哪些规范结构适用。纯配置格式可能不需要执行部分；查询语言则需要全部八个部分。请先提出 references/interview-playbook.md 中的第 0 阶段问题，再阅读 references/spec-anatomy.md，了解这八个部分并标记适用范围。不适用的部分必须明确说明是有意省略，不能默默留下空白。

1. 目的与设计原则

明确语言的用途、非目标以及 3–5 条设计原则。原则是解决规范未预见歧义的决胜依据，因此要逐条追问：“这条原则能预先解决什么未来决策？”

2–3. 先定义词法，再定义句法

先定义词元（::，字符 → 词元），再定义结构（:，词元 → AST）。请先阅读 references/formal-notation.md——双冒号规则以及简写符号（?、+、but not、向前看）能让语法保持明确无歧义。作者最容易在这里留下未定义之处：空白字符是否有意义、是否区分大小写、注释语法、字面量的精确模式，以及最典型的漏洞——运算符优先级和结合性。要主动排查歧义；有歧义的语法无法实现。

4. 语义模型／类型系统（如适用）

如果该语言涉及带类型的实体、架构或资源，请将此模型与语法分开定义，并说明其约束和（可选的）自省方式。

5. 验证（静态语义）

列出文档能够解析、但仍然无效的所有情况。将每种情况写成一条具名规则，包含形式化规范、说明文字和一个反例（最小的无效文档）。反例同时也是测试用例，能够证明该规则可判定。

6. 执行（动态语义）

使用具名的函数式算法（formal-notation.md）来指定求值过程，不要用散文描述。明确作者常常略过的三个决策：求值顺序（仅在可观察时指定）、强制转换规则，尤其是错误模型——错误是中止执行、传播到某个边界，还是产生部分结果？每条算法路径都必须返回结果或抛出已定义的错误。

7. 输出与错误格式

说明可观察到的结果形状、错误对象形状（消息、位置、路径、扩展字段），以及至少一种具体序列化形式。错误格式规定不充分是互操作失败的主要原因——针对某一种实现编写的客户端，在另一种实现上会出错。

8. 一致性

采用 RFC 2119 关键字，声明规范性／非规范性内容的划分，并加入可观察等效条款，以便实现能够进行优化。模板的一致性部分已按 GraphQL 惯例预先填写。

收尾：先运行 lint，再冷读

运行 linter，找出结构缺失并修复所有 FAIL，然后进行真正的测试：

scripts/check-spec.sh acmeql-spec.md

check-spec.sh 会找出机械性缺漏（缺少章节、未解决的 TODO、缺少语法标记、缺少一致性关键字）。它无法判断语义是否正确——这需要通过冷读测试来检验：将草稿交给一位毫无背景的开发者。凡是他们需要问你的问题，都是缺陷；请将答案补充回文档中。

参考文件

文件	何时阅读
references/spec-anatomy.md	界定范围（阶段 0）并检查完整性时——可实现规范的八个部分、每部分要回答的问题，以及每部分的完成标准
references/formal-notation.md	编写语法（阶段 2–3）和语义（阶段 5–6）时——词法与句法标记、算法标记、数据集合、RFC 2119 关键字
references/interview-playbook.md	开展访谈时——严谨追问的方式、三项否决测试、规范不足的检测方法，以及各阶段的问题库

脚本

脚本	功能
scripts/new-spec.sh	根据模板创建规范草稿，并填写标题／日期／版本／目标符号。运行时添加 -h 可查看用法。
scripts/check-spec.sh	检查草稿中的结构缺漏（缺少章节、未解决的占位符、语法标记、一致性关键字、反例），结果为 PASS／WARN／FAIL；任何 FAIL 都会导致非零退出码。

脚手架脚本使用的模板位于 assets/templates/spec-template.md——如果你更愿意手动填写各章节，也可以直接复制该文件。

易忽略的问题

参见 gotchas.md。常见问题包括：作者只描述顺利路径，跳过错误模型；词法语法（::）与句法语法（:）混为一谈；到处都规定求值顺序，或者完全不规定（仅在可观察时指定）；以及看起来完整的规范仍然无法通过冷读测试。

相关技能

• radical-simplification——其 clarify-interview-one-at-a-time 技巧正是本技能用于语言设计的访谈方法。
• python-pep-author——向上游 Python 提交功能提案（这是治理流程，不是从零开始编写语言规范）。
• dev-rfc／feature-spec——内部 RFC、设计文档和功能规范（不是正式的语言定义）。