Vibe Codingの挫折から学ぶ、AI駆動開発の新常識 ― 非エンジニアのためのコンテキストエンジニアリング入門

ChatGPT や Claudeのようなツールのおかげで、「自然言語でお願いしたら、それっぽいコードが一瞬で出てくる」という世界になりました。

いわゆる「Vibe Coding」――雰囲気で仕様をしゃべりながら、その場で AI にコードを書せるスタイルです。

私は、Lovableなどいろんなツールで試してみました。簡単なスクリプトや個人用ツールなら、これで十分動くものができます。

しかし、少し複雑な Web サービスや業務システムを作ろうとした瞬間、大きな壁にぶつかりました。

• 何度言っても、同じ間違いを繰り返す

• バグ修正を頼んでも、別の場所で別パターンのバグを生む

• プロンプトでルールを書き足し続けた結果、会話がカオスになって破綻する

「貼って→直して→また壊れて→堂々巡り」で、開発が止まってしまうのです。

この現象は、プロンプトが悪いからではありません。

原因はシンプルで、 LLM（大規模言語モデル）が一度に覚えておける情報量の上限、いわゆる「コンテキストウィンドウ」という記憶領域の限界があるからです。

この「コンテキストウィンドウの限界」を無視して、ひたすら長文プロンプトを積み増すやり方は、最初から負け戦だったわけです。

では、どうすればこの「記憶の限界」という根本的な制約と上手く付き合い、AIを真のパートナーにできるのでしょうか。

本稿では、その答えが「コンテキストエンジニアリング」という新しい設計思想にあることを、私の実体験を交えながら共有します。それは、AIとの対話を「その場限りの会話」から、重要なルールや設計図を外部ファイル（＝憲法）として共有する「継続的な共同作業」へと変革するアプローチです。

この記事が、AIとの「堂々巡り」から抜け出し、ご自身のアイデアを形にするための、その第一歩となれば幸いです。

1. なぜコンテキストウィンドウに上限が生まれるのか

1-1. 問題の核心：なぜAIは「忘れる」のか？

序文では、Vibe Codingの挫折体験を通して、AI開発が失敗する根本原因が「コンテキストウィンドウ」という記憶の限界にあることを述べました。

では、なぜAIの記憶には、これほど厳格な上限が設けられているのでしょうか？ なぜ、もっと大量の情報を一度に処理することができないのでしょうか。

その答えは、AI（ソフトウェア）の仕組みだけに留まりません。実はこの問題は、現代のほぼすべてのコンピュータが採用している「ハードウェアの根本的な設計」、その設計とAIの仕組みの「相性の悪さ」、そして越えがたい「物理的な限界」が複雑に絡み合って発生しているのです。

この根本原因を理解することが、次章で登場する「コンテキストエンジニアリング」がなぜ有効な解決策となり得るのかを深く知るための、重要な鍵となります。

1-2. 原因その1：コンピュータの「根本的な設計」

AIの記憶の限界を理解するための最初のステップは、意外にもAIそのものではなく、AIが動いている「コンピュータ」の根本的な設計にあります。

私たちが日常的に使うPCやスマートフォン、そしてAIが動くデータセンターのサーバーまで、現代のほぼすべてのコンピュータは「フォン・ノイマン・アーキテクチャ」と呼ばれる約80年前の設計図を基礎にしています 。

1-2-1. コンピュータの基本構造「フォン・ノイマン・アーキテクチャ」

この設計の最大の特徴は、「計算する場所（プロセッサ、GPU）」と「記憶する場所（メモリ）」が物理的に分離していることです 。

これは、料理に例えると非常に分かりやすいです 。

• 計算装置（GPU） ＝ 調理台

• メモリ（記憶装置） ＝ 冷蔵庫

フォン・ノイマン型のコンピュータは、「調理台（計算）」と「冷蔵庫（記憶）」が5メートルも離れているキッチンのようなものです 。

料理人（計算装置）がどんなに素早く調理（計算）できても、材料（データ）が必要になるたびに、わざわざ5メートル離れた冷蔵庫（メモリ）まで歩いて取りに行き、また戻ってくる必要があります 。複雑な料理（AIの処理）になればなるほど、この往復回数は膨大になります 。

1-2-2. なぜ「データ転送の遅さ」が決定的な問題になるのか？

ここで決定的な問題となるのが、「計算の速度」と「データ移動の速度」の圧倒的な差です。

• 計算（GPU内部）は超高速（例：1秒間に1000兆回計算できる）

• データ移動（メモリ往復）は相対的に超低速

この「調理台」と「冷蔵庫」をつなぐ通路は「メモリバス」と呼ばれますが、この通路が非常に狭い（狭い通路）のです 。

別の例え話をしましょう 。

• 計算装置（GPU） ＝ 1秒に1000個の製品を作れる超高速工場

• メモリバス（通路） ＝ 1秒に10個しか運べない遅い配送トラック

結果はどうなるでしょうか？ 工場は製品（計算結果）をすぐに作れますが、トラックが材料を運んでくるのを待ったり、完成品を運び出すのを待ったりする時間ばかりが発生します 。

この「待ち時間」こそが「フォン・ノイマン・ボトルネック」と呼ばれる問題です 。AIの処理時間のうち、実に90%以上が、この「メモリからのデータ待ち」で無駄になっているとさえ言われています 。

1-3. 原因その2：AIの「高性能な頭脳」が要求する膨大な処理

前のセクションでは、ハードウェア（コンピュータ）が「データ往復が遅い」という根本的な弱点を見てきました。

では、なぜAIはそんなにも大量の「往復」を必要としてしまうのでしょうか。それは、現代の高性能AIの多くが採用している「Transformer（トランスフォーマー）」というソフトウェア設計、特にその心臓部である「自己注意機構（Self-Attention）」に理由があります。

1-3-1. 高性能AIの心臓部「Transformer（トランスフォーマー）」

Transformerは、文脈を深く理解するのが非常に得意なAIの設計図です。この設計のおかげで、AIは文章中の遠く離れた単語同士の関係性も捉えられるようになりました。

