vibe-to-agentic-framework

「バイブコーディングからエージェント型エンジニアリングへ」のフレームワーク

このスキルでは、プレゼンテーションの概念モデルを説明します。すべてのスライドとセクションは、ひとつのストーリーを伝えるためのものです。開発者が、構造化されていない「バイブコーディング」（低レベル）から、高度なエージェント型エンジニアリング（高レベル）へと段階的に移行する過程です。

コアコンセプト

**バイブコーディング（低レベル）**とは、開発者が構造のない状態で Claude Code を使うことです。プロジェクトのコンテキストも、規約も、再利用できる知識もありません。プロンプトを入力するたびに、結果は運任せです。Claude は場当たり的なエンドポイントを作成したり、既存のパターンを無視したり、テストを省略したり、一貫性のないコードを生成したりする可能性があります。やり取りを重ねるたびに、コードベースはエントロピーの増大に向かいます。

**エージェント型エンジニアリング（高レベル）**とは、Claude Code が完全に構成されたエンジニアリングシステムとして動作する状態です。プロジェクトのアーキテクチャ（CLAUDE.md）を理解し、対象を絞った規約（Rules）に従い、必要に応じてドメインの専門知識（Skills）を読み込み、専門のワーカー（Agents）に作業を委任し、複数ステップのワークフロー（Commands）を調整し、ライフサイクルイベント（Hooks）を自動化し、外部ツール（MCP サーバー）に接続します。どのプロンプトからも、一貫性があり、テスト済みの、本番品質のコードが生成されます。

この両極端の間の道のりは、段階的かつ累積的です。それぞれのベストプラクティスは前のものを土台とし、プレゼンテーションでは、開発者が取り入れるべき順序で説明します。

4段階の道のりのシステム

プレゼンテーションでは、パーセンテージバーの代わりに4段階のスコアリングシステムを使用します。

レベル	順序	色	道のりバーの高さ	説明
低	1	赤／オレンジ（hsl(0, 70%, 45%)）	25%	バイブコーディングの領域 — 構造なし
中	2	黄色（hsl(40, 70%, 45%)）	50%	構造化されたワークフロー、一部自動化
高	3	ライトグリーン（hsl(80, 70%, 45%)）	75%	ドメイン知識、スキル、カスタムエージェント
プロ	4	ディープグリーン（hsl(120, 70%, 45%)）	100%	完全なエージェント型エンジニアリング、マルチエージェントチーム

道のりバーはスライド1（タイトルスライド）では非表示で、スライド2以降に表示されます。レベルは主要な遷移スライドの data-level 属性で設定され、次のレベル変更まで後続のスライドに引き継がれます。レベルが変わると、スライドの h1 に .level-badge が JS によって挿入されます（これらを HTML にハードコードしないでください）。

継続的な例：TodoApp モノレポ

各手法は、現実的なフルスタックプロジェクトを題材にして説明します。プレゼンテーションでは、単純なプロジェクト（バイブコーディング）から、Claude Code の設定がすべて整ったプロジェクト（エージェント型エンジニアリング）への変化を示します。

導入前（バイブコーディング）：

todoapp/
├── backend/          # FastAPI (Python)
│   ├── main.py
│   ├── routes/
│   ├── models/
│   └── tests/
└── frontend/         # Next.js (TypeScript)
    ├── components/
    ├── pages/
    └── lib/

導入後（エージェント型エンジニアリング）：

todoapp/
├── .claude/                  # Claude Code config
│   ├── agents/               # Custom subagents
│   ├── skills/               # Domain knowledge
│   ├── commands/             # Slash commands
│   ├── hooks/                # Lifecycle scripts
│   ├── rules/                # Modular instructions
│   ├── settings.json         # Team settings
│   └── settings.local.json   # Personal settings
├── backend/
│   └── CLAUDE.md             # Backend instructions
├── frontend/
│   └── CLAUDE.md             # Frontend instructions
├── .mcp.json                 # Managed MCP servers
└── CLAUDE.md                 # Project instructions

なぜ TodoApp なのか？ スライドに収まるほど小さい一方で、現実の問題を示せるだけの複雑さがあるためです。ルートのパターンとテスト規約を備えたバックエンド、コンポーネント階層とデザイントークンを備えたフロントエンド、そして新機能の追加など、横断的な課題への対応に両側の連携が必要となるモノレポ構造があります。

TodoApp によって、バイブコーディングの問題が具体的になります。構造がない状態で Claude に「メモ機能を追加して」と頼むと、routes/todos.py のパターンに従わない場当たり的な /api/notes エンドポイント、サイドバーナビゲーションのない単独ページ、そしてテストがひとつもない状態が生成されます。エージェント型の構成をすべて整えると、同じ依頼から、既存のパターンに従ったルート、サイドバーに統合されたページ、test_todos.py のスタイルに合ったテストが生成されます。

道のりの流れ：この順序にする理由

プレゼンテーションでは、意図的に組み立てられた教育的な順序に沿って進みます。各セクションで、新たな機能レイヤーを利用できるようになります。

