CONCEPT RUNTIME / HANDS-ON

実装する前に、要件を動かす。

このページでは、Concept Runtimeを説明として読むのではなく、自然言語の要求をConcept Modelへ変換し、検証し、成果物へ渡すところまで実際に操作します。

DESIGN BEFORE CODE

コードを書く前に、誰が何をし、どこで止まるかを確かめる。

LLMは候補を作りますが、仕様を確定しません。 人が確認したConcept Modelだけが、検証と成果物生成の正本になります。

最初に理解すること

Concept Runtimeは、自然言語から本番アプリケーションを自動完成させる機能ではありません。 実装を始める前に、要件・データフロー・権限・状態・検証条件をConcept Modelとして動かす開発環境です。

LLMの出力は候補です。 未解決のDecisionや検査findingが残る場合、Concept Runtimeは推測で埋めず、保存・実行・成果物生成の前に止まります。 識別子が重複した候補も、Runtimeが先頭のActor・Flow・Ruleなどを暗黙に選ばないよう保存前に止まります。 同じ要求を再実行しても候補のModel IDやRule数は変わり得るため、毎回表示された内容を確認してください。

一つの要求が通る流れ

0. CLIを準備する

公開Gatewayで試す場合は、管理者から受け取ったトークンでログインします。 すでにCLIを使える場合は、導入ガイドを飛ばして構いません。

statusは接続先のreadinessを確認し、whoamiは認証済みアカウントを確認します。 Concept Runtimeの設計DBはローカルSQLiteに保存され、GatewayのKnowledge Cardへ自動共有されません。

1. ローカルデモで停止とTraceを確認する

最初はLLMを使わない明示的なデモModelで、validate、decide、simulateの流れを確認します。--demoはローカルSQLiteへ明示的に保存する入口であり、自然言語Runの保存前dry-runとは別の操作です。 実験用のDBを明示するため、既存の作業DBと分けたディレクトリを使います。

ここでは、権限や所有者に関する未決定事項が表示されます。 これは失敗ではなく、Modelを確定する前に人へ返された設計上の問いです。 このvalidateは未解決事項があるため終了コード1になりますが、Tutorialで意図した停止です。 シェルに非ゼロ終了が表示されても、次のDecision適用へ進みます。

Decisionを1つずつ確定する

デモModelでは、表示されたDecision IDを使ってYes / Noを適用します。 IDはModelごとに確認し、表示と異なるIDを推測して入力しないでください。

d1〜d3を適用した後も、デモModelにはarticle.updateの権限とArticle / Commentの所有者が未解決として残ります。 これはseedが、確認質問だけでなく「質問を作れない不足」も見せるための設計だからです。 ここでvalidateが完全に通らず終了コード1になること自体が、実装前に止めるべき設計判断です。simulateはLLMを呼ばず、Flow解決、権限評価、状態遷移、Invariantチェックを決定論的に実行します。 このデモでは未定義のarticle.updateがwarningとしてTraceに残ります。

2本のsimulateは終了コード0で、Traceのstatus=completedになります。 未定義権限のwarningが残っていても、--fail-on-warningを付けていないため実行自体は完了します。

2. 同じModelを開発Viewへ渡す

Modelが正本です。 Excel、PDF、Markdown、コードはそれぞれレビュー、共有、編集、実装の入口であり、Modelそのものを置き換えません。export、notebook、chartは未解決findingを含むModelの設計Viewも出力できますが、renderは検証ゲートを通過するまでコード骨格を生成しません。

renderはtypes・permissions・MODELのコード骨格を生成します。 本番アプリケーションの業務実装や外部作用を自動で完成させるものではありません。 上のデモでは未解決findingが残るため、renderが停止することを確認してください。exportが生成したレビュー用design.mdを残すため、編集用のnotebookは別ファイルへ出力します。 Notebookを編集してModelへ反映する場合は、編集後にmurasame concept apply ... --yesを明示的に実行します。 コード骨格まで進める場合は、notebookでModel JSONを開き、所有者と権限を自分の業務判断として明示してからapply --yes、validate、renderの順に進めます。 所有者を推測して埋めるのではなく、チームで決めたActorを入力してください。 PDFにはChromeまたはChromiumが必要です。 同じModel・版数・source hashのまま同じ出力先へ形式を分けてexportしても、既存の形式はManifestへ引き継がれます。 PDF生成だけが失敗しても、PDF以外の成果物は保存され、CLIが再開コマンドを案内します。

VS Codeで同じModelを観測する

CLIで出力したconcept.jsonは、開発者向けの読み取り専用Visual Frontendでも確認できます。 リポジトリをチェックアウトした環境で拡張開発ホストを起動し、先ほど生成したJSONを選択します。 ViewerはConcept DBやネットワークへ接続せず、Modelに存在するActor、Entity、State Machine、Rule、DecisionとFlowのstep順だけを表示します。これはViewer自身の境界であり、CLIのConcept Runtimeが承認後にModelや指定出力先へ書き込むこととは分離されています。

リポジトリを持たない環境では、公開VSIXを入れてから通常のVS Codeで作業フォルダを開けます。公開VSIXを取得し、次のコマンドを実行してください。

codeコマンドを使えない場合は、VS CodeのExtensionsビュー（Ctrl+Shift+X）を開き、... → Install from VSIX...から取得したVSIXを指定してください。

CLIやリポジトリを先に準備せずViewerだけ試す場合は、公開Demo Modelを取得できます。公開Demo JSONを確認し、保存したファイルをVS Codeで開いてください。