しかし、この高性能を実現するために、「自己注意機構」は非常に計算量の多い処理を行います。これは、文章中のどの単語が他のどの単語と関連が深いのか、その「重要度」に重み付けをするための仕組みです。

1-3-2. AIは「文脈」をどう読むか？ (Query, Key, Valueの仕組み)

AIは、私たちが入力したテキスト（文章）を以下のようなステップで処理します。

• トークン化： 文章を単語や文字などの最小単位（トークン）に分割します 。

• 埋め込み（Embedding）： 各トークンを、AIが理解できる数値のカタマリ（ベクトル）に変換します。これは512次元や、GPT-4のような高性能モデルでは12,288次元といった、非常に多次元な数値の羅列です 。

そして、ここからがTransformerの核心です。AIはこの「数値ベクトル」から、文脈を理解するために3つの異なる側面（役割）を引き出します。それが「Query（クエリ）」「Key（キー）」「Value（バリュー）」です 。

これは、図書館で本を探すときの役割に例えることができます 。

• Query (クエリ) ＝ あなたの「検索キーワード」

• 「今、何について調べているか」という役割です。（例：「日本の首都について知りたい」）

• Key (キー) ＝ 本棚に並んだ本の「背表紙（索引）」

• 「私はこういう情報を持っている」という役割です。（例：「日本の地理」「世界の首都」）

• Value (バリュー) ＝ 本の「実際の中身」

• 「その情報（Key）の具体的な内容」です。（例：「東京は日本の首都で…」）

さらに、AIは文脈をより深く理解するために、このQKVの処理を「8つの視点」やそれ以上（マルチヘッド・アテンション）で行います 。これは、一人の司書（視点）が探すだけでなく、複数の司書が「歴史的な視点」「地理的な視点」「経済的な視点」など、異なる角度から一斉に関連する本（情報）を探すようなものです。

1-3-3. なぜ計算量が爆発するのか？ (O(N²)の問題)

ここが最大のポイントです。AIが新しい単語（Query）を処理するたびに、そのQueryと、過去の会話に出てきた「すべての単語のKey」とを1つずつ全部照合し、関連性を計算するのです 。

• 会話に10個の単語があれば、10 × 10 = 100回 の照合が発生します。

• 会話に100個の単語があれば、100 × 100 = 10,000回 の照合が発生します。

• 会話に10,000個の単語（コンテキスト）があれば、10,000 × 10,000 = 1億回 の照合が発生します 。

このように、トークン数がN個の場合、計算量がNの二乗（O(N²)）で爆発的に増えていくのです 。

1-3-4. 相性最悪の組み合わせの誕生

ここで、これまでの話が一つに繋がります。前のセクションで見た「フォン・ノイマン型」の弱点は、「メモリとの往復（データ転送）が遅い」ことでした。

つまり、

• ハードウェアは「冷蔵庫への往復（データ転送）が多いと致命的に遅くなる」という弱点を持っているのに、

• AI（Transformer）は「賢くあろうとするほど、冷蔵庫への往復回数が爆発的に増える」という性質を持っている。

この「遅くなる仕組みの上で、遅くなる処理を動かしている」という相性の悪さこそが、コンテキストウィンドウの限界を生む根本原因なのです。

1-4. 原因その3：AIがぶつかる物理的な「2つの壁」

前のセクションで、AI（Transformer）が「メモリ往復」を爆発的に増やす仕組み（O(N²)）を見ました。

この爆発的な処理要求は、いよいよデータセンターにあるハードウェアの「物理的な限界」に突き当たります。この限界には、実は「容量の壁」と「速度の壁」という、2つの異なる壁が存在します。

1-4-1. 議論の前提：クラウドAIとローカルAI

近年、AppleのM4 Maxのような高性能なチップが登場し、個人のPC上で「ローカルLLM」を動かすことが現実的になってきました。

しかし、本稿で議論の中心とするChatGPTやClaudeのような、数千億パラメータを持つ最先端の大規模言語モデルは、依然として専門のデータセンターで稼働する「クラウドAI」です。

あなたがChatGPTやClaudeに質問を投げかけると、そのデータはインターネット経由でデータセンターに送られ、そこで数千台の高性能サーバーに搭載された「GPU（ジーピーユー）」という専用チップの上で処理されます。

したがって、本稿でこれから解説する「メモリの限界」とは、あなたのPCのメモリ（16GBや32GB）のことではありません。

それは、データセンターにあるサーバーに搭載された「GPU専用メモリ（HBM）」（High Bandwidth Memoryの略）を指します。例えば、現在主流のNVIDIA H100 GPUは80GB、最新のB200 GPUに至っては192GBもの専用メモリを搭載しており、この巨大なメモリ上で起きている現象なのです。

1-4-2. AIの「記憶」の正体：GPUメモリの内訳

では、その巨大なGPUメモリの中は、一体どうなっているのでしょうか？

これは、「図書館の机」に例えると分かりやすいです。例えば、先ほど挙げたH100のメモリ（80GB）が、机全体の広さだと想像してください。

その机の上には、大きく分けて2つのものが置かれています 。

• 内訳①：固定された「百科事典」（モデルの重み）

• これは、AIが学習した「知識」そのものです。（例：「日本の首都は東京である」といった知識）

• 机の大部分（例：80GBのうち50GB）を占めており、会話の最中に内容が変わることはありません。全ユーザー共通の「教科書」のようなものです。

• 内訳②：増え続ける「会話ノート」（KVキャッシュ）

• これこそが、前のセクションで説明した「Key（キー）」と「Value（バリュー）」の保存実体です。

• AIは、あなたとの過去の会話（「日本の首都は？」→「東京です」など）を、この「会話ノート」にKとVのペアとしてどんどん書き込んでいきます。

• なぜ保存するのか？ それは、会話のたびに過去の履歴すべてをゼロから再計算していては、時間がかかりすぎて非効率だからです 。一度計算したKとVを「キャッシュ（一時保存）」しておくことで、次の応答を高速にしているのです。

「コンテキストを消費する」とは、まさしくこの「会話ノート（KVキャッシュ）」が机の上の空きスペース（例：残り30GB）を埋めていくことを意味します 。

1-4-3. 限界①：容量の壁（ハードな制約）

