概要
Claude CodeなどのAIエージェントに操作させることを前提としたCLIツールを開発する際の、命令の構造化やJSON出力、エラーハンドリングにおける設計上の工夫をまとめた記事。
詳細内容
AIエージェント（特にClaude Codeなど）から呼び出されることを前提としたCLIツールをGoで開発した著者が、人間向けCLIとは異なる設計の勘所を5つのポイントで解説しています。主な内容は以下の通りです。
1. **Skill定義の最小化**: エージェント側の定義（Skill）にはCLIの存在のみを記述し、詳細な使い方はCLI自体のサブコマンド（例: `skill`）から出力させることで、ロジックとマニュアルの同期を容易にする。
2. **JSON出力とメタデータ**: エージェントが解析しやすいJSONをデフォルト出力とし、次にエージェントが取るべきアクションを判断するための情報（URLや更新フラグ等）を結果に含める。
3. **親切なエラーメッセージ**: 単にエラーを伝えるだけでなく、解決のために実行すべき具体的なコマンドをメッセージに含めることで、エージェントの推論ステップを短縮する。
4. **処理の軽量化と分離**: 検索（軽量）と詳細取得（重量）のステップを分けることで、トークン消費を抑え、エージェントが段階的に情報を探索できるようにする。
5. **フラグの削減**: 複雑なオプションを減らし、デフォルト設定を洗練させることで、エージェントの判断ミスを防ぎトークン効率を高める。
これらの知見は、LLMがツールを操作する「AI Native」なソフトウェア設計において非常に実用的なガイドラインとなっています。