結論から言うと、AIエージェントに「何をやらせるか」より「何を読ませるか」の方がはるかに重要だ。
この記事はこんな人に向けて書いている。
・Claude Codeを導入したのに思ったほど開発が速くならない
・AIに指示を出しても的外れなコードが返ってくる
・プロンプトの書き方を工夫しても改善しない
・結局自分で書いた方が早いと感じ始めている
ここで止まっている人ほど、最後まで読んでほしい。
AIエージェントが「使えない」と感じるのは指示の問題ではない
Claude CodeやOpenAIのCodex CLIといったターミナルエージェント（ターミナル上で動くAIコーディングツール）は、2025年後半から急激に実用レベルになった。バグ修正、UI実装、バックエンドの更新、テストの追加。こうしたタスクを日常的にエージェントに任せている開発チームは増えている。
ただ、同じツールを使っているのに「めちゃくちゃ生産性が上がった」という人と「結局自分で直す方が早い」という人に分かれる。この差はプロンプトの書き方ではない。
差が出るのは、エージェントがアクセスできる「コンテキスト」の質と量だ。
人間のエンジニアを想像してほしい。新しくチームに入ったメンバーに「このバグ直して」とだけ言っても、プロジェクトの背景も設計思想も分からなければまともなコードは書けない。仕様書、過去の議論、デザインの意図、技術的な制約。こうした情報があって初めて、的確な修正ができる。
AIエージェントもまったく同じだ。どれだけ賢いモデルを使っていても、前提情報が足りなければ的外れな出力しか返ってこない。
「vibe coding」と「vibe engineering」の決定的な違い
「vibe coding」という言葉を聞いたことがある人は多いと思う。AIにざっくり指示を出して、なんとなくコードを書かせるスタイルだ。個人の小さなプロジェクトなら、これでも十分に動くものが作れる。
一方で、Simon Willisonが提唱している「vibe engineering」は、もう一段上の考え方になる。ざっくり言うと、AIエージェントのワークフローに「ちゃんとしたソフトウェアエンジニアリングの慣行」を組み込むという発想だ。
具体的には以下のような要素を含む。
・詳細な計画仕様をエージェントに渡す
・開発者だけでなく、すべての関係者からのコンテキストを反映する
・テストとデプロイのパイプラインを整備する
・1人あたり1日に10〜20セッションのエージェント実行を回す
これをスケールさせるには、エージェントが「チームが議論している場所」から直接コンテキストを引っ張ってこられる仕組みが必要になる。プロダクトの議論、デザインの決定、技術的な仕様。これらが散らばっていたら、毎回プロンプトに手動でコピペするだけで日が暮れる。
vibe codingは「AIに何をやらせるか」に集中する。vibe engineeringは「AIが正しく動ける環境を整える」ことに集中する。この視点の違いが、成果の差を生んでいる。
issueがそのままエージェントの入力になる世界
最近、Emotion Machineというチームが「Overnight」という仕組みを公開していた。これはLinear（プロジェクト管理ツール）のissueにラベルを付けると、サンドボックス環境（隔離された安全な実行環境）が立ち上がり、Claude CodeやCodex CLIがそのissueの内容を読んで実装を進めるという仕組みだ。
面白いのは2段階に分けているところだ。
まずエージェントがissueを読み、コードベースを探索し、実装計画を作成してLinearに投稿する。人間がその計画をレビューして、修正コメントを付けるか「GO」と言えば、2回目の実行で実装してプルリクエストを作成する。
ここで重要なのは、Linearにはすでにエンジニアやデザイナーが普段から情報を入れているという点だ。issueの説明、コメントでの議論、添付されたデザイン、関連ドキュメントへのリンク。これらがすべてエージェントのコンテキストになる。
つまり、エージェント専用の指示書を別途作る必要がない。チームが普段から使っているツールがそのままエージェントの入力になる。サンドボックスで実行されるから、万が一おかしなコードが生成されても本番環境には影響しない。
この仕組みの本質は「ツールの連携」ではなく「コンテキストの集約」にある。情報が一箇所に集まっているから、エージェントが的確に動ける。
自分がVPS運用で痛感した「コンテキスト不足」の代償
自分もAIエージェントを使って日々開発をしているが、コンテキストの整備を怠ったときの手戻りは本当に大きい。
つい最近も、VPS上でエラーが3件同時に出たことがあった。必要なライブラリが入っていない、関数の定義が足りない、依存パッケージが不足している。どれもエージェントに作業を任せた結果なのだが、原因を辿ると「プロジェクトの依存関係や設定の全体像」をエージェントに渡しきれていなかったことに行き着いた。
結局、自分で1つずつ原因を特定して修正した。エージェントに任せた時間より、修正にかかった時間の方が長かった。まさに本末転倒だ。
この経験から学んだのは、エージェントに渡すべきは「やってほしいこと」だけではなく「プロジェクトの前提条件」だということだ。使っているライブラリのバージョン、環境固有の制約、過去に発生した問題とその対処法。こうした情報をあらかじめ整理しておくだけで、エージェントの出力精度は劇的に変わる。
「指示が悪かったのかな」とプロンプトをいじり回す前に、まずエージェントが参照できる情報を増やす方が効果的だ。
フリーランスこそ「コンテキスト設計」に時間を使うべき理由
フリーランスエンジニアは基本的に1人で開発している。チームがいないから、プロジェクト管理ツールに情報を整理するモチベーションが湧きにくい。自分の頭の中にあるから書かなくていい、と思いがちだ。
でも、AIエージェントを活用するなら話は別になる。
エージェントは自分の頭の中を読めない。プロジェクトの背景、設計の意図、なぜこの実装を選んだのか。こうした暗黙知を明文化して、エージェントがアクセスできる場所に置いておく必要がある。
Claude CodeならCLAUDE.mdというファイルにプロジェクトのルールや前提を書いておける。自分はこのファイルをかなり厚めに書いている。使っている技術スタック、コーディング規約、よくあるエラーパターンとその対処法。これを整備してからは、エージェントの出力が明らかに安定した。
1人で開発しているフリーランスだからこそ、自分の代わりに動いてくれるエージェントへの「引き継ぎ資料」は丁寧に作るべきだ。チーム開発なら他のメンバーが補完してくれるが、1人なら全部自分で整備するしかない。
面倒に感じるかもしれないが、この初期投資は確実にリターンがある。自分の場合、コンテキストを整備する前と後で、エージェントの出力を修正する頻度が体感で半分以下になった。
月額約20ドルのAIツール代を払って「いまいちだな」と感じているなら、ツールを変える前に自分のプロジェクトの情報整理を見直した方がいい。ツールの性能はもう十分すぎるほど高い。足りないのは、ツールに渡している情報の方だ。
まとめ
・AIエージェントの成果が出ない原因は、プロンプトの書き方ではなく「コンテキスト不足」であることが多い
・エージェントに渡すべきは「指示」だけでなく「プロジェクトの前提条件と背景」
・フリーランスこそ、CLAUDE.mdのような仕組みで暗黙知を明文化しておく価値がある
AIエージェントは優秀な新人エンジニアだと思えばいい。能力は高いが、プロジェクトのことは何も知らない。引き継ぎ資料の質が、そのまま成果物の質になる。
【PR】フリーランスエンジニアにおすすめのツール
独自ドメインを取得するならコスパで選んで間違いない。ブログやポートフォリオ用に1つ持っておくと便利。
コメント