1つ目の壁はシンプルです。「机（メモリ）が物理的に一杯になる」という限界です。

会話が短いうちは、「会話ノート（KVキャッシュ）」は数MB程度で、机（残り30GB）には余裕があります。 しかし、長いPDFを読み込ませたり、何時間も会話を続けたりすると、その会話履歴（トークン）のすべてが「会話ノート」に書き込まれていきます 。

そして、128,000トークンといった膨大な量になると、「会話ノート」のサイズはついに机の空きスペース（30GB）を使い果たしてしまいます 。

これが「容量の壁」です。これ以上は、物理的に1トークンたりとも会話履歴（KとV）を保存できません。

1-4-4. 限界②：速度の壁（ソフトな制約）

しかし、問題は容量だけではありません。もう一つの厄介な壁が「速度の壁」です。

これは、「たとえ机にノートが置けたとしても、処理が遅すぎて使い物にならない」という限界です 。

なぜ遅くなるのでしょうか？ 前のセクションで説明した通り、AIは新しい発言（Query）があるたびに、過去の「会話ノート」の全ページ（過去の全Key）とめくり合わせて関連性をチェックします 。

• 会話履歴が100ページ（10,000トークン）なら、1億回の照合（メモリ往復）で済み、応答は数秒です 。

• 会話履歴が1,000ページ（100,000トークン）なら、計算量は100倍（100億回）になり、応答に1分以上かかるかもしれません 。

• もし10,000ページ（100万トークン）の履歴を処理しようとしたら、計算量はさらに100倍（1兆回）になり、1回の応答に数時間かかる計算になります 。

毎回返事を待つのに数分～数時間もかかっていては、実用的なサービスになりません。 これが「速度の壁」です。容量的にメモリに入ったとしても、計算量がO(N²)で爆発するため、現実的な時間で処理できなくなるのです。

1-5. 本章のまとめ：制約の理解から、次の一歩へ

ここまで見てきた3つの原因が、すべてつながりました。

• 原因その1：コンピュータの根本設計

• コンピュータは「計算（調理台）」と「記憶（冷蔵庫）」が分かれており、往復が遅い（フォン・ノイマン・ボトルネック）。

• 原因その2：AIの高性能な頭脳

• AI（Transformer）は文脈が長くなる（N）と、計算量とメモリ往復回数が二乗（N²）で爆発的に増える 。

• 原因その3：物理的な限界

• この爆発的な要求が、データセンターのGPUメモリが持つ「容量の壁（物理的に入らない）」と「速度の壁（遅すぎて使えない）」の両方に突き当たる 。

これが「コンテキストウィンドウに上限が生まれる」という最終結果です 。

現在のAI（例：GPT-4の128,000トークン）は、この2つの限界がほぼ同時に訪れるように、意図的に設計・調整されています 。

• GPUメモリ80GBに対し、モデル（百科事典）が50GB、会話履歴（ノート）が30GB。これで「容量の壁」に到達します 。

• そして、その30GBの会話履歴（128,000トークン）を処理する時間が、ちょうど「応答に10〜15秒かかる」といった、実用上我慢できるギリギリの「速度の壁」にも到達するのです 。

どちらか一方だけを解決してもダメで、両方の壁がAIの記憶の上限を定めているのです。

では、この限界は乗り越えられないのでしょうか？ 現在、世界中の企業がこの「容量」と「速度」の両方の壁を押し上げるために、凄まじい開発競争を繰り広げています。

• ハードウェアの進化

• NVIDIA社は、メモリ容量を80GBから192GBに増やし、転送速度も向上させた次世代GPU「B100」などを開発しています 。これにより、コンテキストウィンドウは物理的に60万トークン以上まで拡張可能になると予測されています 。

• ソフトウェアと設計の工夫

• Googleは、AI専用に設計した「TPU」というチップを自社開発し、メモリ設計や圧縮技術を最適化することで、100万トークンという巨大なコンテキストウィンドウを（NVIDIA製GPUを使う他社に先駆けて）実現しました 。

このように、ハードとソフトの両面から限界を引き上げる努力が続けられています。

今回、私たちはAIが「直前の会話を忘れる」という日常的な現象から始まり、その根本原因がコンピュータの基本設計にまで遡ってたどってきました。

AIは魔法の箱ではなく、「容量」と「速度」という2つの物理的な制約の中で動作するシステムです。

このAIの根本的な制約を理解した上で、次章では、この制約と上手く付き合い、Vibe Codingを成功に導くための具体的な手法、「コンテキストエンジニアリング」の実践方法をご紹介します。

2. コンテキストエンジニアリングの活用：「外部化」という答え

2-1. プロンプトエンジニアリングの限界

従来の「プロンプトエンジニアリング」は：

• どう書けば AI が賢く動くか

• どの順番で指示すると誤解されにくいか

といった、「1回の会話を工夫する技術」でした。

しかし実際の開発は：

• 何日も・何週間も続く

• ファイルや仕様が増え続ける

• チームメンバーや文脈も変わる

つまり「その場の一発芸」では足りません。

2-2. コンテキスト管理：外部化

前提として：本稿は、Cursor エディタ上で Claude Code を読み込み、ターミナルで直接指示を出す開発環境を想定しています。

従来のプロンプトエンジニアリングの限界に対し、そこで出てきた考え方が「コンテキストエンジニアリング」です。

コンテキストエンジニアリング： 必要な情報・ルール・設計を “外部化して構造化し、必要なタイミングでだけ AI に読み込ませる設計”

という発想です。

ポイントはたった一つ：

✨「全部プロンプトで説明するな。大事なことはファイルに書いておけ。」✨

この『外部化』に必要なファイル群を、たった3つのプロンプトをClaude Codeに投げるだけで自動生成し、開発のスピードと精度を劇的に向上させる方法を、本稿では共有します。

非エンジニアでもイメージしやすいように、 「AIと一緒に作る開発」は、次の4つの箱に情報を分けて外部化するとスッキリします。

• Rules（.cursor/rules）：AIの行動規範（どう書かせるか）

• Design（docs/ など設計情報）：仕様・設計・方針（何を作るか）

• Env（開発環境：package.json など）：PC側の環境設定（何を入れてどう動かすか）