パート 0：はじめに（スライド 1～4、重み付けなし）

目的： 導入を行います。TodoApp を紹介し、バイブコーディングを定義して、目指す状態を示します。

• タイトルスライドで、旅のメタファーを提示します
• サンプルプロジェクトで変化を示します。TodoApp の変更前と変更後を比較し、シンプルなプロジェクト構成と、完全な Claude Code 設定（.claude/、CLAUDE.md、.mcp.json など）を備えた構成を比べます
• 「バイブコーディングとは？」で、0％の出発点となる課題を示します
• ジャーニーマップで、これから進む全体の道筋を示すクリック可能な目次を提供します

パート 1：前提条件（スライド 5～9、重み付けなし）

目的： Claude Code をインストールして使える状態にします。ここでは実務的な準備のみを扱い、エンジニアリングの実践方法はまだ扱いません。

• インストール、認証、最初のセッション、インターフェースの概要
• ツールのインストール方法を知っていてもコードの品質は向上しないため、重み付けはありません
• 「最初のセッション」はバイブコーディングそのものです。開発者が0％の状態を実際に体験できるよう、意図的にそうしています

パート 2：より良いプロンプト（スライド 10～17、レベル：低）

目的： 最初の本格的な改善です。プロジェクト設定がなくても、入力の質を上げれば出力の質が向上します。

• 良いプロンプトと悪いプロンプト： 具体的で範囲を絞ったプロンプトと、曖昧な依頼を比較します。最も簡単にできる改善です。
• コンテキストの提供： @files を使って、Claude に必要なコードを渡します。ハルシネーションをすぐに減らせます。
• コンテキストウィンドウと /compact： 有限のコンテキストウィンドウについて理解することで、長いセッションで応答の質が低下するのを防ぎます。
• プランモード： /plan によってコーディング前に思考を促し、誤ったアプローチによる無駄な作業を防ぎます。

レベルが低い理由： プロンプトは基礎となるものですが、効果には限界があります。個々のやり取りは改善しますが、プロジェクトに永続する知識は生まれません。セッションのたびにゼロから始まります。

パート 3：プロジェクトの記憶（スライド 18～24、レベル：中）

目的： セッション単位の知識からプロジェクト単位の知識へと飛躍させます。Claude がセッションをまたいで記憶できるようになります。

• CLAUDE.md と /init： プロジェクトについての「Claude 向け README」です。アーキテクチャ、技術スタック、規約を定めます。最も大きな効果をもたらすファイルです。
• 含める内容： 効果的な CLAUDE.md の書き方に関する実践的なガイダンスです（150行未満に抑え、Claude が知っておくべきことに絞ります）。
• ルール： .claude/rules/ でパスごとの規約を定義します。ルールは効果を倍増させ、該当する各ファイルに自動的に適用されるため、開発者が手間をかけなくても一貫性を保てます。backend-testing.md というルールを1つ用意すれば、すべてのテストに同じパターンを恒久的に適用できます。

レベルが中の理由： プロジェクトの記憶により、Claude は状態を持たないツールから、コンテキストを理解する協力者へと変わります。ただし、知識だけではワークフローは生まれません。

パート 4：体系的なワークフロー（スライド 25～28、レベル：中）

目的： 無駄な作業を防ぎ、実行の質を向上させる体系的なアプローチを学びます。

• タスクリスト： 複雑な作業を追跡可能な手順に分割します。作業範囲の逸脱を防ぎ、漏れなく完了できるようにします。
• モデルの選択： 適切なモデルを選ぶことで、コストと品質を最適化します（アーキテクチャには Opus、実装には Sonnet、手早い作業には Haiku）。

レベルが中のままである理由： ワークフローは重要ですが、概念としては比較的シンプルです。パート 3 のプロジェクトの記憶を基盤として、より体系的に活用します。レベルが高くなるのは、ドメイン知識を扱う段階からです。

パート 5：ドメイン知識（スライド 29～33、レベル：高）

目的： 必要なときに利用できる、再利用可能な専門知識です。スキルは、静的なメモリ（CLAUDE.md／Rules）と動的なエージェントをつなぐ役割を果たします。

• スキルとは： Claude が関連する場面で読み込む、パッケージ化されたドメイン知識としてのスキルです。段階的開示の概念を説明します。
• スキルの作成： 実践編：TodoApp 用の frontend-conventions スキルを作成し、Tailwind のトークン、コンポーネントのパターン、サイドバーへの統合方法を教えます。
• スキルのフロントマターと呼び出し： 技術的な詳細として、YAML フロントマター、手動呼び出しと自動検出による呼び出し、context: fork オプションを説明します。

レベルが「高」である理由： スキルは最初の「乗数」となる概念です。1 つのスキル定義によって、そのドメインにおける今後のすべてのやり取りが改善されます。ただし、スキルは受動的な知識であり、能動的にするにはエージェントが必要です。

パート 6：エージェント型エンジニアリング（スライド 34～46、レベル：高）

