---
title: AI 支援開発のために構築
order: 3
icon: phosphor-duotone:robot
summary: cbGenesis から始めることが、ブランクリポジトリから AI エージェントに認証、RBAC、管理パネルを構築させるよりも、測定可能な形でトークン数を削減し、より一貫性のあるコードを生み出す理由。
tags: [ai, agents, skills, productivity]
---

# AI 支援開発のために構築

今日、本格的なアプリはすべて、どこかしらで AI コーディングエージェントを使って構築されています。問題は、エージェントを使うかどうかではなく、そのエージェントが空のリポジトリから始まり、毎回セッションごとにあなたの規約を*推測*しなければならないのか、それとも、物事がどのように行われるべきかをすでに正確に伝えてくれるコードベースから始まるのか、ということです。

cbGenesis は後者のために構築されています。

## 「とりあえず AI で作らせる」の本当のコスト

エージェントに空の ColdBox アプリを渡して、認証、RBAC、管理パネル、CSRF 保護、そしてテストスイートを要求すると、それはエージェントの時間だけでなく、トークンと一貫性のコストもかかります。土台となるコードベースがなければ、エージェントは次のようになります。

- 空のプロジェクトを調べ、何も見つからず、独自の規約を発明するか、あるいはあなたに山ほどの確認質問をしてきます。
- セッション認証、CSRF 検証、権限チェックといった、同じセキュリティ上重要な配管を毎回作り直しますが、ここで実際のインシデントを通じて発見された微妙な部分(ローテーション期間、デフォルト拒否のチェック、自己操作のガード)を正しく実装できる保証はありません。
- 模倣すべきものが何もないため、書くファイルごとに少しずつ前のファイルからずれていきます - 2 週間離れて作られた 2 つの機能が、まるで異なるコードベース由来のように見え始めます。

cbGenesis は、これらすべてをすでに構築済み、テスト済み、そして - AI エージェントにとって決定的に重要なことですが - **人間が指示に翻訳しなければならない散文ではなく、機械可読なスキルとして文書化**した状態で提供します。

## エージェント向けに特に提供されるもの

- **`AGENTS.md`** - リポジトリルートに配置され、ほとんどのエージェントツール(Claude Code、Copilot、Cursor など)が自動的に読み込む唯一のファイルで、エージェントがコードを書く前に、アプリの構造、ハンドラー、インターセプター、規約を説明します。
- **90 以上のフレームワークスキル** - ColdBox CLI によって自動インストールされ、BoxLang、ColdBox、CommandBox、TestBox、WireBox、そしてバンドルされたすべてのモジュール(cbSecurity、cbORM、qb、cbMailServices)をカバーします。現在の API を反映していないかもしれない学習データから推測する代わりに、エージェントが必要に応じて読み込む、段階的な実装パターンです。
- **cbGenesis 独自の 6 つのスキル**(`.agents/skills-custom/`) - フレームワークスキルでは*わからない*、このアプリ独自の `resource:action` 権限モデル、その `fetchWithCsrf()` フロントエンド契約、新機能がここで従う正確なエンティティ/サービス/ハンドラー/ルート/コンポーネントの形、実際のテスト分離メカニズム、そして環境変数対データベース設定の使い分けを捉えています。全リストは [アプリの拡張](guides/extending.md) を参照してください。
- **すべてのフレームワークとモジュールに対応したライブ MCP ドキュメントサーバー** - エージェントが学習カットオフに頼るのではなく、最新のドキュメントを確認できます。

これは「プロンプトエンジニアリング」の小技ではありません。新しい人間の採用者をより早く生産的にするのと同じことです - コピーする価値のある規約を持つコードベースと、それらを見つける場所の地図です。

## 主張するだけでなく、実際に測定しました

AI の生産性に関する主張は安っぽいものです。そこで私たちは、数字を主張するだけでなく、実際に再現可能なテストを行いました。

**タスク:** この cbGenesis コードベースそのものに、完全な CRUD リソース(「Tags」)を追加する - ORM エンティティ、サービス、権限で保護された JSON ハンドラー、ルート、そして正しい CSRF 処理を行う Alpine.js フロントエンドコンポーネントです。同じ十分に定義されたタスクを、同じコミット、同じモデルで、2 つの独立したエージェントに与えました。