• Code（src/）：成果物としてのコード本体

この4つを最初に外部化してしまうことで、

• AIは「Rules + Design」を読みながらコードを書く

• コンピュータは「Env」に従ってそのコードを動かす

• コード本体（src/）は、その結果としてどんどん生成・更新される

という流れになります。

逆に言うと：

Rules / Env / Design がない状態で、 いきなり src にコードを吐かせていると、そりゃ毎回ブレる。

ということです。

以下で、この4つの箱の役割をそれぞれご紹介します。

2-2-1. .cursor/rules（Rules の箱）

AIの“性格と作法”を決める場所

.cursor/rules は一言で言うと、「このプロジェクトでAIはこう振る舞ってください」を書いておく場所です 。

以前は毎回プロンプトで「TypeScriptで書いて」「この命名規則で」... と延々と説明していた内容を、外部ファイル (.mdc) に固定しておくための箱（イメージ）です。

中身と仕組み 14中身は「上:設定 (YAML) +下: ルール本文 (Markdown)」で構成されます。

典型的な.mdc ファイルは以下のようになります。

YAML

--- [cite_start]description: "フロントエンド用の実装ルール (React + TS + Tailwind) " [cite: 53, 129] [cite_start]globs: [cite: 53, 129] - [cite_start]"src/**/*.tsx" [cite: 53, 130] --- # 守るルール [cite: 53, 131] - [cite_start]新規コンポーネントは必ず TypeScript (.tsx) で書く [cite: 53, 132] - [cite_start]関数コンポーネントのみ使用 [cite: 53, 133] - [cite_start]スタイリングは Tailwind CSS を使う [cite: 53, 134] - [cite_start]コンポーネント名は PascalCase (例: UserCard) [cite: 53, 135]ここで大事なのは2つだけです。

• description: このルールは何のためのものか (AIの検索ラベル)

• globs: どのファイルを触っているときに、このルールを“自動で読むか”

「必要なときだけ読む」 仕組み

Cursor は、作業内容に応じて、以下のルールを使い分けます。

• 常に効かせるルール

• 特定のファイルを扱うときだけ自動で読むルール

• 必要と判断したときだけ取り寄せるルール

• あなたが明示的に呼んだときだけ読むルール

代表的な動き (Auto Attached の例) は以下の通りです。

• AIが「では次に src/components/Button.tsx を実装しますね」と提案し、ファイルを生成(またはオープン)する

• Cursor はそのファイルパス (src/components/Button.tsx) を検知して、

• .cursor/rules 内をスキャンし、「globs: src/**/*.tsx にマッチするルールあるな」と判断

• そのルールだけをAIのコンテキストに自動で追加した上で、コード生成を始める

つまり、プロジェクト全体の全ルールを毎回突っ込んでいるわけではなく、「今このファイルなら、このルールが必要だよね」というものだけを読みます。

この「選んで読む」仕組みのおかげで、以下の状態が実現します。

• トークン (AIの脳内メモリ)を圧迫しない

• 無関係なルールを読み込まず、誤作動を減らせる

• 一度決めたルールを、毎回プロンプトで書かなくていい

なぜこれで「同じ間違いループ」が止まるのか

この開発スタイルに切り替えると

• 一度決めたルールは .mdc に書いてあるので、AIは忘れない 。

• AIが変なコードを書いたら、プロンプトで注意するのではなく、ルールファイルの方を修正・追記する。

• 次回以降、AIは修正済みのルールを自動で読んでくれる。

「学びをルールファイルに固定していく」という運用に変わるため、同じ失敗を繰り返しにくくなります。開発は「AIが守るべき憲法 (Rules)を整備し続ける仕事」に変わります。

2-2-2. Design（Design の箱）

何を作るかを書いておく場所

Designは docs/ フォルダなどに格納する、サービスの仕様や設計、開発方針を定義したドキュメント群です。これは「何を作るか」をAIに伝えるための箱です。

docs/README.md や docs/specs.md といったファイルに、以下のような実現したい機能や要件を自然言語で記述しておきます。

• 「ユーザーはタスクを追加・完了できる」

• 「期限とタグを付けられる」

• 「ログインはとりあえず不要」

AIはコードを生成する際に、これらの設計情報を参照し、「何を作るべきか」を理解します 。

2-2-3. Env（Env の箱）

どう動かすかを書いておく場所

Envは package.json や .env といった、開発環境を定義するファイル群です。これは「(生成されたコードを) 何を入れてどう動かすか」を定義する箱です。

package.json の dependencies に React, Vite, TypeScript などを記述しておくことで、AIは「このプロジェクトではこれらの技術が使えるのだな」と理解し、それに沿ったコードを生成します 。

2-2-4. Code（Code の箱）

成果物が生まれる場所

Codeは src/ フォルダ以下に格納される、実際のアプリケーションコードです。

重要なのは、この箱が他の3つの箱 (Rules, Design, Env) をAIが解釈した結果として自動で埋められていく（生成される）という点です。開発者は最初に src/ を直接書くのではなく、まず設計とルールを固め、それに基づいてAIにコードを生成させる、という流れになります。

3. AIに開発の土台を丸ごと作らせる

これまでの章で、「コンテキストの限界」という課題と、その対策としての「4つの箱への外部化」という概念を学びました。本章では、いよいよその集大成として、この「外部化」されたファイル群、つまり開発の土台となるリポジトリ全体を、たった3つのプロンプトでAIに自動生成させる、極めて実践的な手法を共有します。

3-1. 3つのプロンプトで土台を自動生成する

手作業での環境構築や、どのファイルに何を書くべきかといった悩みは、特に非エンジニアにとっては大きな参入障壁です。このステップは、その障壁を取り払い、一貫性のある高品質な初期リポジトリを瞬時に構築することを目的とします。

このワークフローは、闇雲にAIに命令するのではなく、品質管理の考え方を取り入れた、以下の3段階の対話形式で進められます。（※各プロンプトの全文は、実践の際にコピー＆ペーストしやすいよう、記事の最後にまとめてあります。）