Flowを切り替えてもActor・Entity・Precondition・transitionのfrom → to・step説明が残ること、 State MachineまたはEntityを選ぶとInspectorでstates / transitions / attributesを確認できることを見ます。 JSONを保存した後にRefreshすると再読込されますが、ViewerからConcept Modelを編集・保存することはありません。

3. 自分の要求を自然言語で試す

ここからがConcept Runtimeの中心です。 次の備品貸出要求を、最初は--dry-runで実行してください。--dry-run中はModel保存、Simulation、Renderer、成果物生成を行いません。

以後のコマンドは同じ端末セッションで実行し、直前に設定したinventory_requirementを再利用します。 初回生成でModel IDを固定するため--new --id inventory-hands-onを指定しています。 既存Modelを改訂するときは--newを外します。--jsonではPlan JSONがstdout、進捗と人向けの停止案内がstderrへ分かれます。run.logを確認すると、なぜ止まったかと次の要求修正が読めます。 未回答Decisionなら終了コード2、意味上のfindingなら終了コード1になる場合があります。 どちらもこの段階では保存されていないため、まずJSONとログを読みます。

次の例はBash / Zsh向けです。 stderrを画面へ表示しながらrun.logにも保存するため、生成中の経過秒数を見失いません。

jqはJSONを見やすくするための任意の補助ツールです。 手元にない場合は、2つのjq行を飛ばしてcat concept-lab/inventory/plan.jsonで確認できます。

murasame concept listにinventory-hands-onが出なければ、保存前ゲートが機能しています。 既存のModel一覧が表示される場合は、今回指定したMURASAME_CONCEPT_DBが別のDBを指していないか確認します。

既存Modelを自然言語で改訂するときは--newを外します。既存のActor・Entity・State Machine・Transition・Flow、属性、開始前提、Flow stepの欠落や主要な意味変更は保存前に止まり、説明文の変更と新規要素の追加だけが候補として許容されます。意図的な既存仕様の変更は、notebook / applyで明示してください。

4. 質問へ答え、もう一度dry-runする

JSONのopenDecisionsには、Yes / NoでModelの意味が変わる確認事項が入ります。 推奨値があるDecisionだけを自動適用するなら、--dry-run --yesを使えます。 この組み合わせの--yesは、保存や外部作用の承認ではなく、このdry-run内で推奨回答を適用する指定です。

推奨値のない質問には、表示された最新のDecision IDを使って明示回答します。 LLMは再実行時にModelを作り直すため、Decision IDが変わることがあります。 IDが変わったら、前のIDを使い回さず、最新PlanのIDへ置き換えてください。openDecisionsが0件なら、明示回答のコマンドは飛ばして次へ進みます。

invalid-invariant、ambiguous-permission、no-op-decision、参照切れ、状態やFlowの不整合は、--answerだけでは解消しません。 その場合は、ログの指示に沿って要求へ役割・対象・状態・遷移・条件を追記し、元の要求を修正して再実行します。 所有者はentity.ownerActorId、履歴や時間関係は現行の状態式だけでは表現できないため、Concept Runtimeは意味を発明して先へ進みません。

5. 人が確認してから保存・実行する

dry-runのPlan JSONとログを読み、役割、Entity、状態、Flow、Rule、Decisionに納得できた場合だけ、最終承認を付けて再実行します。 非TTYで保存・実行するには--yesが必要です。 この--yesは推奨回答の適用に加えて、Model保存・Simulation・成果物生成へ進む最終承認です。

直前のdry-runで確認した要求文をそのまま使います。 推奨値のないDecisionへ回答した場合だけ、最終コマンドへ--answer 最新のdecisionId=yes|noを追加します。 未解決findingが残る場合や、推奨のない質問へ回答していない場合は、--yesを付けても保存されません。

6. ExcelからProposal-firstでレビューする

保存済みModelからExcelを出力したら、チームでDecisionsシートのanswer列だけを編集します。 他のシートや読み取り専用列を直接書き換えても、正本のModelは変わりません。

reviewはExcelの差分をProposalへ変換するだけです。review-apply --yesで明示承認して初めてConcept Modelの新しい版になります。 この境界が、レビュー中の表計算をそのまま業務仕様へ書き込まないための安全弁です。

7. Simulationと形式検証を使い分ける

simulateは、指定したScenarioを一つのFlowとして実行し、どのStepで状態が変わったか、どの権限を評価したか、どこで警告・停止したかをTraceへ残します。verifyは状態機械をQuintへ射影し、Invariantと反例を形式検証します。 どちらも自然言語の意味を推測する機能ではありません。

Quintが端末にない場合、verifyはInvariant違反とは別の実行環境エラーとして止まります。 その場合はQuintを導入するかMURASAME_QUINT_BINを指定し、自然言語Runでは必要に応じて--no-verifyを使います。

このページで見つけてほしい限界

Concept Runtimeの価値は、すべての要求を自動で通すことではありません。 現在のschemaで決定論的に検証できるものと、まだ意味を表現できないものを分け、実装前に人へ返すことです。

ここで停止したfindingを自動で消す、LLM候補を勝手に修正する、未確定Draftを共有DBへ保存する、といった近道は現在の契約に含めていません。 Concept Runtimeは、設計の曖昧さを消すのではなく、どこにあるかを見える形で残します。

次に試す課題

止まったときの確認

LLM生成中は数十秒から数分かかる場合があります。 CLIは経過秒数を表示し、Ctrl-Cで中断できます。 生成中は未保存なので、まず中断して要求を直す判断も安全です。