agent-native-design

agent-native-design

目的

このスキルは、コマンドラインツールを分析、設計、リファクタリングし、人間、AI エージェント、オーケストレーションシステムが同時に確実に利用できるようにするものです。

CLIを単に使うためのスキルではありません。CLIをエージェントネイティブなインターフェースとして設計し、レビューするためのスキルです。

このスキルでは、次の4つの目標に焦点を当てています。

1. AI エージェントにとって予測しやすいCLIの動作を実現します。
2. 人間が読みやすく、問題から復旧しやすいCLI出力を実現します。
3. システムやオーケストレーターが管理しやすいCLIの実行を実現します。
4. 認証からエラーの振り分けまで、完全なインタラクションループを定義します。

---

このスキルを使用する場面

ユーザーが次のことを求めている場合に、このスキルを使用してください。

• 既存のCLIがエージェントに適しているか評価する
• AI エージェントをより適切にサポートできるようCLIを再設計する
• APIやSDKをエージェントネイティブなCLIに変換する
• ヘルプ出力、スキーマ設計、終了コード、JSONコントラクトをレビューする
• ドライラン、認証の委任、安全境界を設計する
• スキーマからCLIスキル、ドキュメント、インターフェース規約を生成する
• 人間向けのCLIを機械に適したCLIにリファクタリングする
• CLIがエージェントランタイムとどのように連携するか定義する

よくあるプロンプトの例：

• 「このCLIをレビューして、エージェントネイティブかどうか教えてください。」
• 「AI エージェントが確実に使える、このAPI向けのCLIを設計してください。」
• 「このツールをリファクタリングして、stdoutを機械可読にし、エージェントにとってより安全にしてください。」
• 「スキーマのイントロスペクション、ドライラン、終了コードのセマンティクスを定義するのを手伝ってください。」

このスキルを使用しない場面

ユーザーが次のことだけを求めている場合は、このスキルを使用しないでください。

• 特定のコマンドの実行方法
• CLIのインストール方法
• インターフェース設計に関係しないシェルのトラブルシューティング
• 一般的なLinuxやターミナルのチュートリアル
• ツールに関係しないエージェントの計画やメモリの設計
• CLIやツールのレイヤーを含まないAPIのビジネスロジックのレビュー

---

コアモデル

エージェントネイティブなCLIは、3つの対象に同時に対応する必要があります。

1. 人間

ニーズ：読みやすい出力、親しみやすいエラーメッセージ、導入ガイダンス。 チャネル：stderr、任意の--format table、必要に応じて対話型TUI。

2. AI エージェント

ニーズ：構造化データ、安定したコントラクト、自己記述。 チャネル：JSON形式のstdout、安定した終了コード、スキーマのイントロスペクション、ドライランのプレビュー、生成されたスキル／ドキュメント。

3. システム／オーケストレーター

ニーズ：認証の委任、プロセス管理、決定論的なエラーの振り分け。 チャネル：環境変数、終了コード、ドライランモード、安定したコマンドのセマンティクス。

基本コントラクト

チャネル	主な対象
stdout	マシンとエージェント
stderr	人間
exit codes	システムとオーケストレーター

このスキルでは、CLIをエージェント向けの第一級インターフェースにする方法を説明します。実運用のエージェント（Claude Code、Cursor、Gemini CLI）では、CLIとMCP サーバーを組み合わせることがよくあります。状態の変更やローカル／スクリプト可能な作業にはCLIを、マルチテナントSaaSやユーザーごとの認証にはMCPを使用します。MCP側も必要な設計では、references/hybrid-mcp-cli.mdを参照してください。そこには判断マトリックスと、CLIとMCPのトレードオフの根拠となるベンチマークデータが記載されています。

---

完全なインタラクションループ

フェーズ	ステップ	説明
0. ブートストラップ	1	人間／システムが認証トークンまたは認証情報を取得する
0. ブートストラップ	2	信頼できる環境変数を設定する：トークン、プロファイル、安全モード
1. 検出	3	エージェントがスキルまたはコマンドの概要を読み込む
1. 検出	4	エージェントがパラメーターについてスキーマ／ヘルプを照会する
2. 計画	5	エージェントが--dry-runを使ってリクエストの形式をプレビューする
3. 実行	6	エージェントが検証済みの入力で実行する
4. 解釈	7	エージェントが構造化された結果を解析する
5. 復旧	8	エージェントが終了コードとエラーオブジェクトを使って、再試行、再認証、修復、またはエスカレーションを行う

すべてのフェーズに対応していないCLIは、エージェントの観点では不完全です。

---

7つの原則

これらは設計の根幹となる原則です。各原則には、少なくとも1つの評価基準と、それを裏付ける少なくとも1つの例があります。

原則 0. 1 つの CLI、3 つの対象ユーザー

CLI は、人間、エージェント、システムのすべてに同時に対応する必要があります。いずれか 1 つの対象ユーザーのみに対応する設計は不完全です。