ステップ1：サービス概要の定義（Plan - 計画） まず、あなたの曖昧な「プロジェクトアイデア」を、AIに投げかけ、構造化された「サービス概要」という具体的な計画書に落とし込んでもらいます。ここでのあなたの役割は、AIが作成した計画書をレビューし、「私の意図は正しく伝わっているか？」を確認・修正することです。

ステップ2：ドメイン固有ファイルの生成（Do & Check - 実行と検証） 次に、AIにその計画書を元に、プロジェクトの核となるビジネスロジックやAPI設計など、一部分だけを試しに作ってもらいます。これは、最終的なリポジトリ全体を生成する前の重要な「プレビュー」であり、あなたにとって最も重要なチェックポイントです。「この解釈で本当に良いか？」をここで検証します。

ステップ3：最終プロンプトの実行（Act - 最終実行） 2段階のレビューを経てGoサインが出たら、いよいよ最終プロンプトを実行します。AIは検証済みの計画書に基づき、プロジェクト共通のルール（A）とドメイン固有のファイル（B）の両方を含む、リポジトリ全体を一括で生成します。

この「AIに作らせて、人間がレビューする」という対話のサイクルこそが、Vibe Codingの失敗を乗り越える鍵となります。

3-2. 実装中の注意点：AIとの上手な付き合い方

リポジトリが完成し、実装が始まった後も、AIとの対話をスムーズに進めるためのいくつかの「作法」があります。

コンテキスト消費量の監視と管理（ターミナル対話の作法） 私が採用している、Cursor上のターミナルで直接AIと対話するワークフローでは、セッション履歴全体がコンテキストとして積み上がっていきます。この対話環境はチャットUIと同様に状態を保持しており、以下のコマンドでコンテキストを直接管理することが、意図しないコンテキスト汚染を防ぎ、コストを最適化するための鍵となります。

• コンテキストの整理・要約: ターミナルで`/compact`と入力すると、AIがこれまでの会話を要約し、コンテキストを圧縮してくれます。応答が少しおかしくなってきた際の、最初の対処法として有効です。

• コンテキストの完全リセット: AIの応答が明らかに不正確になったり、堂々巡りに陥ったりした場合、ターミナルで`/clear`と入力するのが最も確実なリセット方法です。これにより、過去の会話履歴が完全にリセットされ、AIはクリーンな状態で次の指示を待つことになります。

コスト意識を持つ AIの利用は無料ではありません。特に高性能なモデルをAPI経由で利用する場合、コスト意識は不可欠です。

• モデルの使い分け: Anthropic社の最新・最高性能モデルはClaude 3.5 Sonnet（2024年6月発表）です。リポジトリの初期生成のような、深い思考と正確性が求められるタスクには、このモデルが最適です。一方で、生成後の単純なコード修正など、速度とコストを重視する場面では、より安価なClaude 3 Haikuに切り替えるのが賢明な戦略です。

• モデル利用料金の目安: APIで利用する場合の料金は大きく異なります（2024年11月時点）。

• Claude 3.5 Sonnet: 入力$3 / 出力$15（100万トークンあたり）

• Claude 3 Haiku: 入力$1 / 出力$5（100万トークンあたり）

• Cursorサブスクリプションの利点と注意点:

• 利点: Cursor Pro（月額$20）を契約すると、Haikuのようなモデルは無制限に、3.5 Sonnetのような高性能モデルも月に500回まで、追加料金なしで利用できます。日常的に開発を行うのであれば、コストを気にせずAIの能力を最大限に引き出せるため、極めて強力な選択肢です。

• 注意点: 「完全な使い放題」ではなく、高性能モデルにはソフトリミットが存在することを理解しておく必要があります。

3-3. AIの提案をレビューし、「憲法」を育てる

この開発手法で最も重要なのは、「AIが生成したものを鵜呑みにしない」という姿勢です。AIはあくまで「優秀な副操縦士」であり、プロジェクトの品質に最終的な責任を負う「機長」は、あなた自身です。

「憲法」へのフィードバックループ AIが意図しないコードを生成した時、その場しのぎでコードを修正するだけでは、AIは何も学びません。真に重要なのは、以下のフィードバックループを回すことです。

• 発見（Check）: AIの生成物に、設計上の考慮漏れや、より良い実装方法といった改善点を発見します。

• フィードバック（Act）: その改善点を、`.cursor/rules` 内の関連するルールファイルに追記・修正します。これがAIへの「教育」になります。

• 再実行（Do）: AIに再度指示を出すと、今度は更新された「憲法」を読んでくれるため、同じ間違いを繰り返さなくなります。

このサイクルを回すことで、AIはあなたのプロジェクト固有の文脈やコーディングスタイルを学習し、徐々に「あなただけの熟練アシスタント」に育っていきます。

プロンプトに「協業原則」を組み込む このレビュー文化を単なる心構えに終わらせないために、ステップ3で使う最終プロンプトに、以下のような「協業原則」を明記しておくことを強く推奨します。

開発プロセスにおける協業原則 (重要)

• レビュー文化の徹底: 私（開発者）は、あなたが生成したすべてのコードとドキュメントをレビューし、品質の最終責任を負います。
• 「憲法」へのフィードバック: レビュー時に発見された改善点は、その場しのぎのコード修正に留めません。私は、その改善点を`.cursor/rules`内の関連するルール（＝憲法）に追記・修正することで、あなたにフィードバックします。
• 継続的な学習: あなたは、このフィードバックサイクルを通じて、本プロジェクト固有の「より良いやり方」を継続的に学習してください。次回以降のコード生成では、常に更新された最新の「憲法」を絶対的な正としてください。この原則をプロンプトに含めることで、AIの振る舞いを規定すると同時に、私たち自身が守るべき最も重要な開発プロセスを、常に意識することができるのです。

4. まとめ：AIとの協業を「設計」する時代へ

本稿は、一人の非エンジニアが「Vibe Coding」の壁に突き当たった原体験から始まりました。AIに指示を繰り返すうちに応答が破綻し、開発が頓挫する——この堂々巡りの正体は、プロンプトの巧拙ではなく、「コンテキスト」というAIの記憶を体系的に管理できていなかった、という極めてシンプルな問題でした。

その原因を、1章ではコンピュータのハードウェア設計という根源まで遡ってたどってきました。そして2章と3章では、その制約と正面から向き合い、乗り越えるための具体的な方法論をご紹介しました。

