はじめに

Rune は、エージェントの時代に向けて設計された、エージェントネイティブな CLI フレームワークです。Rune は、次のコンセプトのもと開発されています:

Rune は、人間にとってはもちろんのこと、エージェントにとっても理解しやすい CLI フレームワークでなければならない
Rune によって作成された CLI もまた、人間とエージェント双方にとって扱いやすいものとなるべきである

Rune の特徴

ファイルベースのコマンドルーティング

Rune では src/commands 以下のファイル構造から CLI のコマンドツリーが決まります。index.ts はそのディレクトリをコマンドとして実行可能にし、同じディレクトリに置かれたルーティング対象の .ts ファイルは、そのディレクトリ配下の兄弟サブコマンドになります。

マニフェストを手で管理する必要はなく、ディレクトリを見るだけで CLI 全体の構造を把握できます。_ で始まるファイルやディレクトリ、およびコロケーションされた .test.ts / .spec.ts ファイルはルーティング対象外となるため、関連する実装やテストをコマンドの近くに置けます。実行時には一致したコマンドモジュールだけがロードされるため、不要な読み込みも発生しません。

型安全なコマンド定義

defineCommand() に渡した定義から、オプションや引数の型が推論されます。手動で複雑な型注釈を書く必要はありません。

必須引数と任意引数の順序違反、短縮オプション名の重複、--no-<name> と衝突するオプション名などは、定義時点で検出されます。ハイフンを含む名前のフィールドは camelCase でもアクセスでき、型補完も維持されます。

Standard Schema サポート

コマンドのオプションや引数は、Zod、Valibot、ArkType など Standard Schema に準拠した任意のスキーマライブラリでバリデーションできます。Rune はバリデータを Standard Schema の規約経由で呼び出すため、特定のライブラリにロックインされることなく、プロジェクトに最適なスキーマライブラリを自由に選択できます。

テストユーティリティ

runCommand() を使うと、子プロセスを起動せずにコマンドをインプロセスでテストできます。引数のパース、型変換、バリデーション、デフォルト値の適用を含むコマンド実行をそのまま検証できます。戻り値の exitCode、stdout、stderr、error、型付けされた output を直接アサートできるため、高速かつ確実なコマンドのテストを書けます。

JSON 出力

defineCommand() に json: true を指定すると、そのコマンドは組み込みの --json フラグを受け付けます。--json を付けて実行すると、コマンドの戻り値が構造化された JSON として標準出力に書き出されます。

このとき output.log() による人間向けの stdout は自動的に抑制されます。一方で output.error() と JSON 形式のエラーペイロードは stderr に出力されるため、診断メッセージは失われません。--json を付けなければ通常のテキスト CLI として振る舞うため、ひとつの実装で人間向けと機械向けの両方に対応できます。CLI が AI エージェントから呼び出されたときは、--json が明示されていなくても JSON モードが自動で有効になり、エージェントはデフォルトで構造化された出力を受け取れます。

ストリーミング形式の構造化出力には jsonl: true を使用できます。yield された各レコードは JSON Lines として 1 行ずつシリアライズされ、runCommand() では result.output.records として取得できます。

自動ヘルプ生成

description、options、args、examples などの定義から、--help の出力が自動生成されます。引数の説明、プリミティブのデフォルト値、ショートオプション、否定フラグ、サブコマンド一覧まで反映されるため、ヘルプを別管理する必要がありません。

より細かく制御したい場合は、defineCommand({ help }) によるコマンド単位のカスタマイズや、defineConfig() を使った rune.config.ts によるプロジェクト全体のカスタマイズを利用できます。どちらも renderDefaultHelp() を土台として拡張できます。

構造化されたエラー

CommandError を使うと、kind、message、hint、details をもつ構造化されたエラーを定義できます。通常実行時には人間向けに読みやすく表示され、--json モードでは機械可読なエラー情報として stderr に出力されます。

エージェントスキル

Rune は公式のエージェントスキルを提供しています。エージェントスキルとは、AI エージェントが必要に応じて読み込める手順書やルールをまとめたオープンフォーマットです。複数の AI 開発ツールがこの形式をサポートしています。

Rune のスキルをプロジェクトに導入すると、エージェントはファイルベースルーティングの規約、defineCommand() の使い方、テストの書き方といった Rune 固有の知識をオンデマンドに参照できるようになります。これにより、エージェントがより正確かつ効率的に Rune プロジェクトで作業できます。