先日、NASEBANAL の開発者向けサイト NASEBANAL API Specs を公開しました。各 API の OpenAPI リファレンスと、それらを使った実装レシピ集 (Cookbook) を一つのサイトに集約したものです。本稿では、この公開の背後にある問題意識——AI コーディングを日常的に用いるなかで感じてきた、開発の「見えにくさ」——と、それに対して進めている 2 つの取り組みを整理してご紹介します。あわせて、その先に見据えている、内製・外注・エージェントに共通するガードレールとしての OpenAPI Spec への期待についても述べたいと思います。
取り組みの動機 — AI コーディングで感じた「違和感」
AI エージェントに開発を任せると、機能は驚くほどのスピードで実装されていきます。便利である一方、動作確認さえできてしまうと、「動いたのだから、すぐにリリースしたい」 という気持ちが先に立ちがちです。
しかし、そのリリース速度に対して 実装の理解が追いつかなくなる という問題があります。レビューを十分に通さないまま動いてしまうコードが積み上がり、コードベースの実態や複雑度が次第に見えにくくなっていきます。これはエージェント任せに限った話ではなく、オフショアをはじめとする「自分以外の手による開発」でも同じ構図が生じます。
そこで考えたのは、次のようなことでした。
細部までをすべて追い切れなくてもよい。ただ、各 PR・Merge を経てコードがどのような状態になったのか を、適宜「人間が把握できる形」で残しておきたい。
この「人間が把握できる形にしておく」を実現する手立てとして、二つの方向性に期待を抱きました。一つは メトリクスによる可視化——コードや開発活動の状態を、数値の時系列として俯瞰すること。もう一つは Spec Driven Development(仕様駆動開発)——外部に公開すべき契約(仕様)を先に固定し、実装をそれに従わせること。直近の取り組みは、この二つをそれぞれ形にする試みです。
取り組み① API リファレンスの別サイト化 — Contract-Driven Development への布石
一つ目の取り組みは、各 API の OpenAPI リファレンスを本体アプリから切り出し、開発者向けサイト NASEBANAL API Specs として独立に管理する形へ移行したことです。リファレンスのレンダリングには Scalar を採用し、各 API の仕様をブラウザ上で確認できます。同じサイト内の Cookbook には、それらの API を用いた実装レシピも掲載しています。
この別サイト化は、Contract-Driven Development (CDD) を実現するための布石 と位置づけています。CDD が機能するようになれば、それはそのまま AI コーディングのガードレール として働くと期待しているためです。とりわけ Specmatic を用い、OpenAPI Spec を契約としてコントラクトテストとスタブ生成を回す CDD に、強い関心を持っています。
なぜ契約を独立して管理したいのか。AI コーディングでフロントエンドとバックエンドを 同時に 開発すると、機能実装そのものは非常にスムーズに進みます。その一方で、両者を並行して動かしているがゆえに、外部に公開すべきインターフェース(契約)がどうなっているのかが、かえって把握しづらくなる という現象が起こります。フロントエンドが期待する形とバックエンドが返す形が、レビューを経ないまま静かに乖離していく——いわゆる契約ドリフトが生じやすいのです。
OpenAPI Spec を バージョン管理された契約 として外部に切り出し、そこから Specmatic でスタブとコントラクトテストを生成しておけば、フロントエンドは実バックエンドなしで E2E テストを回せます。加えて、CDD が定着すれば、新しい API のバージョンアップも、契約を介してフロントエンドへスムーズに反映できるようになる ことを期待しています。NASEBANAL では現在、この CDD フローを Account / Recorder / Target で段階的に導入しているところです。その設計動機・パイプライン構成・運用の実際については、近日中に独立した記事として改めて詳しくご紹介する予定です。
取り組み② 開発の可視化 — DORA / Code メトリクスとトークン消費
二つ目の取り組みは、先述の 「人間が把握できる形」のメトリクス可視化 を、実際に自分たちの開発へ適用して運用し始めたことです。具体的な手順は Cookbook に動くレシピとして公開しています。可視化の柱は二つあります。
DORA / Code メトリクスのモニタリング
一つは、GitHub Actions から DORA メトリクス(Deploy 回数・LeadTime)とコードメトリクス(LOC など) を、毎マージおよび毎日 Recorder に蓄積するパターンです(レシピ)。これにより、エージェントやオフショアを含む「他者による開発」が、現在どのような状態にあるのかを時系列で俯瞰できます。細部の差分をすべて追えなくとも、Merge のたびにコードの規模・複雑度・デプロイ頻度がどう変化したかが、人間がひと目で読める形で残ります。
上は NASEBANAL 内部リポジトリの実データで、左軸が総 LOC(オレンジ)、右軸がブランチ密度(緑)です。コードが増えつつもブランチ密度が緩やかに下がっており、規模の拡大に構造の整理が追いついている様子が読み取れます。
注: このサンプルは Recorder のリポジトリのもので、当該期間はまとまった改修がほとんどなかったため、変化に乏しくややバランスの悪いグラフになっています。解釈の際はその点を差し引いてご覧ください。
トークン消費の監視
もう一つは、Claude Code の Stop hook を用いて、開発(プロジェクト)ごとのトークン消費量 を Recorder に記録するパターンです(レシピ)。Input / Output / CacheRead / CacheCreate の 4 種類を、アプリ別の時系列として可視化します。
素の Input / Output を見ると、Output(緑)が数十万トークン規模まで伸びる一方、Input(赤)はほぼベースラインに張り付きます。入力の大半が prompt cache 側に回るため、課金対象となる素の入力トークンは小さく抑えられます。
キャッシュ側は桁が約 100 倍違うため別チャートにしています。CacheRead(緑)が数千万トークン規模に達し、コンテキストの大半が prompt cache から再利用されていることがわかります。
率直に申し上げると、こちらは現時点ではまだ 実験的な段階 にあり、集計の粒度や解釈には改善の余地が残っています。それでも、アプリ開発ごとのトークン消費を分析すること は、AI 開発の ROI(投資対効果)を評価するうえで、今後ますます重要になると見ています。現在は Claude Code が優勢ですが、今後さらに有力なツールが登場すれば、それらを 同じ土俵で比較評価する 必要が生じるはずです。その際、アプリ別・ツール別の消費量の時系列が手元にあるかどうかは、判断の質を大きく左右すると考えています。
おわりに — 内製・外注・エージェントに共通するガードレールの実装を目指して
これからのソフトウェア開発では、エージェントの出現により、内製・外注(外部サービスの利用を含む)の役割分担が見直されていく のではないかと感じています。これまで開発の選択肢は、内製・国内外注・オフショア開発が中心でした。とりわけ国内では、言語の壁や日本の IT 産業特有の商習慣もあいまって、国内外注への依存が高い状況が長く続いてきました。しかし、いまエージェント開発が急速に伸展したことで、場合によっては、ユーザー企業自身がエージェントを活用した内製開発を担い、外注開発との間で連携プレーを組み立てていく——そうした新たな役割分担が期待されるようになってきていると感じます。そして、その配分や良し悪しを メトリクスで評価したい という要請も、今後ますます高まっていくはずです。
同時に、内製・外注・エージェントという性質の異なる担い手に対して 共通したガードレール を整備できれば、それはそのまま品質管理につながります。その共通のガードレールとして、私はいま 「役割を定義する文書」としての OpenAPI Spec の可能性に強い関心を抱いています。誰が——あるいは何が——書いたコードであっても、満たすべき契約が同じであれば、品質の最低ラインを揃えられるはずだからです。
この仮説を確かめるべく、現在は Specmatic をはじめとするツールを組み合わせた品質評価 を検証しています。その 評価結果については、次回のブログで改めて詳しくご紹介する予定 です。続報をお待ちいただければ幸いです。
ソフトウェアは一度作って終わりではなく、サービスとして継続的なメンテナンス・改善が必要です。昨今は AI によってソフトウェアエンジニアのレイオフが懸念される一方で、だからこそ——継続的なメンテナンスが欠かせないこの領域でこそ——エージェントの活用によって、これまで手が回らなかったディジタル化がさらに前へ進む可能性もあるのではないか、と私は期待しています。
とりわけ日本には、ディジタル化が期待されながらも、技術的には可能なはずなのに実現できていない領域が、まだ数多くあると感じています。Spec Driven なエージェント開発 がそうした領域を一歩ずつ動かしていく——その可能性を、私自身もう少し深掘りしていきたいと考えています。