本稿が提示する解決策「コンテキストエンジニアリング」は、AIとの対話を「その場限りの会話」から、「継続的な共同作業」へと変革する設計思想です。その核心は、AIの脳内にすべてを記憶させることを諦め、重要なルールや設計思想を「4つの箱」に外部化し、それをプロジェクトの「憲法」としてAIに遵守させることにあります。

この手法を実践するあなたの役割は、もはや単なる「AIへの質問者」ではありません。あなたは、AIが思考するための「外部脳」を設計し、その振る舞いを司る「憲法」を制定・育成する、プロジェクトの最高意思決定者です。AIの提案をレビューし、改善点を「憲法」にフィードバックし続けることで、AIはあなただけの最強のパートナーへと成長していきます。

コンテキストエンジニアリングは、技術的な背景を持たない私たちにこそ、大きな力を与えてくれます。それは、複雑なコードを書く能力ではなく、「何を」「なぜ」「どのように作るべきか」という本質的な問いを構造化し、AIに正確に伝える能力こそが、これからのAI駆動開発の主役となることを示唆しているからです。

この記事が、AIという強力な知性と対等に渡り合い、自らのアイデアを確実に形にするための、その第一歩となれば幸いです。

プロジェクトのリポジトリ初期設定を行うためのプロンプト

新しいプロジェクトのリポジトリ初期設定を行うためのプロンプト実行フローを、資料として以下にまとめます。

このワークフローは、大きく分けて3つのステップで構成されます。

• [ステップ1] サービス概要の定義: プロジェクトのアイデアから、AIに具体的な「サービス概要」を生成させます。

• [ステップ2] ドメイン固有ファイルの生成: ステップ1の概要に基づき、「B) ドメイン固有ファイル」群を生成させます。

• [ステップ3] 最終プロンプトの実行: ステップ1の概要を使い、「A) 共通ファイル」と「B) ドメイン固有ファイル」の両方を一括で生成・更新する最終指示を出します。

ステップ1: サービス概要（ドメイン前提）の生成

まず、プロジェクトの核となる「サービス概要」をAIに定義させます。

目的:

ユーザーの「プロジェクトアイデア」を、開発の前提条件となる具体的な「サービス概要（ドメイン前提）」に落とし込みます。

使用プロンプト (プロンプト1):

あなたはドメインエキスパートで、新しいソフトウェアサービスの基盤となる前提を定義します。ユーザーのプロジェクトアイデアに基づき、以下の厳密な形式で "## サービス概要（ドメイン前提）" セクションを生成してください。詳細で現実的、ドメインのベストプラクティスに沿ったものにし、[例]のようなプレースホルダーは具体的な内容で置き換えてください。

出力は以下の点をカバー: - サービス名: 指定がない場合、簡潔なキャメルケース名を提案。 - 種別/目的: 高レベルの目標とキー機能。 - 主要ユーザー/ユースケース: 3-5の主なペルソナとフロー。 - 成功指標: 3-5のKPI、定量的なものを含む。 - 制約・非機能: セキュリティ、スケーラビリティ、コンプライアンスなど。 - 技術スタック(初期想定): 現代的な適合スタックを提案（例: Webフレームワーク、DB、デプロイ）。

出力は "## サービス概要（ドメイン前提）" ブロックのみとし、それ以外は何も出力しない。

ユーザーのプロジェクトアイデア: [ここにあなたのプロジェクトアイデアを記述]

####サービス概要（ドメイン前提） - サービス名: [例: VaxReserve] - 種別/目的: [例: 予防接種の空枠検索→予約→通知をオンライン完結] - 主要ユーザー/ユースケース: [例: 住民/医療機関/管理者、検索→予約→リマインド] - 成功指標: [例: 予約完了率 > 90%, no-show率 < 5%, 本番までの時間 < 3ヶ月] - 制約・非機能: [例: PII暗号化、RBAC、監査ログ、i18n、高可用性(99.9%アップタイム)] - 技術スタック(初期想定): [例: Next.js + TypeScript、Prisma ORM + PostgreSQL DB、Docker、GitHub Actions CI/CD]実行方法:

• `[ここにあなたのプロジェクトアイデアを記述]` の部分を、あなたの具体的なアイデア（例：「クリニックの診察順番待ち状況をリアルタイムで確認・通知するシステム」）に置き換えて実行します。

• AIが `## サービス概要（ドメイン前提）` ブロックのみを生成します。このブロック全体を、次のステップで使用するためにコピーしておきます。

ステップ2: B) ドメイン固有ファイルの生成

次に、ステップ1で作成した「サービス概要」に基づき、プロジェクト固有のルールファイルやドキュメント（ドメインルール、API契約など）を生成します。

目的:

プロジェクトのビジネスロジックやAPI設計の骨子となる、ドメイン固有のファイル群（B）を個別に生成・確認します。

使用プロンプト (プロンプト2):

あなたはリポジトリ初期化の専門家です。提供されたサービス概要に基づき、B)ドメイン固有のファイルを生成してください。出力はファイル内容のみとし、各ファイルのテキストをそのまま記述。品質ポリシーに従い、簡潔で拡張可能な骨子を優先。

サービス概要: [ここにステップ1で生成したサービス概要をコピペ]

生成ファイル: 1. .cursor/rules/domain-[サービス名をkebab-case].mdc - front-matter: description を入れる - globs: ["**/*.ts","**/*.tsx"] - セクション: ビジネスルール、データ設計、API原則、失敗時リカバリ（概要を反映し、具体例を追加）

2. docs/domain.md - 目的/ユーザー/ユースケース/成功指標/制約を記述 - glossary.mdに重要用語を初期投入（別ファイルとして出力）

3. docs/api-contract.md - 主要3-5エンドポイントのI/O例、認証/認可/エラーコードを明記

最後に「作成/更新ファイル一覧」「要点サマリ」「次アクション候補」を出力。実行方法:

• `[ここにステップ1で生成したサービス概要をコピペ]` の部分に、ステップ1でコピーした `## サービス概要（ドメイン前提）` の内容全体を貼り付けて実行します。

