実際のコマンドとフラグから、AIエージェント向けのコマンドスキーマを作る

## 生成ファイルは直さず、レジストリとジェネレーターを直す リポジトリのガイダンスは、その適用範囲にあるファイルの契約として扱う。無関係な作業を維持し、変更したすべてのソースファイルにその言語のフォーマッターを適用し、要求された動作に必要な所有元の入力だけを最小限変更する。 編集前に権威ある入力を特定する。レビュー済みコマンドレジストリは、安定したコマンド識別情報、プライマリパス、エイリアス、ナビゲーションを所有する。実行可能なコマンドツリーは、パスが存在して実行可能か、どのフラグを受け付けるかを所有する。生成されたカタログとエージェントメタデータは出力物であり、編集面ではない。正本となる入力とジェネレーターを変更してから再生成する。 変更を対象とする、リポジトリ所定のビルド、全テスト、生成、ドリフト検査、ポリシー検査、範囲を絞ったコマンドテストを実行する。生成された差分を確認し、無関係な書き換えを退ける。 ## スキーマを一方向で作り、各コマンドを1回だけ仕様にまとめる スキーマ解決を一方向に保つ。 1. 実際に実行可能なコマンドツリーとフラグを構築する。 2. バインド前に、レビュー済み識別情報レジストリとレビュー済みメタデータオーバーレイを組み合わせる。 3. パラメーターの型、マッピング、必須状態、既定値、パラメーター間の制約を解決する。 4. 宣言済みのソース優先順位に従い、エージェント選択、安全性、インターフェース、ランタイムゲートの意味を解決する。 5. 各コマンドをちょうど1回だけ、1つの型付きツール仕様とインデックスへバインドする。 6. その型付き正本だけから、カタログ、完全エクスポート、要約、生成メタデータを公開する。 バインド後は、識別情報を修復または再解決する目的で、注釈、ソースレコード、以前のカタログ、生成済みJSONを再び開いてはならない。埋め込みスナップショットをデコードする本番ローダーは受け渡し境界であり、第2のソース解決段階ではない。コマンド、フラグ、レジストリ項目、後続の生成入力を作成または修復してはならない。 バージョン付き変更が明示的に承認されない限り、公開済みのワイヤー契約を維持する。別システムとのアーキテクチャ上の整合は、バージョンなしの形式変更を正当化しない。 ## すべてのコマンドとスキーマが、両方向で対応しているか確かめる バインダーは、存在しないか実行不能なコマンドパス、エイリアスの衝突、有効なレジストリと一致しないネイティブ識別情報の表明を拒否しなければならない。注釈が代替の識別情報源ではなく整合性検査である場合、ネイティブ識別情報の表明がないことは許容できる。 双方向で網羅性を強制する。 1. カタログへの投影を含む、受け渡されるすべてのスキーマツールは、実行可能なコマンドへ解決されなければならない。 2. 外部に公開された実行可能なコマンドリーフは、すべてスキーマへ解決されるか、空でない理由を持つ正確なレビュー済み対象外指定に含まれなければならない。 将来のコマンドを隠す可能性があるため、プレフィックスやワイルドカードによる対象外指定を決して使わない。古い、無効、重複した対象外指定があれば生成を失敗させ、対象コマンドがスキーマへ入った時点でその指定の取り扱いを終える。 レビュー済みレジストリを安定した識別情報とナビゲーションの唯一の正本とし、実行可能ツリーをパス、実行可能性、フラグの正本とする。コマンドツリーが変わるたびに逆方向の完全性テストを実行する。 ## 安全のメタデータと、AIが選ぶための説明を別々に書く 人が記述する入力は所有責任ごとに分ける。メタデータは影響、リスク、確認、冪等性、インターフェース、ランタイムゲート、任意のパラメーターオーバーレイを所有する。選択情報はエージェント用要約、肯定・否定のルーティングガイダンス、例、プロダクトルーティングを所有する。インデックスはプロダクト識別子をそれらのファイルへ対応付けるだけにする。 これらのブロック間でフィールドを混在させてはならない。人が記述する各項目には、明示的なレビュー、具体的なレビュー理由、証拠への参照が必要であり、ユーザーから見える動作を表す最小限の項目にする。選択文はコマンド要約を言い直すのではなく、発動意図、兄弟コマンドへのルーティング、期待される結果を説明する。 宣言済みの優先順位に従って証拠を解決する。最初に実行時の事実、次に稼働中のインターフェーススキーマ、固定済みインターフェースメタデータ、最後に証拠としてだけ使うスキル文書を置く。稼働中の情報取得で個人用の資格情報を使う場合、認証情報を表示したりコミットしたりしてはならない。取得に失敗した場合はその失敗を記録し、承認済みの代替証拠を使い、インターフェースやリモート手続きを捏造しない。 パラメーターオーバーレイは、外部に公開された実行可能なコマンドリーフと実在するフラグを正確に対象としなければならない。説明、インターフェースのマッピング、必須状態、条件付き要件は調整できるが、コマンドやフラグの作成、インターフェースの定義、未知のリモート手続きの提示をしてはならない。 ## 出力を毎回すべて作り直し、どれも同じ値か確かめる 生成は、以前のカタログに対する増分パッチではなく、決定論的な完全スナップショット再構築として扱う。レビュー済み入力をすべて読み直し、古い生成済みプロダクトメタデータの取り扱いを終え、正確な出力投影を書き直す。生成ファイルをマージ入力にしてはならず、生成処理が人の記述した入力やレビュー済みレジストリを変更した場合は、バイト単位のガードで失敗させる。 すべての投影に、解決済みの同じ型付きツール仕様を使う。リーフのペイロードは完全エクスポートとカタログの対応項目に一致し、概要とグループ要約は同じツールの要約投影に一致しなければならない。エイリアス検索で変更できるのはエイリアス固有の表示フィールドだけであり、コマンド契約を再解決または変更してはならない。 受け渡されるすべてのツールとパラメーターフィールドで、選択された出典情報の値は受け渡される値と正確に一致しなければならない。ソース名、候補数、フィールドの存在、ハッシュだけの確認では不十分である。 生成、ランタイム確認情報の正しさの検査、逆方向の完全性テスト、範囲を絞ったコマンドテスト、最終埋め込みローダー検査を実行する。スナップショットを受け入れる前に、そこで生じた差分をすべて確認する。 ## 例とドライランを、--yes などの抜け道なしで確かめる レビュー済みの例はツールごとに2件以下とする。例では、実在するプライマリパスまたはエイリアス、受け付けられるフラグ、必須の位置引数、有効な「いずれか1つ必須」「同時必須」「相互排他」の全制約を使わなければならない。シェルコメントや `--yes` のような確認回避フラグを含めてはならない。 すべての例は、バインド済みコマンドに対する契約検証を通過しなければならない。必須値の欠落、制約違反、実行時エラー、インターフェース解決エラーは契約上の欠陥であり、例を飛ばす理由にはならない。 実行時の例の実行は任意参加とし、最終的な型付きツールが明示的なレビュー済みドライラン機能を公開している場合にのみ許可する。リスクと確認のメタデータからプレビュー機能を作り出してはならない。レビュー済みの手動判定では、既存のドライラン機能を、0始まりの正確な例インデックス1件に限って狭められる。ただし承認済み理由コードと具体的な理由を使い、通常の契約検証をスキップへ変えてはならない。 ドライランの失敗を捕捉し、契約検証のみへ動的に格下げしてはならない。既定では網羅的な契約ゲートを実行し、隔離されたユーザー状態と遮断されたプロキシを使う実コマンドでは、適格なドライラン部分だけを実行する。安定した実行件数の変更は、レビューを要する契約変更として扱う。 ## AIが正しいコマンドを選ぶかを、正解を送らずにテストする 肯定的な選択シナリオはすべて、レビュー済みコマンドが選ばれるべきだという表明として扱い、否定的なシナリオはすべて、そのコマンドが選ばれてはならないという表明として扱う。人が記述した選択フィールドから決定論的な型付きフィクスチャを導出し、ツールの正確な網羅と実行可能なプライマリコマンドを必須とし、欠落、重複、矛盾した期待値を拒否する。文字列一致だけでは意味理解を証明できない。 稼働中のモデルを使う選択検査は、明示的な任意参加に保つ。小規模なスモークセット、レビュー済みの全セット、正確なケース一覧に対応する。評価器へ送るのはケース識別子、シナリオ本文、同一プロダクトの候補表だけとし、期待値と禁止条件はローカルに保持する。 組み込みのHTTPS評価エンドポイントを許可リストに登録する。他のHTTPSプロバイダーを使うには、承認済み許可リストへ正確なベースURLを登録する必要があり、平文HTTPを許容するのはループバックのテストサーバーだけである。API資格情報を任意の平文エンドポイントへ決して送らない。 通常の継続的インテグレーションは決定論的に保ち、モデルを呼び出してはならない。再現可能なフィクスチャ、コマンドのバインド、例の有効性、出典情報、最終受け渡しの同一性を阻止ゲートとする。 ## 安全と確認の設定を、どの情報を優先するかの順番で決める 安全性とパラメーターのメタデータは、より厳しそうな値を選ぶのではなく、ソース優先順位に従って解決する。優先順位の高いレビュー済みソースは、影響、リスク、確認、冪等性、説明、マッピングを意図的に強めることも弱めることもできる。すべての候補と選択されたソースを維持し、同じ優先順位の競合は黙って統合せず失敗させる。 必須コマンドフラグは下限となる。オーバーレイは任意フラグを必須にできるが、実行可能コマンドが宣言した必須要件を決して弱めてはならない。コマンド文では、レビュー済みのコマンド固有ヒント、コマンドヘルプ、インターフェースメタデータの順に優先する。一般的なリモート手続きの説明で、専門化されたコマンド説明を上書きしてはならない。 ある安全性フィールドから別の安全性フィールドを推測してはならない。破壊的な影響や高いリスクが、確認を機械的に書き換えるわけではない。確認は明示的なランタイムゲートと一致させ、ユーザーの確認が必要な場合は `--yes` のような回避フラグを追加する前にその確認を得なければならない。 配布済みコマンドヘルプとリーフスキーマが一致しない場合は、実行可能コマンドが受け付けるフラグだけを渡す。安全性のソースが競合する場合は、より安全な解釈を使うか、停止して契約ドリフトを報告する。確認の意味は、ジェネレーターの単体テストだけでなく、最終埋め込みローダーと問い合わせ経路を通して検証する。 ## コマンドを段階的に調べ、データは実際のコマンドで取る 通常の検出は段階的に行い、概要、プロダクトまたはグループ、リーフの順に進める。完全エクスポートは安定した互換性契約のために確保し、フラグのないコマンドに対する空のパラメーターオブジェクトを含め、最終ツールごとに完全なパラメーター、制約、安全性の意味を収録する。簡略化した完全エクスポートは完全な互換性基準にはならない。 コマンドヘルプは、パスの存在と実行可能プログラムが受け付けるフラグを決定する。リーフスキーマは、エージェント選択、パラメーターマッピングと制約、安全性と確認の意味を決定する。不一致は契約ドリフトであり、推測を許すものではない。 スキーマとヘルプはコマンドを説明するものであり、業務データを返すものではない。検出後、確認済みの権限内で適切な実際の読み取り、検索、一覧取得コマンドを実行してデータを取得する。 受け渡し前に、コマンド識別情報がレビュー済みであること、実行可能性の網羅が双方向であること、対象外指定が正確であること、人が記述するブロックの所有責任が分離されていること、ソース優先順位が保たれていること、生成出力が出力専用のままであること、例が実際の契約を通過すること、確認がランタイムゲートと一致すること、すべての投影が同じ型付き正本と一致することを確認する。