Guide/guides

Why Guren

このページでは、Hono・Next.js・AdonisJS・Laravel と比べたときの Guren の立ち位置と、Guren が今の設計になっている理由を、長所も短所も含めて整理します。

Why Guren

要約

認証、データベース、フォーム、バックグラウンドジョブ、メールまで備えたフルスタックアプリを、1 つの TypeScript コードベースで、端から端まで型を通して組み立てたいなら Guren が向いています。
小さなステートレスの API サービスを作りたく、それ以外に何も要らないなら 素の Hono が向いています。
マーケティングサイト、EC のストアフロント、React Server Components を軸にしたアプリのように、コンテンツが中心で React のレンダリングが主役のプロダクトなら Next.js が向いています。

Guren はさらに、多くのフレームワークが手を付けてこなかった領域にも力を入れています。AI コーディングエージェントがプロジェクトを理解し、拡張し、検証しやすくすることです。詳しくは次の節で説明します。

AI コーディングエージェントのために

多くのフレームワークは、ドキュメントを読む人間を相手に設計されてきました。Guren はそれに加えて、リポジトリの中で作業するエージェントも相手に設計しており、新しく作ったアプリは最初からその状態になっています。secure by default と同じ考え方で、agent-ready by default を目指しています。違いを生んでいる性質は次の 3 つです。

プロジェクトを安く把握できます。 bunx guren context を実行すると、ルート・モデル・コントローラー・ページをまとめた小さな地図が出力されます(--json を付ければ機械可読の形式になります)。エージェントはディレクトリツリーをたどり歩かなくても、コマンド 1 つでプロジェクトを正確に理解できるので、コンテキストウィンドウは小さく、前提は正確なまま保てます。データモデルについては、bunx guren model:list が同じ役割を持ちます。

規約で迷う余地が減ります。 コントローラーは app/Http/Controllers、モデルは app/Models、ページは resources/js/pages に置き、bunx guren make:feature Post --fields "title:string,body:text" を実行すれば、形のそろった CRUD 一式がスキャフォールドされます。どのコードにも置き場所と形が 1 つずつしかなければ、生成したコードが最初から正しい場所に収まることがずっと多くなります。

間違いはレビューに頼らず機械が見つけます。 エージェントが書いたコードは、互いに独立した 3 つのゲートで検証します。

bunx guren check    # ルート ↔ コントローラー ↔ ページの整合性
bunx guren audit    # 変更系ルートのバリデーション/認証漏れ、生SQL、シークレット
bun run typecheck   # 型付き page props とルート契約のズレはビルドが落ちる

ページの props、ルートパラメータ、リクエストボディはどれも型付きの契約です。そのため、エージェントが存在しない props 名をでっち上げたり、バリデーションスキーマを付け忘れたりすると、diff を 1 行も読まないうちにコンパイルエラーか check の失敗として表に出ます。

こうして、読み込むコンテキストは少なく、間違える余地は小さく、できあがったものは機械で検証される状態になります。この「把握、生成、検証」のループがあるので、Guren でのエージェント駆動開発は、うまくいくことを祈るものではなく、当てにできるものになります。

仕様がコードからずれないようにもしています。 Guren はプロジェクトの知識を、導出できるものは導出し、できないものは宣言し、常に検証する(derived where possible, declared where not, checked always) という 1 つの原則で扱います。ER 図・ドメインモデル・画面一覧はコードから生成し(bunx guren spec:generate)、CI のドリフトゲートで守ります。コードでは表せない意思決定は ADR に残し、frontmatter で対象のモデルにリンクして、変更のたびに検証します。bunx guren context Invoice を実行すると、そのエンティティについてプロジェクトが知っていることが、紐付いたドキュメントも含めてすべて、人間にもエージェントにも渡されます。その時点で、リンクが切れていないことと導出したビューが最新であることは、チェッカーが確かめています。全体の流れはスペックアンカード開発を参照してください。