• AIは、`domain-*.mdc`, `domain.md`, `api-contract.md` などのファイル内容と、サマリを出力します。

ステップ3: 最終プロンプトの実行 (A+Bの一括生成)

最後に、ステップ1の「サービス概要」を使い、プロジェクト共通のルール (A) とドメイン固有のファイル (B) の両方を一括で生成・更新する「最終プロンプト」を実行します。

目的:

プロジェクト全体のリポジトリ初期設定（共通ルールとドメイン固有ルールの両方）を、一つの指示で完了させます。ステップ2で生成したファイルが存在する場合、それに対する差分適用として機能します。

使用プロンプト (プロンプト3 / 最終プロンプト):

あなたはリポジトリの初期化コーチ兼コンテキストエンジニアです。 以下のサービス前提に基づき、A)共通ルール/ドキュメント、B)ドメイン固有ファイルを生成・更新してください。 既存があれば安全に差分適用します。

サービス概要（ドメイン前提）

[ここにステップ1で生成した「## サービス概要（ドメイン前提）」ブロックをそのままコピペ]

1. 生成・更新するファイル一覧（A+B）

まず、次のファイルを作成／更新してください。

A) 共通の生成/更新（同時に実施）

(1) .cursor/rules/core-guidelines.mdc（alwaysApply: true） - セッション再開時の初期化シーケンス（AI自身の起動手順）をルールとして含めること。

(2) .cursor/rules/security-baseline.mdc（alwaysApply: true）

(3) .cursor/rules/testing-standards.mdc（globs適用）

(4) .cursor/rules/frontend-style.mdc（globs適用）

(5) .cursor/rules/backend-architecture.mdc（globs適用）

(6) docs/domain.md / docs/architecture.md / docs/api-contract.md / docs/glossary.md（骨子を埋める）

B) ドメイン固有の生成/更新（このプロジェクト専用）

1) .cursor/rules/domain-[サービス名をkebab-case].mdc - globs: ["**/*.ts","**/*.tsx"] （※Python 中心など別スタックの場合は、開発者と相談のうえ適切な globs に変更してよい） - セクション: - ビジネスルール（[サービス概要]を反映） - データ設計（主要エンティティとキー、整合性/冪等性） - API原則（I/O契約、認可/レート制限、冪等性ID） - 失敗時リカバリ（リトライ/補償トランザクション/アラート） - 例: 予約なら「スロット一意性」「二重予約防止」「キャンセルポリシー」「TZ方針」などを具体化 - front-matterに description を入れる

2) docs/domain.md - [サービス概要]の内容で、目的/ユーザー/主要ユースケース/成功指標/制約を具体的に記述 - docs/glossary.md に重要用語（例: スロット/キャンセル/在庫/枠/リード）を初期投入

3) docs/api-contract.md - 主要3〜5エンドポイントのI/O例を具体化（例: searchSlots, createReservation, cancelReservation, notify） - 認証/認可/スロットの一意条件/エラーコードを明記

2. 各ファイルの中身に関する仕様

2.1 .cursor/rules/core-guidelines.mdc の仕様

このファイルは「AI にとっての憲法 + 進捗メモ」です。 会話履歴ではなく、このファイルと docs/ 群を Single Source of Truth とします。

以下のセクションを必ず含めてください：

1. 「AI セッション初期化シーケンス」 2. 「現在の進捗状況」 3. 「次のアクション（優先順位付き）」 4. 「セッション開始時のチェックリスト」 5. 「/clear や /compact 実行後の扱い（重要）」

#### 2.1.1 「AI セッション初期化シーケンス」

内容の例（構造だけ守れば中身の文章はおまかせ）：

1. リポジトリルートの認識 - 例: `~/project-root` をリポジトリルートとみなす、など。

2. .cursor/rules/ 配下の規則読み込み - `.cursor/rules/core-guidelines.mdc` を最優先で開き、要点を短く要約する。 - 存在する場合のみ、次もざっくり把握する： - `.cursor/rules/security-baseline.mdc` - `.cursor/rules/testing-standards.mdc` - `.cursor/rules/frontend-style.mdc` - `.cursor/rules/backend-architecture.mdc` - `.cursor/rules/domain-*.mdc`

3. 主要ドキュメントの読み込み - 存在するものだけを対象に、目的と現状を簡単に要約： - `docs/domain.md` - `docs/architecture.md` - `docs/api-contract.md` - `docs/glossary.md` - `SETUP_SUMMARY.md` 等の進捗サマリ系ファイル

4. 「現在の進捗状況」と「次のアクション」の確認 - core-guidelines.mdc 内の該当セクションを読み、 - 現在どのフェーズにいるか - 直近で何をするべきか を 5 行以内で要約して開発者に返す。

5. タスクのすり合わせ - 初期化結果を共有し、「このセッションでどこから進めたいか」を開発者と確認する。

#### 2.1.2 「現在の進捗状況」

• フェーズ単位（例: Phase 1 / Phase 2 ...）でタスクを管理。
• ✅ / ⏳ / ❌ などでステータスを明示。
• 表形式または箇条書きを使い、誰が見ても一目でわかるようにする。
• `最終更新: YYYY-MM-DD` を含める。

#### 2.1.3 「次のアクション（優先順位付き）」

• 「直近（本セッション）」と「今後1〜2週間」など時間軸で分ける。
• 各アクションに、具体的なファイルパス / ノートブック / スクリプト名を含める。

#### 2.1.4 「セッション開始時のチェックリスト」

• 新セッションや `/clear` / `/compact` 後に必ず確認すべき項目を列挙。
• 例：
• [ ] `SETUP_SUMMARY.md` でフェーズ進捗を確認（存在する場合）
• [ ] `.cursor/rules/core-guidelines.mdc` の「現在の進捗状況」を確認
• [ ] `.cursor/rules/domain-*.mdc` で最新のビジネスルールを確認
• [ ] 必要に応じて `docker-compose ps` や `logs/` で実行状態・ログを確認

#### 2.1.5 「/clear や /compact 実行後の扱い（重要）」

ここでは「今後の運用ルール」として、次の方針を書いてください：

