設計思想

なぜ Kumiki は今の形をしているのか。このページは設計理念の要約である。7 レイヤをどう使うかは Kumiki の考え方 に譲り、ここではそれらがなぜ存在するのかを扱う。

出発点

仮説は単純である: AI が書く前提でゼロから設計し直すなら、Hooks や JSX のような人間中心のイディオムはそのまま負債になる。Kumiki はこの仮説の検証から始まった。

なぜ React ではないのか

React は人間中心の最適点である。Hooks・Context・JSX は、人が読み書きして自然に感じるよう 20 年近く磨かれてきた慣用句だ。コードの書き手が AI に移ると、同じ機構が摩擦になる:

摩擦点	AI にとってのコスト
構文オーバーヘッド	JSX は閉じタグ・キャメル属性・式埋め込みでトークンが嵩む
暗黙の副作用	useEffect の依存配列、stale closure、cleanup 忘れ
順序依存ルール	Hooks の呼び出し順、条件分岐内・リスト内の禁止
暗黙スコープ	Provider 階層、子孫から不可視に解決される Context
非局所的レンダリング	親の再レンダーが子に波及し、memo での抑制が複雑さを足す

共通するパターン: これらはどれも AI が書く分には書けるが、AI が直す・並列で触るとなると急激に難しくなる。バグの原因がプログラムテキストの外にあるとき、AI は履歴をコンテキスト窓に全部詰めないと推論できない。

Kumiki はこの摩擦を規約ではなく構造で消す。

設計要件

1. トークン効率 — 同じ UI を React より少ないトークンで。
2. 副作用の静的追跡可能性 — どの副作用がどの状態に依存しどこから発火するか、構文だけから自明であること。
3. アーキテクチャの予測可能性 — バグは局所化し、エラーは機械可読なコードで返ること。
4. 並列編集耐性 — 数十のエージェントが同時に編集してもセマンティックに壊れないこと。
5. 可読性の放棄を許容 — 人間が読んで快適かは二次目標。一次目標は AI が正確に書け・直せること。

要件 1 と（部分的に）2–4 は願望ではなく、継続的に実測している。ベンチマーク を参照。

4 つの独立案が収束した先

Kumiki は 1 つの設計から始まっていない。互いを参照しない 4 つの独立案を、それぞれ別のモデル支援探索で得るところから始まった。

批判的に比較すると、表面の構文がまったく違うのに、4 案すべてが同じ 4 つの核に収束していた:

1. 副作用は明示 descriptor — 関数呼び出しではなく純粋な値。
2. ローカル状態の禁止 / 最小化 — 全状態が静的に位置特定可能。
3. source ≠ runtime — IR とコンパイルの必須化。
4. append-only causal log — デバッグ・リプレイ・監査を一つの基盤に統合。

残った論点はソース表現の物理形式だけだった。Kumiki はそのハイブリッドである: 7 レイヤ強制分離と名前付き slot（Pyramid）、capability 付き effect descriptor（IR+Actor / Pyramid）、episode log の考え方（Loom）、参照整合性を検査された op による並列編集（Nexus）——そして各案の既知の弱点は別の案の強みで塞ぐ（例: ネストは tile 内のみ許容することで、1 行 1 宣言の形が括弧地獄にもアセンブリ退化にも落ちない）。

先行研究からのレッスン

試み	取り入れた	避けた
Elm	完全な副作用分離、Result/Option	ボイラープレートの膨張、ローカル状態全面禁止の硬直さ
Unison	content-addressable な定義	テキスト/Git エコシステムからの分断
SolidJS	fine-grained reactivity、コンパイル時依存解析	隠れた追跡範囲、シグナルの stale 問題
Hazel / Subtext	typed holes、構文エラーゼロ	入力摩擦
Dark	trace 駆動の開発	エコシステムロックイン
Datomic	append-only fact log	高頻度更新への不適合

非目標

Kumiki は次のものを意図的に目指さない:

• 既存 React コードの段階移行 — 互換性ゼロでよい。新規アプリ専用。
• 人間が快適にフルスクラッチで書くこと — 人間も書けるが、そのために最適化しない。
• マクロ・プラグイン・言語拡張 — AI の学習対象を単一かつ閉じたまま保つ。
• 動的型 — すべて静的。
• 複数レンダリングターゲット — DOM のみ。

接続は境界で。言語に穴を開けない

上の非目標は裏返すと積極的な原則になる: interop のために言語そのものに穴を開けない。既存 JS エコシステムとの接続は、すべて言語の外側にある 3 つの境界で行う:

• Inbound — 宣言済み capability の実装をホスト側が注入する（mount(app, target, { providers })）。http.* などの標準 capability も同じ仕組みで上書き可能。標準 capability を参照。
• Outbound — Kumiki アプリは Web Component（defineKumikiElement）として任意のページに埋め込める。ランタイム を参照。
• Build — @kumikijs/vite で任意の Vite プロジェクトから import App from "./app.kumiki" でき、provider 用の TS 型も生成される。

ホスト固有のものが .kumiki に漏れ込めないからこそ、同じファイルがどこでも同じ意味を持つ。

運用モデルも設計の一部

このリポジトリは「見ればすべての疑問が解決する」を規則として運用する。質問やバグには散文ではなく動く example とテストの追加で答える。仕様は normative であり、すべての example は CI で compile・build・smoke を通らなければならない。機械を読者とする言語には、同じ性質を持つドキュメントが要る。