原則 1. 構造化出力がインターフェースです

stdout は常に解析可能で、安定している必要があります。成功時も失敗時も、構造化された JSON を出力します。CLI は、どの対象ユーザーが読み取るのかを自ら判断する必要があります。起動時に stdout が TTY かどうかを検出し、TTY でなければデフォルトで JSON を、TTY であればデフォルトで人間が読みやすい形式を使用します。NO_COLOR と明示的な --format json|table フラグは、自動検出より優先されます。エージェントが --format json の指定を覚えておく必要があってはいけません。必要な場合、指定を忘れて、実行結果が解析不能な文章になっても気づかないことがあります。エンベロープとエラーの規約については、references/design-patterns.md#output-envelopes を参照してください。

原則 2. 信頼は方向性を持ちます

CLI 引数が本質的に信頼できるとは限りません。幻覚を起こしたり、プロンプトインジェクションを受けたりしたエージェントから渡される可能性があります。人間またはシステムが設定した環境レベルの構成は、より信頼できます。エージェントは制限された範囲内で 何をするか を選び、人間は どこで、どのように操作することが許可されるか を定義します。

原則 3. CLI は自分自身について説明する必要があります

エージェントが外部の README ファイルを読まずに使える程度に、CLI は自身について説明する必要があります。自己説明は一度にすべてを表示するのではなく、段階的に行う必要があります。トップレベルの --help にはリソースを、リソースのヘルプにはアクションを、アクションのヘルプにはフラグを表示します。別途 schema <resource.action> を実行すると、完全な型付きスキーマが返されます。数百のコマンドを最初の --help にすべて表示する CLI では、エージェントが呼び出すたびにその分のトークンコストが発生します。references/design-patterns.md#help-design と references/examples.md の例 2 および 5 を参照してください。

原則 4. 段階的な可視性による安全性

読み取りコマンドは見つけやすくし、変更コマンドには明示的な警告を付け、破壊的なコマンドはスキルから隠すか、別途ゲートで制御します。段階とその根拠については、references/design-patterns.md#safety-design の表を参照してください。段階分けは必要ですが、それだけでは十分ではありません。これはプロンプト側の防御策であり、承認疲れによってすぐに効果が薄れます。エージェントのランタイムが CLI を OS レベル（ファイルシステム、ネットワーク、プロセス）でもサンドボックス化すると想定し、そのサンドボックス内では破壊的なコマンドが安全側に失敗するように設計してください。

原則 5. 中間ではなく境界で検証する

入力は CLI のエントリポイントで一度だけ検証します。内部コードは、検証済みで型付けされた信頼できる構造を扱います。検証関数は一元化し、受け入れるケースと拒否するケースの両方をテストします。

原則 6. スキーマを信頼できる唯一の情報源とする

スキーマが存在する場合、すべてをそこから導出します。CLI コマンド構造、検証ルール、ヘルプテキスト、生成ドキュメント、生成スキル、型定義、ドライランの規約が対象です。スキーマを手作業で重複して定義してはいけません。また、スキーマには独自のバージョンと非推奨化のシグナルを含める必要があります。これらはすべての応答の meta ブロックに提示し、古い情報をキャッシュしているエージェントが、削除されたメソッドを気づかずに呼び出すのではなく、差異を検出して再発見できるようにします。バージョン管理の規約と例については、references/design-patterns.md#schema-versioning を参照してください。

原則 7. 認証を委任可能にする

認証情報の取得と更新は、人間またはシステムが管理するフローで行います。エージェントは認証情報を使用しますが、認証ライフサイクルは管理しません。推奨する仕組みは、環境変数、構成ファイル、OS キーチェーンとの統合、外部で更新されるトークンです。標準的なパターンについては、references/examples.md の例 3 を参照してください。

---

標準的なレビューのワークフロー

ステップ 1. 入力を分類する

ユーザーが提供しているものが、既存の CLI、ラップ対象の API、概念設計、部分的なインターフェース、または失敗ケースのいずれかを判断します。

ステップ 2. 3 つの対象者を把握する

人間： 読みやすい出力になっていますか？ エラーは理解しやすいですか？ オンボーディングはサポートされていますか？

エージェント： stdout は安定した JSON ですか？ CLI は自身について説明できますか？ スキーマのイントロスペクションやドライランはありますか？

システム： 認証を委譲できますか？ 終了コードは安定していますか？ 障害を決定的に振り分けられますか？

ステップ 3. インタラクションループを確認する

CLI が次の各機能をサポートしているか確認します：ブートストラップ、検出、パラメーターの理解、プレビュー、実行、解析、復旧。

ステップ 4. ルーブリックで CLI を採点し、原則に対応付ける