- `/clear` や `/compact` によって会話履歴が消えたり要約されても、 真実の源泉は常にファイル側にある とすること。 - 会話の要約や直前のメッセージ内容は「参考情報」に過ぎず、 ルール・進捗・方針は必ず以下から再構築する： 1. `.cursor/rules/core-guidelines.mdc` 2. `.cursor/rules/domain-*.mdc` 3. `.cursor/rules/security-baseline.mdc` `.cursor/rules/testing-standards.mdc` `.cursor/rules/backend-architecture.mdc` 等 4. `docs/domain.md`, `docs/architecture.md`, `docs/api-contract.md`, `docs/glossary.md` 5. `SETUP_SUMMARY.md` 等の進捗サマリ系ファイル（存在する場合）

- `/clear` や `/compact` の後、AI は必ず： 1. `.cursor/rules/core-guidelines.mdc` を開き、「現在の進捗状況」と「次のアクション」を読み直す。 2. 必要に応じて docs/* や SETUP_SUMMARY.md を読み直す。 3. 「いまどのフェーズで、次に何をするか」を 5 行以内で言語化して開発者に報告する。 4. その上で、このセッションで着手するタスク案を提案し、開発者とすり合わせる。

- `/compact` によって生成された会話要約は、 ファイル内容と矛盾しない範囲でのみ参考にし、矛盾する場合はファイル側（特に core-guidelines.mdc）を優先する。

2.2 その他のルールファイル

(2) .cursor/rules/security-baseline.mdc（alwaysApply: true） - API キーや認証情報の扱い、ログへの機密情報記録禁止、権限設計などをサービス概要に沿って明記。

(3) .cursor/rules/testing-standards.mdc（globs適用） - プロジェクトの言語・構成に合わせて globs を設定（例: ["**/*.ts","**/*.tsx"] や ["**/*.py","**/*.ipynb"]）。 - 単体テスト / 結合テスト / 回帰テスト / E2E / バックテストなどの基準を定義。

(4) .cursor/rules/frontend-style.mdc（globs適用） - フロントエンドがある場合のみ詳細を書く。現時点でフロントエンドが無い場合は、その旨を明記。

(5) .cursor/rules/backend-architecture.mdc（globs適用） - レイヤ構造、ディレクトリ構成、責務分担、依存関係の方針などを骨子レベルで定義。

2.3 docs/ 配下のドキュメント

(6) docs/domain.md / docs/architecture.md / docs/api-contract.md / docs/glossary.md（骨子を埋める）

• docs/domain.md:
• サービスの目的 / 主要ユーザー / ユースケース / 成功指標 / 制約を、ステップ1のサービス概要に基づき文章化。

• docs/architecture.md:
• システム構成、主要コンポーネント、データフロー、外部サービス連携をテキストで図解。

• docs/api-contract.md:
• 主要 3〜5 エンドポイントについて、リクエスト/レスポンス例、認証/認可方式、主なエラーコードを記述。

• docs/glossary.md:
• 本ドメインで頻出する重要用語（例: 本サービス固有の用語）を用語集として整理。

3. 品質・出力ポリシー

- 実ファイルとして保存し、最後に必ず以下を出力： - 「作成/更新ファイル一覧」 - 「要点サマリ」 - 「次アクション候補」 - 既存ファイルがあれば差分パッチ形式で提示 → 適用。 - 文章は簡潔で、後から拡張しやすい骨子を優先。 - 会話コンテキストが `/clear` や `/compact` で失われても、 1. `.cursor/rules/*.mdc` 2. `docs/*.md` 3. `SETUP_SUMMARY.md` 等の進捗系ドキュメント を読み直すことで、AI が自力でコンテキストを再構築できる状態にしておくこと。 - 新しいセッションでは、必ず core-guidelines.mdc の「AI セッション初期化シーケンス」に従うこと。

4. 開発プロセスにおける協業原則 (重要)

• レビュー文化の徹底: 私（開発者）は、あなたが生成したすべてのコードとドキュメントをレビューし、品質の最終責任を負います。

• 「憲法」へのフィードバック: レビュー時に発見された改善点は、その場しのぎのコード修正に留めません。私は、その改善点を`.cursor/rules`内の関連するルール（＝憲法）に追記・修正することで、あなたにフィードバックします。

• 継続的な学習: あなたは、このフィードバックサイクルを通じて、本プロジェクト固有の「より良いやり方」を継続的に学習してください。次回以降のコード生成では、常に更新された最新の「憲法」を絶対的な正としてください。

ここまでを一括で実行してください。

実行方法:

• `[ここにステップ1で生成したサービス概要をコピペ]` の部分に、ステップ1でコピーした `## サービス概要（ドメイン前提）` の内容全体を貼り付けます。（※プロンプトの[例:]の部分は、ステップ1の生成結果で完全に置き換えてください）

• この完成したプロンプト全体を実行します。

• AIは、A) 共通ファイルと B) ドメイン固有ファイルの両方を生成・更新し、最終的なサマリを出力します。

• ステップ2は、「B」のファイルを得るためではなく、「ステップ1の概要が正しいか」を検証するための「プレビュー」です。

• ステップ3は、検証済みの「概要」を使って、リポジトリ全体（A+B）を同期させるための「最終実行（Sync）」です。

/clear及び/compact 後に毎回投げる「セッション再開用プロンプト」

これは/clear または /compact 後の新しいセッションとして扱ってください。

まず `.cursor/rules/core-guidelines.mdc` を開き、 そこに書かれている「AI セッション初期化シーケンス」と 「/clear や /compact 実行後の扱い」のルールに従って再初期化してください。

そのうえで必要に応じて、

• .cursor/rules/domain-*.mdc

• .cursor/rules/security-baseline.mdc

• .cursor/rules/testing-standards.mdc

• .cursor/rules/backend-architecture.mdc

• docs/domain.md, docs/architecture.md, docs/api-contract.md, docs/glossary.md

• SETUP_SUMMARY.md（存在すれば）

を読み直し、

• 現在のフェーズ

• 現在の進捗状況（1〜2行）

• 直近の「次のアクション」候補（3つまで）

を箇条書きで教えてから、 このセッションでやるタスク案を 3 つ提案してください。

（最終更新：2025-11-18）