効果は計測で確かめています。 Agents on Guren は、バグ修正・セキュリティ・機能追加の 20 タスクを、エージェントからは見えない受け入れテストで採点する評価です。3 つのモデルそれぞれについて、scaffold に同梱のハーネスがある場合とない場合を走らせ、合計 360 ランを実行しました。各ランの patch、ログ、判定はすべて公開しています。Sonnet 5 では、ハーネスありが 60 ラン中 60 ラン、なしが 58 ラン合格し、ハーネスありのほうがターン数は 28%、コストは 25% 少なく済みました。Opus 5 はどちらも 60 ラン中 60 ラン合格で、差はターン数 26% 減、コスト 12% 減として出ました。Haiku 4.5 では合格率そのものが 51/60 から 54/60 へ上がりましたが、コストは 6% 増えています。guren check を実際に実行したランは、ハーネスありで 180 ラン中 119 ラン、なしでは 15 ランでした。ハーネスが逆効果になったケースもレポートに載せています。この評価の過程で、@guren/orm の paginate() が eager loading を落とすバグも見つかり、すでに issue を起票しました。

Hono との比較

Guren の HTTP レイヤーは Hono そのものです。すべてのリクエストが Hono のルーターを通るので、性能も Hono と同じ水準を保てます。Guren が足しているのは上に載る薄い MVC レイヤーで、新しいサーバーを作っているわけではありません。

Hono があえて持たないものを、Guren は同梱しています。

必要なもの	素の Hono	Guren
データベースアクセス	ORM を選んで自分で配線	Drizzle ベースの `Model.where().orderBy().get()` が最初から使える
バリデーション	ハンドラーごとにスキーマライブラリを呼ぶ	`this.validateBody(schema)` で 422 レスポンスまで返せる
認証	セッション・ハッシュ・ミドルウェアを自分で組み立てる	`bunx guren add auth` でフロー一式をスキャフォールド
フロントエンド	別に作った SPA と手書きの API レイヤー	Inertia 経由の React ページに型付き props
ジョブ・メール・イベント・キャッシュ	ライブラリを選んで組み込む	組み込みのサブシステム(プロバイダーでオプトイン)
テスト	ハーネスを自作	fluent なアサーションを備えた `TestApp`

JSON のエンドポイントが数個あれば済むサービスなら、素の Hono は優れた選択です。Guren の中身も Hono なので、Hono で始めたものを Guren に移すときも、書き直しではなく自然に育てていく形になります。差が出てくるのはアプリが大きくなってからです。上の表の各行は、Guren を使わなければ自分で書き、テストし、保守し続けることになるグルーコードです。

Next.js との比較

Next.js と Guren は、そもそも答えようとしている問いが違います。Next.js は React ファーストで、中核の抽象はレンダリング戦略(RSC、ストリーミング、ISR)にあり、バックエンドはフロントエンドから育っていきます。一方の Guren はサーバーファーストで、Laravel の系譜に連なる MVC アプリケーションです。React は Inertia を通じて届けるビューレイヤーという位置付けです。

この違いは、機能の作り方に表れます。

考え方のモデルは 1 つで済みます。 機能はルート・コントローラー・モデル・ページでできています。クライアントコンポーネントとサーバーコンポーネントの境界を考える必要も、'use client' を付けるかどうか迷う必要もなく、データと React の props の間に API ルートの層を挟むこともありません。
データの受け渡しを手で書かずに済みます。 コントローラーは型付きの props をそのままページコンポーネントへ渡します。データベースのカラム名を変えれば、モデルから React のページまで TypeScript のエラーが順に出て、直す場所を教えてくれます。
バックエンドの機能がフレームワークに入っています。 キュー、スケジュールジョブ、メール、ブロードキャスト、ポリシーはフレームワークのサブシステムとして用意されており、レンダリングフレームワークの周りにサードパーティのサービスを寄せ集める必要はありません。

コンテンツの多いサイト、コンポーネント単位の細かいストリーミング、RSC のエコシステムに深く乗っているチームのように、サーバーでレンダリングした React そのものがプロダクトである場合は、引き続き Next.js が向いています。

