用途:把作者脑中的粗略语言想法,转化为零上下文开发者仅凭文档即可实现一致实现的规格,形如 GraphQL 规范,包含语法、语义、验证、执行与一致性。适用于设计或形式化 DSL、查询语言、配置/数据格式、模板语言、表达式语言或协议;也用于对已有原型或草稿补洞。不适用于撰写 Python PEP、公司内部 RFC/设计文档,或为已有固定定义的 API 写文档。
主要能力:以“逼问式”访谈推进,一次只问一个尖锐问题并给出默认建议,用陌生人测试、边界用例测试和双实现者测试拒绝模糊答案。按管线分阶段展开:0 定位语言类型;1 目的与设计原则(作为歧义裁决依据);2 词法语法(字符→token);3 句法语法(token→AST),重点排查空白、大小写、注释、字面量、运算符优先级与结合性;4 语义模型/类型系统(可选);5 静态验证规则,含反例;6 执行语义,以命名算法描述求值顺序、强制转换与错误模型;7 输出与错误格式;8 一致性(MUST/SHOULD/MAY)。
使用方式:先运行 scripts/new-spec.sh --title "AcmeQL" --goal-symbol "Document" --editors "R. User r@x.io" 生成结构化草稿,逐节填入答案;完成后运行 scripts/check-spec.sh acmeql-spec.md 做机械性检查。模板位于 assets/templates/spec-template.md,可手动复制填写。参考文件:references/spec-anatomy.md(八部分与完成标准)、references/formal-notation.md(词法与句法记号、算法记号、RFC 2119)、references/interview-playbook.md(访谈立场与问题库)。需 Bash 与 coreutils(awk、sed、grep、date),macOS/Linux 默认具备,无需语言运行时。linter 只查结构缺口,不判断语义正确;最终须做“冷读测试”,把开发者提出的每个问题视为缺陷并回填。常见问题:只写正常路径而漏掉错误模型、混淆 :: 与 : 语法、求值顺序该写处不写。相关技能:radical-simplification、python-pep-author、dev-rfc/feature-spec。