language-spec-author

実装可能な言語仕様を作成する

大まかな言語のアイデアから、作者にまったくアクセスできない開発者が文書だけを基に適合する実装を構築できるほど正確な仕様へと、作者を導きます。出力するのは、GraphQL specificationのような形式の仕様です。文法、意味論、検証、実行、適合性を定め、ほかの開発者が実装して相互運用できるようにします。

言語仕様で難しいのは文章を書くことではありません。作者自身が見落としている曖昧さを取り除くことです。曖昧な文を読んだ2人の実装者は、互換性のない言語を作ってしまいます。そのため、このスキルの手法は徹底的な質問です。一度に鋭い質問を1つ投げ、既定値を提案し、第三者・エッジケース・実装者間の解釈一致のテストに通らない回答は記録しません。骨組みスクリプト、完全性リンター、仕様の構成、形式的記法、インタビューに関するリファレンスドキュメントが含まれています。

適用する場合

• ユーザーが言語を設計または形式化したい場合：DSL、クエリ言語、設定形式やデータ形式、テンプレート言語、式言語、ワイヤープロトコルなど。
• ユーザーに動作するアイデアやプロトタイプがあり、ほかの人が実装できる文書仕様が必要な場合：「自分のクエリ言語の仕様を作って」「この構文を形式化して」など。
• ユーザーが文法、言語仕様、または実装可能な定義を求めており、単なる例ではなく、字句・構文・意味の構造を明確にする必要がある場合。
• ユーザーの仕様案について、実装者から何度も質問されている場合。抜け穴を見つけて埋める必要があります。

次の場合には使用しないでください：Python 言語の提案を作成する場合（python-pep-authorを使用）、社内 RFC や設計ドキュメントを作成する場合（dev-rfc / feature-specを使用）、または定義がすでに確定している API の仕様を文書化する場合。

前提条件

• 2つのスクリプトを実行するための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. 言語の枠組みを定める

文法に取りかかる前に、この言語がクエリ、設定、命令型、宣言型、プロトコル、テンプレートのどれに当たるかを明確にします。これによって、どの構成要素が必要かが決まります。純粋な設定形式には実行の節が不要な場合がありますが、クエリ言語には8つすべてが必要です。references/interview-playbook.mdにあるフェーズ0の質問を行い、references/spec-anatomy.mdを読んで8つの構成要素を確認し、どれが対象となるかを明示してください。対象外の部分は、黙って省略せず、明示的に判断を記載する必要があります。

1. 目的と設計原則

目的、対象外とすること、3～5個の設計原則を明確にします。原則は、仕様で想定していなかった曖昧さを解決する判断基準です。そのため、各原則について「この原則によって、将来のどの判断をあらかじめ決められますか？」と徹底的に問いかけます。

2～3. 字句文法、次に構文文法

構造（:, トークン → AST）より先に、トークン（::, 文字 → トークン）を定義します。まずreferences/formal-notation.mdを読んでください。コロン2つの使い分けと、省略記法（?、+、but not、先読み）は、文法の曖昧さを防ぐために重要です。作者による仕様不足が最も多いのはこの部分です。空白の意味、大文字と小文字の区別、コメント構文、リテラルの正確なパターン、そして典型的な抜け穴である演算子の優先順位と結合規則を明確にします。曖昧さを積極的に探してください。曖昧な文法は実装できません。

4. 意味モデル／型システム（該当する場合）

その言語が型付きエンティティ、スキーマ、またはリソースを扱う場合は、制約や（任意で）イントロスペクションとともに、そのモデルを文法とは分けて定義します。

5. 検証（静的意味論）

文書として解析できても無効となるあらゆる条件を列挙します。それぞれを、形式的な仕様、説明、反例（最小の無効な文書）を含む名前付きルールとして記述します。反例はテストケースも兼ね、そのルールが判定可能であることを示します。

6. 実行（動的意味論）

評価は文章ではなく、名前付きの関数形式アルゴリズム（formal-notation.md）で規定します。執筆者が省略しがちな3つの判断、すなわち評価順序（観測可能な場合のみ）、型強制のルール、そして何よりエラーモデルを明確にします。エラーは処理を中断するのか、境界まで伝播するのか、それとも部分的な結果を返すのかを定めます。各アルゴリズムのすべての経路で、定義済みのエラーを返すか送出する必要があります。

7. 出力とエラー形式

観測可能な結果の形、エラーオブジェクトの形（メッセージ、位置、パス、拡張情報）、および具体的なシリアライズ例を少なくとも1つ示します。エラー形式の仕様が不十分であることは、相互運用性における大きな問題です。1つの実装を前提に書かれたクライアントが、別の実装では動作しなくなります。

8. 適合性

RFC 2119 のキーワードを採用し、規範的な内容と非規範的な内容を明示して、観測上同等であれば実装を最適化できる旨の条項を含めます。テンプレートの適合性セクションには、GraphQL の規約に沿った内容があらかじめ記入されています。

仕上げ：lint を実行してから、初見で読み直す

リンターを実行して構造上の抜けを見つけ、すべての FAIL を修正してから、本当のテストを行います。

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

check-spec.sh は、機械的に検出できる抜け（セクションの欠落、未解決の TODO、文法表記の欠落、適合性キーワードの欠落）を見つけます。PASS／WARN／FAIL を出力します。ただし、意味論が正しいかどうかは判定できません。それを確かめるのが初見読みテストです。草案を、事情を知らない開発者に渡してください。その人があなたに尋ねなければならないことは、すべて不備です。回答を文書に反映しましょう。

参考ファイル

ファイル	読むタイミング
references/spec-anatomy.md	スコープを定めるとき（フェーズ 0）と網羅性を確認するとき — 実装可能な仕様を構成する8つの要素、それぞれが答える問い、各要素の完了基準
references/formal-notation.md	文法（フェーズ 2～3）と意味論（フェーズ 5～6）を記述するとき — 字句表記と構文表記の違い、アルゴリズム表記、データコレクション、RFC 2119 のキーワード
references/interview-playbook.md	インタビューを進めるとき — 厳しく問いただす姿勢、3つの却下基準、仕様不足の検出方法、フェーズごとの質問集

スクリプト

スクリプト	機能
scripts/new-spec.sh	テンプレートから仕様の草案を作成し、タイトル／日付／バージョン／goal-symbol を入力します。使い方は -h を指定して実行してください。
scripts/check-spec.sh	草案の構造上の抜け（セクションの欠落、未解決のプレースホルダー、文法表記、適合性キーワード、反例）をチェックし、PASS／WARN／FAIL を出力します。FAIL が1つでもある場合は、ゼロ以外の終了コードを返します。

スキャフォールドで使用するテンプレートは assets/templates/spec-template.md にあります。セクションを手作業で埋める場合は、直接コピーしてください。

注意点

gotchas.md を参照してください。よくある問題は、執筆者が正常系の処理を説明する一方で、エラーモデルを省略してしまうこと、字句文法（::）と構文文法（:）を混同すること、評価順序をどこにでも規定するか、まったく規定しないこと（観測可能な場合のみ規定してください）、そして一見完全に見える仕様でも初見読みテストに失敗することです。

関連スキル

• radical-simplification — その clarify-interview-one-at-a-time の手法は、このスキルが言語設計に適用するインタビューの進め方です。
• python-pep-author — Python 本体への機能提案向けです（ガバナンスプロセスであり、一から言語仕様を作るものではありません）。
• dev-rfc / feature-spec — 社内 RFC、設計ドキュメント、機能仕様向けです（形式的な言語定義ではありません）。