AdonisJS との比較

AdonisJS は、TypeScript の世界にあるもう 1 つのバッテリー同梱型 MVC フレームワークで、優れた選択肢です。Laravel のアーキテクチャを Node.js で使いたいなら、まず候補に挙がります。Guren は、次の 2 点で AdonisJS と違う方向に賭けています。

Node ではなく Bun で動きます。 同じ仕様のアプリ同士で測ったベンチマーク（フレームワーク比較リポジトリにある Inertia SSR の実装 2 つ）では、Guren のスループットは SSR のページで 2.3 倍、JSON の経路で 3.5 倍、コールドスタートは 1.8 倍高速でした（計測方法とワンクリックでの追試手順はこちら）。アプリのコードは同じなので、この差はランタイムの差です。アーキテクチャはそのままで、エンジンだけが替わるという点がポイントです。Bun を選んでもデプロイ先は縛られません。AWS Lambda・Vercel・Cloudflare Workers 向けの公式プラグインがあり、guren.dev 自体も Workers 上で動く Guren アプリです。
部品は独自に作らず、TypeScript エコシステムの定番を使います。 AdonisJS は独自の ORM（Lucid）やバリデータ（VineJS）を持っています。Guren はエコシステムですでに標準になっている部品（Drizzle、Zod、Vite、Inertia）を組み合わせ、その上に規約を載せています。同じ仕様のアプリを実装したところ、保守対象のコードは Guren が 991 行 / 38 ファイル、AdonisJS が 2,438 行 / 68 ファイルで、直接の依存は 17 対 43 でした。

手で打つ量はほぼ同じです（どちらもスキャフォールドがよくできていて、手書きしたのは約 570 行と 600 行）。どちらを選ぶかは、ランタイムと、どのデータ層を使いたいかで決まります。

Laravel・Rails との比較

Laravel や Rails を使ったことがあれば、Guren にはすぐ慣れるはずです。コントローラー、モデル、ミドルウェア、ポリシー、リソース、ジョブ、make:* ジェネレーターは、どれも想像どおりに動きます。違うのは言語の境目で、Guren ではその境目がなくなります。

端から端まで 1 つの言語で書けます。 バックエンドとフロントエンドの間で PHP と JavaScript を行き来することはありません。バリデーションスキーマも、モデルも、ページの props も、すべて TypeScript です。
型がサーバーとブラウザの境目を越えます。 Laravel と同じような開発体験に、静的な保証が加わります。コントローラーが送る props と React のページが宣言する props が一致しているかは、コンパイラが検査します。
ランタイムがモダンです。 Bun は TypeScript をそのまま実行するので、開発時のトランスパイルが要らず、起動も速く、テストランナーも組み込まれています。

Guren を選ぶべきでないとき

どんな場面でも正解になるフレームワークはありません。次のような場合は、別の選択肢を検討してください。

プロダクトがレンダリング中心の場合。 コンポーネント単位のストリーミング SSR、きめ細かいキャッシュ、RSC のエコシステムは Next.js が得意とする領域です。
とにかく小さなサービスが欲しい場合。 Webhook のレシーバーやエッジファンクションに MVC は要らず、素の Hono のほうが軽く済みます。
チームが Bun で開発できない場合。 Guren は Bun ファーストで設計しており、開発サーバー・テストランナー・CLI は Bun を前提にしています。デプロイ先は選べて、AWS Lambda・Vercel・Cloudflare Workers 向けの公式プラグインもありますが、開発マシンで Bun を使えないなら、別のフレームワークのほうが合っています。

次のステップ

クイックスタート: 5 分ほどでプロジェクトを作って起動します。
First Steps: 1 つのリクエストがすべてのレイヤーを通る流れを 10 分で追います。
アーキテクチャ: ルーティング、コントローラー、モデル、Inertia がどう組み合わさるか。
CLI リファレンス: エージェントが使う検査コマンドを含む、全コマンドの一覧。