API から CLI + Skill へ：Coding Agent 時代の新しいソフトウェア開発パラダイム
By mosoo team 
mosoo の開発では当初、よくある順序を採用していました。まず API を構築してプロダクトの中核機能を一通り完成させ、その後に Coding Agent が機能を使いやすくするための CLI を作る、という流れです。
しかし、この順序は逆だったのかもしれません。少なくとも、十分ではありませんでした。
観察したこと
第一級の CLI がなければ、Coding Agent は通常、curl、ブラウザ自動化、その場で作るスクリプトを使って個々の API エンドポイントをテストします。どの方法にも避けられるはずの摩擦がありました。
curlの生のレスポンスは、目の前のテストには不要なフィールドを大量に含む HTML や JSON になりがちです。レスポンスだけでは、フィールドの意味、制約、発見方法、安定した呼び出し方は分かりません。CLI、SDK、継続的に保守されるテストからの圧力がなければ、API 仕様も不完全になったり、古くなったり、実装と食い違ったりしやすくなります。Agent はソースコード、エラー、周辺コンテキストから型、必須フィールド、制約を推測するしかありません。その分、トークンと時間を余計に消費します。- ブラウザ自動化はトークン消費が大きく、遅く、停止しやすいうえ、待っている人にとっても扱いづらい方法です。
- 一時的なテストスクリプトはすぐに増殖します。長く、構造が不統一で、保守しにくくなり、読むためにさらに多くのコンテキストを消費します。
これらの方法は、インテグレーションテストの編成には特に不向きです。Agent はほとんど読めないスクリプトを繰り返し大量に生成します。テスト自体が読めなければ、その結果を説明することも、信頼することも難しくなります。
Vibe Coding に慣れた後でも、ビジネスロジックには誰かが目を通すかもしれません。テストコードはさらに読まれません。誰にも読まれないコードには、ほとんど価値がありません。
この問題は mosoo の開発中ずっとつきまとっていました。転機になったのは、オープンソースの API-to-CLI ジェネレーター Lathe を使い、mosoo の完全な CLI を生成したことです。
Lathe が提供するもの
Lathe は、API が人と AI Agent の両方に使われるチーム向けに設計されています。Swagger 2.0、OpenAPI 3、または google.api.http アノテーション付きの Protobuf API から、本番運用に対応した Cobra CLI を生成します。
生成される CLI には、機械可読な Command Catalog、意図検索、コマンドごとの詳細 JSON、認証メタデータ、リクエストボディのビルダー、構造化出力、そしてリポジトリ内の skills/<cli-name>/ ディレクトリが含まれます。
この組み合わせが重要です。得られるのは単なるシェルコマンドの集合ではありません。Agent が何を実行するか決める前に調べられる、発見可能なインターフェースです。
新しい発見と、新しい問題
CLI を生成した後、その周りに Skill、Workflow、指示を構築しました。すると mosoo の E2E テストと負荷テストは、劇的にシンプルかつ高速になりました。
一連の Case を大まかに考えて Coding Agent に渡せば、Agent が Case を実装し、実行し、結果を収集できます。Skill、CLI、Prompt ベースの Workflow が、その全行程を支えました。
さらに重要なのは、テストの過程が読みやすく説明可能になったため、Agent の結論を素直に信じることも、疑って検証することも容易になった点です。厳密な比較実験は行っていませんが、以前の方法よりトークン消費もはるかに少なく感じられました。
ただし、生成するだけですべてが解決したわけではありません。
Lathe はプロジェクト内のすべての API を CLI コマンドへ変換し、そのサーフェスを扱う Skill を生成します。しかし、どの API がプロダクトの中心なのか、どれを内部に留めるべきか、どの操作を組み合わせれば一つのビジネス Workflow になるのか、どの状況でどのコマンドを使うべきかまでは分かりません。
そのため、最初に生成した CLI は Agent にとって使いにくいものでした。どのコマンドを選ぶべきか、逆にいつ使うべきでないかを判断できなかったのです。当時、生成された Catalog には非表示コマンドを含めて 127 個のコマンドがありました。操作の多さは、命名やガバナンスの問題も引き起こしました。
そこで mosoo のビジネスドメインに関する私たちの理解を反映させました。Skill を再編し、CLI を使う大量の Case を実行し、Agent のフィードバックを取り込みました。最初の mosoo CLI を生成してから、Coding Agent が本当に使えるものにするまで、断続的な作業で約 1 か月かかりました。
Day 1 から CLI があったら？
Day 1 の最初の API から、次のことを行っていたらどうなっていたでしょうか。
- CLI サーフェスを生成する
- どの API をコマンドにするか、しないかを意図的に選ぶ
- どのコマンドを組み合わせて Workflow にするかを特定する
- 各コマンドを使うビジネス上の状況を文書化する
- 対応する
SKILL.mdを手で書く
mosoo CLI はもっと小さく、Agent にとって使いやすいものになっていたはずです。コマンド名も短く、人が読みやすくできたでしょう。開発ループ全体も、より速く、より少ないコンテキストで回せたかもしれません。
なぜ CLI を先に作らなかったのか？
6 月の時点で、API が完成する前から CLI の必要性を訴えていました。CLI なしの Dogfooding はすでに苦痛になっていたからです。それでも最初の mosoo CLI が登場したのは 7 月で、Lathe がチームに紹介されてから 2 週間後でした。
私たちを遅らせた前提は二つありました。
一つ目は、Coding Agent 時代にソフトウェアがどう利用されるかに適応できていなかったことです。UI への依存は小さくなり、CLI-first の操作面が重要になります。最初の 2 か月、API 開発は主に mosoo のフロントエンドを通して進めていました。システムの入出力ではなく、目で見た印象で評価していたのです。その結果、プロダクトの基礎的な振る舞いよりも、命名の議論や見た目の磨き込みに時間をかけすぎました。
二つ目は、早い段階で CLI を導入すると複雑さが増すと思っていたことです。API が変わるたびに、手作業で再生成して配布する必要があると想像していました。しかし、ジェネレーターと安定した Workflow があれば、その保守コストはほぼゼロに近づきます。それどころか CLI は、API 仕様を正確に保つ健全な圧力を生み、API ドキュメントの改善にもつながります。
開発ループ
現在、Coding Agent 時代のソフトウェア開発は、次のループに従うべきだと考えています。
- API を開発または変更する。
- OpenAPI や Swagger などの API 仕様を更新またはエクスポートする。
- CLI、Command Catalog、Skill を生成または更新する。
- CLI を通してすべての API 操作を検証する。
- CLI コマンドを Workflow に組み立てる。
- インテグレーションテストと E2E テストを実行する。
- 問題が見つかったら、その問題を所有する API、生成インターフェース、Workflow のレイヤーに戻る。
そして、繰り返します。
重要なのは、このループを見えないプロジェクト契約にすることです。ユーザーが Coding Agent に対して、CLI を生成するよう、あるいは CLI 経由でテストするよう毎回指示する必要があってはいけません。
そのためには、IDE で新規プロジェクトを作るときのようなプロジェクトテンプレートを、Coding Agent 向けに用意するとよいでしょう。最初から CLI と Skill の生成を組み込み、Workflow を明示する AGENTS.md も含めます。
このような完全なテンプレートがすでに存在するかどうかは、まだ調査できていません。Lathe は近いうちに、その一つを提供できるかもしれません。