14 項目のルーブリックを使用して CLI を採点します。ルーブリックの全文は references/rubric.md にあります。7 つの原則のそれぞれに、対応するルーブリック項目が少なくとも 1 つあるため、スコアと原則の対応付けに漏れはありません：P0 → 3 つの対象者への対応、非対話型の操作；P1 → stdout の契約、stderr の分離、冪等な再試行、エラーからの復旧可能性；P2 → 信頼境界；P3 → 自己説明（ヘルプ）、ドライラン；P4 → 安全性ティア；P5 → 境界の検証；P6 → スキーマのイントロスペクション；P7 → 認証の委譲。次に、各原則について、根拠、リスク、推奨事項をまとめます。レビュー用チェックリストの全文は references/checklists.md にあります。

機械検証のベースライン。 レビュー対象の CLI がインストール済みで実行可能な場合は、ルーブリックを適用する前に anc audit <command> --output json（8 つの RFC 2119 原則に基づく agentnative リンター）を実行します。anc は配布済みバイナリの挙動を検証します：非対話型の操作、--output json の妥当性、スキーマの検出可能性、ヘルプ／バージョン、終了コード、NO_COLOR、ドライランです。ルーブリックのみで評価する項目は自分で採点してください。現在のリンターでは、信頼の方向性（P2）、境界の検証（P5）、安全性ティア（P4）、認証の委譲（P7）、スキーマのバージョン間の差異（P6）は測定できません。CLI をインストールできない場合、または anc を利用できない場合はルーブリックのみを使用し、利用できる場合はルーブリックのスコアと併せて anc のスコアカードを報告します。

ステップ 5. リファクタリング計画を作成する

• P0 必ず修正
• P1 改善を推奨
• P2 長期的な改善

---

既定の出力形式

1. 総合評価

CLI が エージェントネイティブ、部分的にエージェントネイティブ、または まだエージェントネイティブではない のいずれかを示します。

2. 3 つの対象者との契約のレビュー

人間、エージェント、システムへの対応を評価します。

3. インタラクションループの対応状況

各フェーズを評価します：認証のブートストラップ → 環境のセットアップ → スキル／ヘルプの検出 → スキーマのイントロスペクション → ドライラン → 実行 → 解析と復旧。

4. ルーブリックのスコアと 7 つの原則のレビュー

まず 14 項目のルーブリックのスコアを報告し、続いて 7 つの原則を「ステータス・根拠・問題・推奨事項」の形式でまとめます。

5. 主なリスク

設計上の問題をまとめます：人間向け出力のみ、安定しない JSON、スキーマのイントロスペクションがない、破壊的なコマンドが過度に公開されている、認証がエージェントに結び付いている、終了コードが曖昧。

6. リファクタリング計画

references/examples.md にある例を使って、優先順位を付けた推奨事項を示します。

---

このスキルが推奨を避けるべき事項

• 人間が読める文章だけを出力契約とすること
• 基本的なコマンド検出に README を必須とすること
• スキーマと検証の内容が食い違うこと
• 主にエージェントが生成した引数を通じて認証情報を渡すこと
• 破壊的な操作を既定で公開すること
• 文書化されていない規約に依存する CLI の挙動
• 機械で振り分けられず、テキストのみのエラー
• 再試行時に冪等でない変更操作
• --yes による回避手段がなく、TTY を考慮したフォールバックもない確認プロンプト
• トップレベルの --help でスキーマを早々にダンプすること — CLI をループ内で呼び出すエージェントは、呼び出しのたびにこのコストを負担します。代わりに段階的な開示を使用してください。トークンコストの理由は references/hybrid-mcp-cli.md に記載されています。

---

参考ファイル

必要に応じて読み込みます。エージェントのコンテキストには、必要になるまで含まれません。

ファイル	読み込むタイミング
references/examples.md	適切なエンベロープ、エラー、ドライラン、バッチレスポンス、またはアンチパターンをユーザーに示すとき
references/rubric.md	CLI レビューのスコア項目を作成するとき
references/checklists.md	ユーザーと一緒に CLI 監査チェックリストを確認するとき、または新しい設計を検証するとき
references/design-patterns.md	エンベロープ、終了コード、冪等性、非対話モード、長時間実行コマンド、スキーマのバージョン管理、ロケール／時刻に関する契約を作成するとき
references/hybrid-mcp-cli.md	CLI、MCP、または両方のどれを採用するか判断するとき、または CLI の効率性に関する主張の根拠としてベンチマーク数値を引用するとき
references/testing.md	CLI が実際に契約を守っていること（エンベロープの形式、冪等性の再実行、TTY の動作、スキーマのドリフト、ドライランの安全性、ロケールの決定性）を検証する方法をユーザーに示すとき。設計レビューの結論が「エージェントネイティブな状態を長期的にどう維持するか」になったら読み込みます
references/citations.md	推奨事項の根拠となる一次資料を引用するとき

---

一文での概要

このスキルは、人間、AI エージェント、システムにとって信頼できる実行インターフェースとなるよう、構造化出力、自己記述、委任認証、安全性の境界、完全なインタラクションループを通じて CLI を改善します。