はじめに
2025年はAIエージェント元年と言われ、Claude CodeやCursorなどのAIエージェントが急速に発展した年でした。
AIエージェントは、従来の生成AIのように単一のタスクをこなすのではなく、指示した内容を理解して自律的に動いて目的を達成してくれます。
数年前までIT人材不足と騒がれていましたが、その大部分をAIエージェントが補って解決していくと容易に想像できます。
われわれソフトウェアエンジニアの職場も、AIエージェントの導入により働き方が様変わりしつつあります。
本記事では、AIエージェントを使った開発の失敗談をもとに、AIエージェントの効果的な使い方について説明します。
時代の潮流に乗り遅れて淘汰されないように、概要レベルの知識は把握していきましょう。
前提条件
- 本記事は、AIエージェントをまだ使いこなせていないソフトウェアエンジニアを読者対象としています。
- 本記事で紹介するAIエージェントは、「Claude Code」を対象とします。
- GitHubなど、ソフトウェア開発で登場するエコシステムについては詳細を割愛します。
解説
変わりゆくソフトウェアエンジニアの働き方
AIエージェントは、指示された要件をもとに、調査、分析、設計ドキュメント作成やソースコードの実装、自動テスト、各種環境へのデプロイまで一通りの作業を自律的に実施します。
ソフトウェアエンジニアはその恩恵を受け、自ら手を動かしてフレームワークやライブラリの調査を行ったり、プロトタイプを作って実現性検証をすることは少なくなりました。
代わりにAIエージェントに対して適切に指示を出し、成果物をレビューすることが求められるようになってきました。
未経験者やジュニアエンジニアのハードルが上がった
一昔前なら、業界未経験でスクールや独学でプログラミングを学習した人たちであっても、現場で先輩に教えを請いながら成長できました。
ところが、AIエージェントの登場により、アメリカで情報工学を専門に学んだ新卒者たちでも就職難の時代になってきました。
SIerやコンサルタントの仕事は減っていく未来が見えている中で、われわれソフトウェアエンジニアはどのように生き残っていけばよいのでしょうか。
サバイブしていく方法について
半年間、AIエージェントを使ってみた個人的な所感ですが、以下の能力を伸ばしていけば、しばらくは生き延びられると感じています。
- AIエージェントに快適に働いてもらえるよう指示を出せる
- AIエージェントの成果物について、適切にレビューするための情報工学知識を持つ
- AIエージェントが作成した雑多な設計ドキュメントをかみ砕き、ステークホルダーが理解できるくらいの資料に落とし込める
- AIエージェントが学習しきれていない深いドメイン知識を持つ
上記は、AIエージェントに関係なく、これまでシニアエンジニアが担ってきた役割であり、目新しいことはないです。
経験の少ないジュニアエンジニアは、手始めにこれから紹介するAIエージェントの活用方法をマスターして、残りの能力を伸ばしていけばよいでしょう。
AIエージェントを使用してきた半年間の振り返りとナレッジ共有
2025年の夏頃から、社内プロジェクトでAIエージェント「Claude Code」を使って開発を行うことになりました。
今思い返せば、当初は手探りでいろいろ試行錯誤して、無駄な時間を過ごすこともありましたが、そこで得た知見、ノウハウを共有します。
プロジェクト計画に合わせて料金プランを選択する
Claude Codeの料金プランには、個人プラン、チーム・エンタープライズプラン、APIプランがあります。
個人プランには、Proプラン（＄20/月）、Maxプラン（5x:＄100/月、20x:＄200/月）があります。※2026年2月時点の料金です。
Proプランは、コード量が1,000行未満のプロジェクト向けプランです。
画面数が少ないToDoアプリ程度なら十分ですが、それ以上の規模になると、すぐにトークン使用量制限にかかり、その後5時間程度Claude Codeを使用できなくなります。
プロジェクト開始時など、まだMaxプランを契約していない場合は、
- 顧客説明用など簡易の画面遷移だけつくればよい段階：Proプランでしのぐ
- 要件を収集後に機能実装する段階：Maxプランに切り替え
など、最初から計画的な料金プラン変更を検討しておくと、トークン回復待ちのタイムロスや無駄な課金も抑えらるでしょう。
また、開発が落ち着いてきたからと安易にMaxプランからProプランにダウングレードしてしまうと、規模の大きなアプリでバグ調査などを行う場合に、Claude Codeにソースコードを調査させただけで、すぐに使用制限に達して満足のいく修正ができない、などの事態が発生する可能性があるので注意が必要です。
私の場合、個人のProプランで利用を開始しました。最初の頃にPoCを実施中に使用制限に達することが多発していたので、プロジェクトの本格開始前にMaxプランに切り替えたため、大きなタイムロスなく開発を進めることができました。
会社で5名以上のチームで利用する場合は、チームプランを検討しましょう。個人プランと同じ金額で、より多くの使用量が得られます。
また、数百名規模の組織で、利用内容の監査を行いたい場合はエンタープライズプランを検討しましょう。
バイブコーディングは捨て、仕様書駆動開発を採用する
「XXXXのようなアプリが作りたい」といった曖昧な指示をプロンプトで与え、AIエージェントが作り上げた内容を見て、自分の要望と異なる点を都度フィードバックしていく方法をバイブコーディングと呼びます。
AIエージェントに初めて触れた人たちは、会話していくだけで動くアプリができる開発体験に感動を覚えるでしょう。
一方で、規模の大きいアプリを開発する場合、仕様書をAIエージェントとともに作成して、仕様書通りに実装させていく仕様書駆動開発（SDD：Spec Driven Development）を行う方が無難です。
なぜなら、指示を与える人間も、指示を受けるAIエージェントも、記憶できる容量は限られており、途中までやっていたことを次第に忘れていくからです。
バイブコーディングした場合、アプリが完成に至ったプロセスは、指示を与えた人間にしかわからないし、その人の記憶も時間と共に失われていきます。リリースして運用保守フェーズになった段階には、アプリの挙動が仕様通りなのかバグなのか、誰にもわからなくなってしまいます。
AIエージェントも、トークンの残量が減ってくると、これまでの会話を圧縮してコンテキストウィンドウ残量を増やそうとします。圧縮した場合、過去の会話の概要は断片的に記憶していますが、詳細は忘れ去られます。それだけならまだしも、PCをシャットダウンしたり、AIエージェントを提供するサービス事業者側の問題で通信が繋がらなくなった場合、それまでの会話はすべて失われてしまいます。
AIエージェントを用いた場合でも、仕様書を作成し、後続の作業が滞りなく実施できるようにするプロセスは、従来の開発プロセスと同様に必要です。
なお、バイブコーディングがすべて悪なわけではなく、小規模なプロジェクトやPoCには向いているため、適材適所で使い分けるとよいでしょう。
SDDツールのGitHub Spec Kitについて
GitHub Spec Kitは、仕様駆動開発のためのツールです。決められたフローに従いコマンドを入力するだけで、AIエージェントが必要な設計書や実行計画書を自動で作成します。
以下のようなコマンドが用意されています。
-
/speckit.constitution: プロジェクト全般で守るべき規約ドキュメントを作成します。 -
/speckit.specify: 要求に沿って要件定義書を作成します。 -
/speckit.plan: 要件を実現するための設計書と実行計画を作成します。 -
/speckit.tasks: 設計した内容を実装するためのタスクリストを作成します。 -
/speckit.implement: タスクリストに従い、実装を進めていきます。
AIエージェントが作成した設計ドキュメントを複数の人間がレビューすることで、設計意図やナレッジを共有することが可能になり、途中で別担当へ作業を引継ぐこともバイブコーディングに比べて容易に可能になります。
また、タスクリストの消化状況も随時更新されていくため、途中でPCを落として、次の日から再開することも容易になります。
定期的にコミットし、PR(Pull Request)は短くまとめる
AIエージェントは、1回の会話セッションで記憶できるコンテキストウィンドウ（読み書きできる情報量）に上限があり、超過すると会話の内容を圧縮して、記憶領域を広げようとします。
会話の内容が圧縮されると、それまで行っていた会話の断片しか記憶されなくなります。
下記/contextコマンド実行例だと、会話するに従い、Messagesの使用量が増えていき、Free spaceを消費していきます。Free spaceが枯渇した際、それまでのMessages内容を圧縮してFree spaceを広げようとします。
❯ /context
⎿ Context Usage
⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ claude-opus-4-5-20251101 · 23k/200k tokens (11%)
⛀ ⛁ ⛀ ⛀ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ Estimated usage by category
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ System prompt: 2.5k tokens (1.2%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ System tools: 18.4k tokens (9.2%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ MCP tools: 293 tokens (0.1%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ Custom agents: 1.6k tokens (0.8%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ Skills: 61 tokens (0.0%)
⛶ ⛶ ⛶ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛁ Messages: 8 tokens (0.0%)
⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛶ Free space: 144k (72.1%)
⛝ Autocompact buffer: 33.0k tokens (16.5%)
この仕組みを知っていないと、「さっき指示したのに、もう忘れて同じ間違いをするのか！」とAIエージェントに憤慨することになります。
コンテキストウィンドウの枯渇が原因で、AIエージェントがプログラムを壊していく例を紹介します。
例えば、A→B→Cの順に作業をしていて、A→Bの時点では想定通りの挙動で、Cの挙動が満足いかず、CをロールバックしてA→B→Dの実装にしてほしいとAIエージェントに指示を出すケースがあった場合を考えてみます。
AIエージェントは、Cを実装した時点ではこれまでの実装内容を覚えていますが、CをロールバックしてDを実装することを指示されたタイミングでたまたま記憶容量オーバーになり、会話を圧縮した場合、Cの作業内容を忘れて、AやBの実装まで壊し始めます。
AとBはうまくいっていたので、そのままにしてほしかったのに！と憤慨しても、後の祭りです。
また、AIエージェントに同じ指示を出したとしても、作成されるアウトプットが同じとは限りません。
最初からやり直したとしても、AとBが再現されるとは限りません。
このような惨劇を防ぐための方法は、定期的にコミットすることです。
Aの実装が終わったタイミングでコミット、Bも同様。コミットログが残っていれば、AIエージェントにコミットIDを指定してロールバックさせることは容易です。
また、AIエージェントが作成したソースコードは、最終的には人間がレビューする必要があります。
人間がコードを書く場合も同様ですが、レビュー範囲が広いとレビュワー側の負担が大きいです。
負担が大きくなると、まともなレビューができなくなります。とりあえず動いていそうだし、ビルドエラーが出ていないなら承認してしまいます。その結果、細かい部分で設計漏れに気づけず、他の機能との連動でエラーが出たりします。
1回のPR（Pull Request）で、修正するファイルやソースコードの行数、機能数に上限を設けるほか、AIエージェントとの1セッションの対話時間を最長30分に制限するなど、AIエージェントのコンテキストウィンドウ圧縮前に作業完了できる単位に区切ると、一度にレビューする量も減ります。
SubAgents、Agent Skills、MCPを活用する
CLAUDE.mdファイルに規約を記載しておけば、Claude起動時にAIエージェントが読み込み、規約に沿ったアウトプットを行います。
例えば、日本語で応答して欲しい旨をCLAUDE.mdに記載しておけば、Claudeに対して毎回日本語で答えるよう指示を出す必要はありません。
CLAUDE.mdに膨大な指示を記載してしまうと、毎回起動時に読み込まれるため、セッション内で消費できるコンテキストウィンドウが減ってしまいます。
必要な時に、必要な指示だけを、AIエージェント自身が読み込むことができれば、無駄にコンテキストウィンドウを消費することもなくなります。
解決策として、SubAgentsやAgent Skills、MCPをAIエージェントに利用させれば、コンテキストウィンドウの消費量を抑えることができます。
SubAgents
SubAgentsは、レビュワーやセキュリティ診断や品質管理など専門的なタスクを行うエージェントを別に設けて、メインのエージェントが複雑なタスクを処理する際、サブエージェントに処理を委譲することで、コンテキストウィンドウの消費を抑えることができます。
メインエージェントとサブエージェントは、別々のコンテキストを使用するため、互いのコンテキストウィンドウを消費しあうことはありません。
AIエージェントが自発的にサブエージェントに処理を任せたり、ユーザーがプロンプトでサブエージェントを使用することを指示することもできます。
サブエージェントは、Claude上で/agentsのコマンドを実行して作成できます。
Agent Skills
SubAgentsが独立した専門家アシスタントだったのに対して、Agent Skillsは再利用可能な業務マニュアル・参考書のような役割を果たします。
コーディング規約やAPIドキュメントのテンプレート、コードレビューの観点、プロジェクトのディレクトリ構成、実装方針など、プロジェクトで利用するルールを定義します。
CLAUDE.mdにルールをまとめて定義するのではなく、役割毎にファイルを分けておくことで、必要な時に必要なだけファイルを読み込むことが可能になり、コンテキストウィンドウの消費量を抑えることができます。
Skillsは、SKILL.mdファイルを手動で作成し、.claude/skills/user/任意のスキル名/SKILL.mdに格納します。
MCP
MCP（Model Context Protocol）は、AIモデル（LLM）と外部のデータソース、ツール、APIを標準化された形式で接続するための規格です。
Claude CodeにMCPの定義を読み込ませれば、AIエージェントが必要と判断した際に外部のAPIを呼び出して情報を取得したり、DBにSQLを発行してデータを分析したりすることが可能です。
おススメのMCPは以下の通りです。
Context7 MCP
AIエージェントのLLMは、学習時点のデータをもとに受け答えを行うため、古い情報をもとに作業を進めてしまうことがあります。
Context7は、フレームワークやライブラリなどのOSSがGitHubリポジトリで公開している公式ドキュメントを集めてホストしています。
Context7のMCPを利用すると、AIエージェントが旧バージョンのライブラリを前提としたコードの提案すること低減し、利用者が自分で公式ドキュメントを読み込む必要がなくなります。
Serena MCP
AIエージェントがソースコードを分析する場合、基本的にはGrepによる文字列検索を行います。
Grepで分析する場合、キーワードに合致するソースコードをすべて読み込んでしまうため、コンテキストウィンドウを消費してしまいます。
Serena MCPは、LSP（Language Server Protocol）を活用し、ファイル全体ではなく、プロジェクト構造を意味的に解析し、必要な関数・クラスなどのシンボル部分だけを抽出してAIエージェントに渡すため、コンテキストウィンドウ消費を大幅削減できます。
PostgreSQL MCP
PostgreSQLなどのデータベースを操作するためのMCPも存在します。
例えば、「XXテーブルから、ZZの条件に合うデータを検索して」とか、「売上データをカテゴリごとに月次で集計して」などAIエージェントに指示すると、条件に合致するSQLを実行してデータを編集してOUTPUTしてくれます。
AIエージェントが間違ってデータを書き換えてしまわないよう、ReadOnlyで接続させることもできます。
表でまとめると以下の通りです。
| 機能 | 目的 | できること | メリット | 向いている場面 |
|---|---|---|---|---|
| SubAgents | 専門タスクの分離 | レビュー、セキュリティ診断、品質管理などを別エージェントに委譲 | メインのコンテキストを消費しない。専門家ロールを明確化 | 大規模開発、複数観点のレビューが必要な場面 |
| Agent Skills | 再利用可能なルール集 | コーディング規約、API仕様、レビュー観点などを必要時に読み込む | CLAUDE.md の肥大化を防ぎ、必要な時だけ読み込める | プロジェクトのルールを体系化したい時 |
| MCP | 外部ツール・データとの接続 | API呼び出し、DBクエリ、OSSドキュメント参照など | 最新情報を取得し、LLMの知識不足を補える | ライブラリ調査、DB分析、外部サービス連携 |
品質は人間が担保すること
最初にユニットテストコードを作成し、そのあとでプロダクションコードを作成するTDD（Test Driven Development）手法は、AIエージェントの得意とするところです。CLAUDE.mdに、必ずTDDで作業を進める指示を出しておくとよいでしょう。
ただし、複数の機能をまたがるテストや、画面操作を伴うテストでは、TDDは必ずしも有効ではありません。
前述の通り、AIエージェントはコンテキストウィンドウが枯渇した場合に、指示内容を忘れて適当な作業をしてしまうことがあります。テストコードを作成するために多くのコードを読み込む必要がある場合、AIエージェントは有効なテストケースを作成できない可能性があります。
結合試験や総合試験、受入試験については、AIエージェントにチェックリストのたたき台を作ってもらい、ドメイン知識を持った人間がレビューして試験項目を増やして、人間自身が手動でテストを行うとよいでしょう。
プロジェクトが大きくなると、レビューでは見つけきれなかったAIエージェントの実装漏れなどを多く発見することができます。
AIエージェントの「テストもすべて通って、完璧です」という言葉に騙されず、じっくり時間をかけて人間が手動でテストを行いましょう。
まとめ
-
エンジニアの役割は「実装者」から「指揮・レビュー担当」へシフトしている
AIエージェントが実装や調査を担う時代では、重要なのは「正しく指示を出す力」と「成果物を見抜くレビュー力」です。深いドメイン知識と設計理解を持つ人材が、より価値を発揮します。 -
バイブコーディングではなく、仕様書駆動開発（SDD）を徹底する
会話ベースの開発は短期的には楽ですが、長期運用で破綻します。仕様書を作成し、タスク分解し、短いPR単位で進めることで、AIとの協働を安定させられます。 -
コンテキスト管理と品質担保は人間の責任
SubAgents・Agent Skills・MCPを活用してコンテキスト消費を最適化しつつ、最終的な品質保証（特に結合・総合試験）は人間が行う必要があります。AIの「完璧です」を鵜呑みにしてはいけません。
ソフトウェアエンジニアとしては、なかなか大変な時代になってきましたが、まだAIエージェントを使ったことがない人は、Claude CodeのPro版を契約して、GitHub Spec Kitで小さなアプリケーションを開発してみることをお勧めします。
一緒にAIエージェント開発について学んでいきたいなど、ご興味を持たれた方は、弊社ホームページからお問い合わせいただければ幸いです。