**条件 A - 探索のみ。** このエージェントには、cbGenesis のカスタムスキルを一切参照しないよう指示され、規約を自力でリバースエンジニアリングしなければなりませんでした。どのファイルが権限フォーマットを定義しているか、既存のハンドラーが JSON レスポンスをどう形作るか、フロントエンドが古い CSRF トークンからどう復旧するか、ルートがどこに登録されるか、などです。

**条件 B - スキル支援。** このエージェントには最初に 3 つの関連するカスタムスキル(`cbgenesis-crud-resource`、`cbgenesis-csrf-frontend`、`cbgenesis-rbac-permissions`)が示され、その内容に基づいて直接実装しました。

両方のエージェントとも、完全に動作する縦割りのスライスを作り上げました。かかったコストは次のとおりです。

| | 探索のみ | スキル支援 |
|---|---|---|
| **トークン数** | 129,672 | **113,995** |
| **ツール呼び出し回数** | 38 | **22** |
| **実時間** | 208 秒 | **137 秒** |

これは、同一スコープに対して **トークン数で 12% 削減**、**ツール呼び出し回数で 42% 削減**、**時間で 34% 削減**という結果で、1 回の測定実行によるものです。トークン数の差はこの勝利を過小評価しています。エージェントの呼び出しにはそれぞれ、両条件で同一の大きな固定オーバーヘッド(システムプロンプト、ツール定義)が伴うため、この削減のほぼすべてが*タスク固有*の作業 - つまり実際に探索なのか、直接実行なのかという部分から来ているのです。

**方法論について正直に言うと:** これは条件あたり 1 回の実行であり、平均化されたベンチマークではないため、正確なパーセンテージは保証ではなく方向性として捉えてください - タスクの複雑さやモデルによって結果は変わります。両条件とも、cbGenesis のベースラインとなる `AGENTS.md` のプロジェクト概要は利用可能でした(ほとんどのエージェントツールがこれを自動的に読み込み、それを隠すきれいな方法もありません)。そのため「探索のみ」の条件も*完全な*暗闇から作業していたわけではなく、それでも具体的な実装パターンは自力で見つけなければなりませんでした。私たちの言葉を鵜呑みにするのではなく、あなたが気にかけているタスクで自分自身で比較してみてください。

ツール呼び出し回数の差の方が、より雄弁な数字です。38 対 22 は「エージェントが少し考えなくなった」という話ではなく、*コードベースの半分を読んでパターンを見つける*ことと、*パターンをそのまま読む*ことの違いです。

## トークンを超えたケース

トークンは測定しやすいものです。より定量化しにくい勝利は、*起こらなくなること*です。cbGenesis の上にログインフロー、権限チェック、または CSRF で保護されたフォームを構築するエージェントは、実際のミス(古い CSRF トークンがユーザーの入力を静かに破棄してしまう、権限の関連付けが静かにクリアされなくなる、自己操作ガードが一貫性なく適用される)に対してすでに強化されたパターンを継承します - これらはこのプロジェクトが実際に犯し、修正し、そしてスキルにエンコードした過去のミスであり、あなたのプロジェクトでエージェントが再び同じミスをすることはありません。

「AI でゼロから」構築するということは、これらの教訓のすべてを、プロジェクトごとに、苦労して再学習しなければならないということです。cbGenesis から始めるということは、それらがすでに支払い済みであるということです。

## 次に読むべきもの

::: cards
::: card title="はじめに" icon="phosphor-duotone:rocket-launch" href="getting-started.md"
インストール、設定、マイグレーション、そしてローカルでのアプリ実行。
:::
::: card title="アプリの拡張" icon="phosphor-duotone:puzzle-piece" href="guides/extending.md"
カスタムスキルを文脈の中で見てみましょう - それらが何をカバーしているか、そしてアプリの成長に合わせて独自のスキルを追加する方法。
:::
::: card title="セキュリティと権限" icon="phosphor-duotone:shield-check" href="guides/security.md"
`resource:action` モデル、CSRF、そして上記のスキルがエンコードしている規約。
:::
:::