スクリプトから複雑なCLIツールを動かし、成功をJSONのレポートで確かめる

## CLIの成功を、進み具合の表示ではなく決まった形のデータで判断する スクリプト、パイプライン、コーディングエージェントから複雑なコマンドラインツールを操作する場合、CLIを対話シェルではなく、バージョン管理された機械向けインターフェースとして扱う。計画、実行、検証を分離し、各段階が構造化データを受け取り、次の段階で検証できる証拠を生成するようにする。 - 人間向けの進捗表示を解析して、処理の成否を判断してはならない。 - 対応タスク、成果物の種類、ライセンス要件を記憶から推測してはならない。 - ツールのバージョン、解決後の実行時設定、要求した範囲、生成された成果物を記録する。 - 必須の構造化証拠が存在しない、または整合しない場合は、安全側で失敗として扱う。 ## 動かす前に、ツールのタスクとクラスの一覧を確かめる 負荷の高いジョブを組み立てる前に、ツールの軽量な情報取得コマンドまたはレジストリコマンドを使う。メインCLIの検証に使われるものと同じレジストリから生成されたJSON表示を優先する。ソースから転記した一覧やハードコードされた名前は、インストール済みバージョンとずれる可能性があるためである。 機能確認では、次の情報を得られるようにする。 - 利用可能なタスクと各タスクの入力形式 - 各タスクでライセンスまたは利用資格が必要か - クラス絞り込みで受理される、インデックスとクラス名の正確な対応 - インストール済みツールのバージョンとタスク固有の制約 重量のある推論依存関係を読み込まず、アクセラレーターを初期化せず、モデル重みを取得せず、ローカル状態も変更しない確認経路を優先する。レジストリ全体が不要な場合は、問い合わせを1つのタスクまたはクラス表示に限定する。 ## 入力・保存先・設定を全部書いて、同じ実行をやり直せるようにする 入力、保存先、タスク、デバイスポリシー、任意のクラス部分集合、成果物の表現形式、レポート保存先を、実行ごとに明示する。ボリュームファイル、順序付きスライスのディレクトリ、スライスのアーカイブなど、文書化された入力形式だけを受け付け、選んだ成果物形式に対して保存先が妥当か検証する。 実行前に次を確認する。 1. 要求したタスクとクラスが、現在の機能レジストリに存在する。 2. 入力形式が対応対象であり、保存先の解釈が一意である。 3. 利用資格が必要なタスクでは、開始前に資格を解決している。 4. デバイスと性能モードを意図的に選んでいる。 5. 機械可読の実行レポート用に、一意の保存先を確保している。 古い成果物を今回の結果と誤認する可能性がある場合は、既存の成果物ディレクトリを再利用してはならない。解決後のコマンド引数を実行証拠とともに保存する。 ## デバイスと高速モードを選び、ライセンスが要るタスクは先に確かめる デバイス選択と速度オプションを再現性契約の一部として扱う。要求したデバイスだけでなく、実際に選ばれたデバイスを記録する。アクセラレーションが利用できずCPUへ切り替わると、実行時間が大きく変わる場合があるためである。 リソースが限られている場合は、文書化された制御で負荷を下げる。 - 精度との交換条件を許容できる場合に限り、低解像度の高速モードを使う。 - 後続処理に必要なクラスだけを要求する。 - 複数のデバイスがある場合は、特定のアクセラレーター番号を指定する。 - 必要な場合は、対応するプラットフォーム用バックエンドを明示的に選ぶ。 成果物の品質や処理範囲が変わる高速モードまたは絞り込みモードへ、黙って切り替えてはならない。ライセンスが必要なタスクでは、有効な認可が設定済みでない限り、推論開始前に停止する。 ## JSONのレポートと、そこに書かれた全部のファイルを確かめる 正常完了後、CLIに構造化レポートを書かせる。レポートは自動化処理へ渡す正式な引き継ぎ成果物であり、次を含める。 - ツール、実行環境、フレームワーク、依存関係の各バージョン - タスク、入力モダリティ、ライセンス要件 - 解決後のデバイスと性能フラグ - 正規化された入力場所と保存場所 - 要求したクラス部分集合と、最終的なインデックスとクラス名の対応 - 実経過時間と、実際に生成された成果物ファイルの正確な一覧 レポートが存在し、JSONとして解析でき、期待したタスクを示し、次の段階で必要な全成果物を列挙していることを確認する。その後、列挙された各ファイルが存在することも確認する。クラスごとの体積、強度、ボクセル数、分散、極値、重心、境界ボックスには専用の統計結果を使い、ファイル名や進捗表示から推定してはならない。 ## 終了コードで失敗を分け、新しい保存先でやり直す 任意成果物を読む前に、プロセスの終了状態を解釈する。正常完了、実行時失敗、引数または使用方法の失敗を区別し、無効なコマンドをそのまま再試行しないようにする。 - 正常完了時は、レポートと、そこで宣言された成果物ファイルを検証する。 - 実行時失敗では診断用の標準エラーを保存し、認可不足、リソース不足、入力破損、未処理のツールエラーなどに分類する。 - 引数の失敗では、再試行前にタスク、入力、保存先、またはオプション一式を修正する。 - 通常時は静音モードで不要な表示を減らし、追加の診断情報が必要な場合だけデバッグモードを使う。 部分的なファイル、進捗メッセージ、空の成果物ディレクトリを成功とみなしてはならない。再試行では、新しい保存先、または失敗した試行の成果物を除いた保存先を使い、前回の成果物が今回の検証条件を満たさないようにする。 ## 公開APIから呼び、レポートのファイル一覧で次の処理につなぐ プロセス内実行が必要な場合は、正式に対応する上位プログラミングAPIを使う。ただし、CLIの手順と同じく、タスク、入力、保存先、検証の契約を明示する。計画と検証には、推論実行環境全体を読み込まずにタスクとクラスを列挙できる軽量レジストリモジュールを優先する。 オーケストレーションを実装内部から切り離す。正式なレジストリから機能を確認し、文書化されたCLIまたはAPIで実行し、構造化レポートの成果物一覧から後続処理をつなぐ。これにより、標準出力の壊れやすい解析や機能一覧の重複を避けながら、バージョン変更後も自動化を維持できる。