Cycloud 新基盤の全貌第8回: FrontEnd 編

*※ この記事は、筆者が AI エージェント(Claude Code)と対話しながら執筆しました。読了時間の目安は約 10 分です。* ## はじめに CyberAgent group Infrastructure Unit(CIU)の小竹です。フロントエンドエンジニアとして、Web コンソール「Cycloud Platform Console」の開発・運用を担当しています。本記事では、このコンソールで何ができるのか、そしてどう作られているのかを、開発の経緯と技術の話を交えて紹介します。 Cycloud Platform Console は、[Cycloud 新リージョン基盤](https://developers.cyberagent.co.jp/blog/archives/64643/)プロジェクトの一環として開発している Web コンソールです。これまで個別のコンソールや CLI に分かれていた Cycloud サービスの操作を 1 つのコンソールに統合し、Cycloudプロジェクトや IAM と組み合わせて横断的に扱えるようにしていく取り組みです。 現時点では IAM・Cycloudプロジェクト管理・Compute・Networking・Load Balancing・Cycloud Run・Container Registry・Secrets・Billing・Hosted Runner の 10 サービスが使えます。今後は、GKE ライクに使えるマネージド Kubernetes の AKE と、全社員が利用できる機械学習基盤の ML Platform も加わる予定で、最終的には**Cycloud のことはこのコンソールを開けば全部できる**状態を目指しています。 ![image](https://developers.cyberagent.co.jp/blog/wp-content/uploads/2026/07/blog-02-home.png)サインイン後のホーム画面。プロジェクト一覧から利用したいプロジェクトを選んで操作を始める。（※表示内容はダミーです） ## Cycloud Platform Console の歩み もともと Cycloud には、AKE、Cycloud Run、ML Platform など、サービスごとに別々の Web コンソールがあり、それらを 2 人のフロントエンドエンジニアで運用していました。依存ライブラリや SDK クライアント(※1)を共通化してはいたものの、バージョンを上げるたびに各コンソールへの追従作業が発生し、運用コストは膨らむ一方。品質の担保もままなりません。Cycloud 新リージョン基盤プロジェクトの際に、「コンソールを 1 つに統合しよう」というのが、Cycloud Platform Console の出発点のひとつです。 **※1 SDK クライアント: Cycloud の各サービス API を呼び出すためのクライアントライブラリ。API 定義から自動生成された TypeScript パッケージ(@cycloud-io/*)として、各コンソールで共通利用していた。 開発は 2025 年 3 月、Create Next App の雛形から始まりました。そこから 16 ヶ月で、10 サービスをコンソールから操作できるところまで実装してきましたが、変わったのは機能の数だけではありません。開発のやり方そのものが大きく変わっています。 時期 出来事 2025-03 プロジェクト発足(Create Next App + Cloudscape) 2025-05 Claude Code 導入。公開直後からエージェントコーディングを検証 2025-06 基盤固めの月。テスト・モック基盤・BFF 認証・クリーンアーキテクチャが出揃う 2025-11 初リリース 2025-12 プロダクション化。Terraform / Docker / Nginx→Envoy 移行 2026-03 Issue 駆動 × AI 駆動へ転換。.claude/rules 誕生 2026-04 品質の仕組み化。Storybook + Chromatic・テスト戦略の明文化 2026-07 現在。173 ページ・10 サービス提供中 また、AI エージェントが出てきたこともあり、いまの設計が最適かを常に問い直すようにしています。例えば、src/utils の廃止と src/lib への統合したようにファイル構成の見直しや、Envoy への移行、middleware を使わない認証への刷新。一度作ったものでも、そのときどきのベストプラクティスを追い続けています。 ## できること 現在管理できるのは以下の 10 サービスです。 サービス できること IAM ユーザー・ロール・サービスアカウント・外部アカウント・マネージドポリシーの管理 Projects プロジェクトの作成・サービスの有効化 Compute インスタンス・ボリューム・イメージの管理 Networking VPC・サブネット・セキュリティグループ・Floating IP の管理 Load Balancing 内製 L4/L7 ロードバランサー(Kubernetes Gateway API 互換)のゲートウェイ・ルート・ターゲットグループ・証明書の管理 Cycloud Run コンテナサービスのデプロイ・リビジョン管理 Container Registry リポジトリ・パッケージの管理 Secrets シークレットとバージョンの管理 Billing 各サービスのコストや、作成したインスタンス単位のコストの参照 Hosted Runner GitHub Actions ランナーグループ・キャッシュの管理 AKE と ML Platform は現在実装中で、近いうちにお披露目できる予定です。 画面はどのリソースも「一覧 → 詳細 → 作成・編集・削除」という共通の構成で、デザインは AWS 製の Cloudscape Design System(採用の経緯は後述)に統一しています。AWS のマネジメントコンソールに近い操作感で、ページは全部で 173 ありますが、どの画面も同じ操作感なので、新しいサービスが増えても操作を覚え直す必要はほとんどありません。 ![image](https://developers.cyberagent.co.jp/blog/wp-content/uploads/2026/07/blog-03-compute-instances.png)Compute のインスタンス一覧。どのサービスもこの「一覧」画面が入り口になる。（※表示内容はダミーです） ![image](https://developers.cyberagent.co.jp/blog/wp-content/uploads/2026/07/blog-04-run-create.png)Cycloud Run のサービス作成フォーム。作成・編集画面も全サービス共通の文法で作られている。（※表示内容はダミーです） ## 技術的な特徴 フロントエンドは Next.js 15(App Router)+ React 18 + TypeScript、データ取得は SWR、バリデーションは Zod という構成です。特徴的な部分を紹介します。 ## UI を Cloudscape Design System に全振りする 実は当初、Cycloud 独自の UI コンポーネントを一から作る構想がありました。しかしチームは私を含めて 2 人、デザイナーさんはいません。デザインシステム作りは、コンポーネント実装そのものより、仕様決めやガイドライン整備、ドキュメント作成といった周辺の仕事が重く、そこに割く余裕がありませんでした。 そこで、自由度の高い shadcn/ui のような選択肢ではなく、ガイドラインとドキュメントが最初から整備されている [Cloudscape Design System](https://cloudscape.design/)(AWS が自社コンソール向けに開発した OSS)を採用しました。デザインシステムを作る仕事を丸ごと手放し、その分を機能実装に振り向ける判断です。 実際、Cloudscape のコンポーネントはプロパティに値を渡すだけで、高機能なデータテーブルやオートコンプリート付きのセレクトメニューが実装できます。パディングやマージン、レイアウトの調整に時間を割く必要がなく、タイトなスケジュールのなかでも品質の高い UI を出せました。専任デザイナーを置かずに 173 ページを作っても見た目がばらつかないのは、デザインの判断を Cloudscape に委ねているからです。 ## API の仕様は TypeScript の型でわかる Cycloud の API は gRPC(Protocol Buffers)で定義されています。[Google の API Improvement Proposals を参考にしたリソース指向の設計](https://developers.cyberagent.co.jp/blog/archives/64873/)で、どのリソースも CRUD 操作で宣言的に扱えます。コンソールはこの定義から自動生成された TypeScript クライアント(@cycloud-io/*、19 パッケージ)を使い、gRPC Gateway 経由で API を呼び出します。 これがフロントエンド開発ではとても便利です。フィールドや enum の中身がエディタの補完に出てくるので、ドキュメントを探さなくても型定義を読めば仕様がわかる。API を呼ぶ層に手書きの fetch はなく、API 側に変更が入ればコンパイルエラーが「影響箇所の一覧」として出てくれます。 ## API の変化に強いクリーンアーキテクチャ とはいえ、生成された API 型をそのまま UI まで引き回すと、API の変更のたびに画面が壊れます。さらに開発当初の生成型はすべてのフィールドがオプショナル**で、何が必須なのか型からわかりません。そのまま使うと UI のあらゆる場所で null チェックを書く羽目になります。そこで、コードベースはクリーンアーキテクチャで依存方向を一方向に固定しています。 UI(Container / View) → Hooks(SWR) → Registry(DI) → UseCase → Repository → API(SDK / BFF) API の型に触れてよいのは最下層だけです。domain 層は Vpc のようなドメインモデルを「必須かどうかが確定した型」として定義し、生成型からの変換でデフォルト値の付与や Date への変換を済ませます。null チェックは変換の一箇所に集約され、上の層は整った型だけを扱えます。application 層の VpcInteractor のようなユースケースは、Repository のインターフェースにだけ依存して CRUD の流れを組み立て、API エラーを「VPC の取得に失敗しました」のようなユーザー向けメッセージへ翻訳します。infrastructure 層の VpcApiRepository は、SDK クライアント生成・認証ヘッダー・ページネーション・モック分岐といった通信の都合を抱え込み、ドメインモデルに変換して返します。層のあいだは port(インターフェース)でつながり、registry が実装を注入。UI はユースケースを SWR でラップした hooks を呼ぶだけです。 効果は「API の都合が UI に漏れない」ことに尽きます。フロントエンドに知らされないままAPIの定義が変更され @cycloud-io/* のバージョンを上げても、ビルド時に型エラーとして検出でき、実行時にコンソールが落ちる事態を未然に防げます。依存方向は eslint-plugin-strict-dependencies で制限していて、たとえば UI が infrastructure 層を直接 import すると lint が落ちます。たくさんの TypeScript ファイルを少人数で書き続けても秩序が崩れないのは、レビュアーの頑張りではなくこの仕組みのおかげでもあります。 ## コンポーネントは Container/Presentational、テストは 3 層 React コンポーネントは、データ取得や状態管理を Container に、描画を Presentational(View)に分けるパターンで実装しています。Atomic Design も検討しましたが、UI 部品そのものは Cloudscape が提供してくれるので、自前の部品階層の管理はオーバースペックと判断しました。 テストは Unit・Integration・E2E の 3 層で、Vitest・Storybook・Playwright を責務に合わせて使い分けています。単一ページの動作確認は Container と View を結合レンダリングする Integration テストに寄せ、原則は「View をモックしない」こと。モックするのはデータ取得フックとルーターだけです。E2E は複数ページを跨ぐクリティカルフローだけに絞っています。この方針は仕組みでも守っていて、Container のテスト漏れは CI で、View の Storybook ストーリー漏れは lint で落ち、ストーリーは Chromatic のビジュアルリグレッションテストにつながっています。 ## ひとつのモック基盤を 3 つの用途で使い回す npm run dev:mock を叩くと、バックエンドなしで全 173 ページが動きます。MSW のようなライブラリは使わず、各 Repository が shouldUseMock() で分岐してモックデータを返すだけの素朴な仕組みです。この基盤をローカル開発・Chromatic・E2E で共用しており、CI の E2E もモックビルドで実行するためバックエンドの状態に左右されません。 開発中は、API の定義はあるものの実際にどんなレスポンスが返ってくるかわからず、API サーバーにリクエストしても応答が返ってこないまま画面を実装する場面が多くありました。このモックの仕組みは、表示部分を先に作り切るうえでとても役に立ちました。 ## AI エージェントと開発する Cycloud Platform Console を実装しているのは 2 名です。この人数で 12 サービス分・173 ページを回せているのは、開発フローに AI エージェント(Claude Code)を深く組み込んでいるからです。 **ルールの機械可読化。** リポジトリには開発ルール群(.claude/rules/)があり、「ラベル UI は共通コンポーネントを使う」といった規約を AI がそのまま読める形で明文化しています。各ルールは評価コマンドを持ち、AI が自分の成果物を自己採点できる「ルーブリック」になっています。 **定型作業のスキル化。** テスト作成、Storybook ストーリー生成、Issue 起票などは 12 のカスタムスキルに型化し、誰が(どのエージェントが)やっても同じ品質になるようにしています。 **GitHub Actions への AI 常駐。** Issue を起票すると AI が自動でトリアージし、PR には AI コードレビューが走ります。修正要求は最大 3 サイクルまでで、超えると needs-human ラベルで人間にエスカレーション。CI が落ちた場合は、エージェントが作った PR に限って自動修正も走ります。 Issue 起票 → AI トリアージ → 実装 → CI → AI レビュー ⇄ AI 自動修正(最大 3 サイクル) └ 超過したら needs-human で人間へ 「Issue 起票 → トリアージ → 実装 → CI → レビュー → 修正」までが半自律で回っており、claude[bot] 名義のコミットはすでに 21 あります。人間の仕事は、要件を Issue に落とすことと最終判断のレビューに寄りつつあります。前節までの lint やテストの強制チェック群は、実は AI に安心して書かせるための安全網でもあります。 ## ドメイン知識ゼロで IaaS の画面を作った話 いちばん過酷だったのは、新リージョンの提供開始に向けて Compute・Networking・Load Balancing の画面を作った 2026 年前半です。API が揃うのは 4〜5 月ごろ。それを待たずに API の開発と同時並行で実装する、工数にもスケジュールにも余裕のないプロジェクトでした。しかも私たちはフロントエンドエンジニアで、VPC やロードバランサーといったネットワークのドメイン知識はほぼゼロ。仕様を聞いたり調べたりする時間も取れず、頼れるのは Protocol Buffers の API 定義だけでした。 救いになったのは、AI エージェント導入の早さです。Claude Code を導入したのは 2025 年 5 月 30 日。Claude Sonnet 4 が出た直後、エージェントコーディングが世の中に広まる前で、数日後には GitHub Actions のワークフローにも組み込んでいます。組織のなかでもかなり先行してこの開発スタイルに挑戦していたチームだと思います。 進め方はこうです。TypeScript の型定義と、バリデーションルールの書かれた Protocol Buffers のファイルを AI エージェントに読ませ、ドメイン知識がいちばん要求されるリソース作成まわりの実装を任せる。バックエンドやインフラのエンジニアにヒアリングすることなく、「API と疎通して正しくリソースを作れる」という意味での品質をかなりの水準で担保でき、この物量をスケジュール内に作り切れました。 一方の「見た目の品質」を支えたのが Cloudscape でした。整備されたガイドラインをそのまま AI のコンテキストに入れられる。「デザインシステムのドキュメントが AI への指示書になる」という予想外の副産物で、品質を保ったままページを量産できました。Cloudscape を採用していたことで、AI エージェントを使ったコーディングでも一定の品質を担保できたと感じています。 ## v1.0 に向けて Cycloud Platform Console はまだ v0.x です。v1.0 の条件ははっきりしていて、AKE コンソールと ML Platform コンソールがこのコンソールへ移行を終えたとき、と考えています。 バグや機能追加の Issue もまだたくさんあります。いま考えているのは、開発をさらに加速させるための仕組み作りです。Issue が起票されたら Hermes Agent などを使って AI が自動で実装に入り、仕様のすり合わせや動作確認は起票者自身が責任を持つ。フロントエンドエンジニアは Issue の意図を読み解く作業から解放され、見た目のレビューとコードレビューに専念する。そんなふうに責務を分けられれば、開発のスピードはさらに上がるはずです。 CIU のフロントエンド(UI/UX セクション)は、AI 活用の番付があるなら横綱級を目指しています。そんな未来を描きながら、日々の開発に取り組んでいます。 ## おわりに Cycloud Platform Console の 16 ヶ月を、歴史・機能・技術・開発スタイルの面から紹介してきました。振り返っていちばん大きいのは、AI エージェントで開発スピードが、正直、爆発的に変わったことです。ただ、それを支えているのは、Cloudscape のガイドライン、型で仕様がわかる SDK、機械強制のクリーンアーキテクチャとテストといった「AI に安心して書かせるための土台」でした。2 名のチームで 10 サービス・173 ページを作って運用できているのは、この積み重ねのおかげだと思っています。 Cycloud Platform Console はいまも毎週のようにリリースを重ねながら、バラバラだったコンソールを 1 つにまとめきる v1.0 を目指しています。2 名 + AI エージェントという体制でコンソールを作ってきた試行錯誤が、同じように少人数で大きなプロダクトに向き合う方の参考になれば嬉しいです。 リリースに向けて協力してくださったすべての方に、この場を借りて感謝申し上げます。最後まで読んでいただき、ありがとうございました。

Cycloud 新基盤の全貌第8回: FrontEnd 編

背景や根拠まで確認しますか？

関連記事

調べる

選ぶ

サイト