目的： このプレゼンテーションで扱う到達点です。機能をエンドツーエンドで構築するために連携する、自律的で専門性の高いエージェントについて説明します。

• エージェントとは： 使用できるツールを制限し、スキルをあらかじめ読み込んだ、専門性の高いサブエージェントの概念です。
• フロントエンドエンジニアエージェント： TodoApp のフロントエンド規約を利用し、サイドバーにルートを追加して、デザイントークンに従う具体的なエージェントです。変化を示すために、使用前と使用後を比較します。
• バックエンドエンジニアエージェント： バックエンドを担当する並列エージェントです。FastAPI のルートパターンや SQLAlchemy モデルに従い、既存のスタイルに合わせてテストを作成します。
• コマンドとオーケストレーション： 総仕上げとなるパターンは「コマンド → エージェント → スキル」です。単一の /add-feature コマンドが、それぞれ独自のスキルを持つフロントエンドとバックエンドのエージェントを連携させ、完全な機能を提供します。これはアーキテクチャの到達点です。
• フックと MCP： ライフサイクルの自動化（コミット前チェック、サウンド通知）と外部ツールとの統合です。自動化の最終レイヤーです。
• コマンド → エージェント → スキル： アーキテクチャ全体を示す図です。コマンドがエージェントを呼び出し、エージェントがスキルを読み込み、スキルが知識を提供するという、すべての要素のつながりを示します。これが「レベル：高」の理解を示すスライドです。

レベルが「高」である理由： このセクションでは、このプレゼンテーションで扱う実践方法のうち、最も価値の高いものを取り上げます。それまでのすべての内容は、ここに向けた準備でした。オーケストレーションとエージェント型ワークフローは、このコースで扱う内容の上限です。完全な Pro（マルチエージェントチーム、高度なオーケストレーションパターン）は、このプレゼンテーションの範囲を超えています。

レベル「高」のスライド（スライド 44）

全体を振り返る場面です。TodoApp の設定一式を示します。

• プロジェクトのコンテキストを示す CLAUDE.md
• パスごとの規約を定義する Rules
• ドメイン知識を提供する Skills
• 一貫した実行を担う Agents
• オーケストレーションされたワークフローを担う Commands
• ライフサイクルの自動化を担う Hooks
• 外部ツールを利用する MCP サーバー

付録（スライド 47 以降、重みなし）

目的： 参考資料です。すべてのコマンド、設定、構成オプションを扱います。学習の節目ではなく、必要に応じて参照する情報のため、重みはありません。ツールの使用方法、すべてのスラッシュコマンド、コミット／PR のワークフロー、カスタマイズオプション、デバッグのヒント、重要なルールを含みます。

スライドを編集する際の、このフレームワークの使い方

スライドを作成または変更する際は、次の点を考慮してください。

1. この概念は、学習の流れのどこに位置しますか？ 「プロンプトのエラーメッセージを改善する」スライドは、Part 2（プロンプト、Low レベル）に該当します。「エージェントのメモリスコープ」に関するスライドは、Part 6（エージェント型、High レベル）に該当します。

2. 変更前と変更後はどうなりますか？ 重要なスライドではすべて、Low レベル（バイブコーディング）で何が起きるかと、この手法を使うとどうなるかの対比を、明示的または暗黙的に示してください。TodoApp を使って具体化しましょう。

3. レベルの割り当ては適切ですか？ レベルの移行は Part のセクション境界で行われます。セクション内の各スライドには、そのセクションのレベルが適用されます。

4. これまでの内容を踏まえていますか？ Skills は、開発者がすでに CLAUDE.md と Rules を理解していることを前提とします。Agents は Skills を理解していることを前提とします。Commands は Agents を理解していることを前提とします。各概念のセクションより前に、その概念に言及しないでください。

5. TodoApp を使いましょう。 抽象的な説明では、聴衆に伝わりにくくなります。実際の routes/todos.py コード、実際の Sidebar.tsx コンポーネント、実際の CLAUDE.md の内容を見せてください。この実例によって、フレームワークを具体的に伝えられます。

レベル移行の参照表

スライド	スライド名	data-level	レベルラベル
10	より良いプロンプト（セクション区切り）	data-level="low"	Low
18	プロジェクトメモリ（セクション区切り）	data-level="medium"	Medium
29	ドメイン知識（セクション区切り）	data-level="high"	High
34	エージェント型エンジニアリング（セクション区切り）	data-level="high"	High

その他のスライドには、その前に設定された最後の data-level 属性のレベルが適用されます。スライド 1～9（イントロ＋前提知識）にはレベルがなく、スライド 2 に「Low」が表示されるまでバーは非表示のままです（スライド 2～9 は最初のレベル移行であるスライド 10 より前のため、スライド 10 まではバーに空またはゼロが表示されます）。

注： メインプレゼンテーション（presentation/index.html）の上限は High レベルです。data-level="pro" は使用しません。Pro の目盛りは理論上の上限としてジャーニーバーに表示されたままですが、塗りつぶしがそこに達することはありません。動画プレゼンテーション（1-video-workflow.html）の上限は Medium レベルです。