エージェント型コーディングは、テック業界の基準からしても前例のない速度で変化しています。オンラインで利用できるチュートリアルやリソースの多くは、シンプルなグリーンフィールドのシナリオにおける個別の機能を扱うものがほとんどです。
Bobの構築と、幅広い業界のフィールド実践者との交流を通じて、Bobの有効性と使用体験を向上させる一連のコンセプトが浮かび上がってきました。
これらのコンセプトは、主流でない技術を使用する複雑なプロジェクトにも適用できます。
コンセプト1: サイクル — 探索、計画、実装、検証
エージェント型ソフトウェアエンジニアリングで最も一般的な失敗パターンは、構造の欠如です。会話の一貫性が構造を模倣しているように見えるため、実装のすべてのステップを1つのチャット会話に詰め込みたくなります。セッションは生産的に感じられますが、そのコストはレビュー時になって初めて明らかになります。
手でコードを書く行為は、それ自体に構造を課していました。実装にはコストがかかるため、実装前に計画することは直感的に合理的に感じられました。入力しながら理解が積み上がり、間違った前提はそのプロセスの中で表面化することが多かったのです。 AIエージェントはそのような摩擦を取り除きました。コードは今や安価であり、それが構造に対する直感も失わせました。かつては遅さの副産物だった構造を、今は意識的に作り出さなければなりません。
このサイクルを意識的に活用することで、その構造を提供できます:
- 探索は理解を生む
- 計画は意思決定を生む
- 実装はコードを生む
- 検証はエビデンスを生む
このサイクルに従うことで、集中力を保ち、構造的に作業を進め、より速く、より一貫して目標を達成できます。
サイクルを1周するのに20分かかる場合も、3日かかる場合もあります。1周の中にサブサイクルが含まれることもあり、各フェーズへの時間配分はタスクによって大きく異なります。
サイクルの詳細なウォークスルーは、以下の詳細解説: サイクルを実行するで確認できます。
コンセプト2: コンテキストウィンドウは希少なリソース
コンテキストウィンドウを意識することは、最もリターンの高い習慣です。
コンテキストウィンドウとは?
モデルはステートレスです。チャットはメモリを持つ継続セッションではなく、各ターンでそれまでのすべてのメッセージを再送し、新しい回答を末尾に追加します。コンテキストウィンドウとは、そのターンの1回でモデルが受け取ることのできる入力の最大量です。Bob V2ではそれが270kトークンです（コンテキストウィンドウ管理）。
最初のメッセージを送る前から、ウィンドウはすでに埋まり始めています:
- 最初からロードされるもの: Bobのシステムプロンプト、アクティブなモードの説明、リポジトリの
agents.md、および接続されているすべてのModel Context Protocol（MCP）ツールの説明（BobのMCP）。 - セッション中に見えない形で追加されるもの: ファイルの読み取り、ツールの結果、Bobが取り込むskillファイル、サブエージェントの出力。
ウィンドウが満杯になると、Bobは会話を圧縮します。Bobはそれまでの会話をサマリーに置き換え、作業を継続します。これによりセッションは継続されますが、設計上、情報は失われます。どの詳細が残るかはBobが自動的に判断し、残らなかった情報は何も通知されません。2回圧縮されたセッションは、サマリーのサマリーの上で動いていることになります。
MCPの呼び出し1回で数万トークンが返ることがあり、ファイルを連続して読み込むとセッション前半に議論した内容が希薄化されます。モードの説明、rulesファイル、MCPサーバーはより緩やかに、より目立たない形でウィンドウを消費します。Bobはソース別にウィンドウの内訳を表示するため、設定が増えてきたら定期的にその内訳を確認する価値があります。
Bobcoinsは主にトークン単位で計算されます。そのため、会話のコストはその長さに対して二次関数的に増大します。長い会話は短い会話よりもはるかに多くのBobcoinsを消費します！（Bobcoinsドキュメント）
コンテキストウィンドウと協調して働く
- 作業を別々の会話に分割する。 タスク1つにセッション1つ。コードにおける単一責任の原則と同じ考え方です。会話には「コンポーネントXのアーキテクチャ図を作成する」や「機能Yの実装計画を作成する」といった、1つの存在理由があるべきです。うまくいかなかったアプローチも含め、コンテキストウィンドウにあるものすべてが次の動作に影響します。行き詰まったセッションは行き詰まったままになりやすく、それは失敗した試みがウィンドウに残っており、モデルがそれをこのタスクの性質を示す証拠として読み取るからです（コンテキストポイズニング）。
- Bobと議論するのではなくロールバックする。 会話が望ましくない方向に進んだら、最後の良いメッセージにロールバックし、そのメッセージを修正して続行します。これによりBobがローカルで加えた変更もすべて元に戻り、コンテキストウィンドウを小さくクリーンに保てます（ロールバック）。
- 保存する価値のあるものはファイルに残す、チャットには残さない。 計画、調査結果、意思決定はファイルに保存します。同僚はmarkdownドキュメントをレビューして新しいセッションに渡すことができますが、チャットログにはどちらもできません。
- サブエージェントを使って大量の作業をコンテキストウィンドウから切り離す。 Bobがいつ実行するかを判断し、調査結果だけが返ってきます。誰も読む必要のない出力が生成されるようなタスクでは、直接指示することもできます（サブエージェント）。
- コンテキストウィンドウに入るものと、それが価値をもたらすかどうかを意識する。 ガイドとセンサーを定期的に見直し（次のトピックで説明）、改善に時間を費やす。
コンセプト3: 2種類の構成要素 — ガイドとセンサー
長期プロジェクトにおいて、コードベースが良くなるか悪くなるかは、Bobよりもむしろ何がその作業を形成し、出力をチェックするかによって決まります。利用できる構成要素は多数あります: rules、skills、modes、hooks、サブエージェント、外部リンター、レビューエージェント。それらのほとんどは2つの仕事のどちらかを担います。
- ガイドはBobが作業する前または作業中に方向を示します（フィードフォワード）。 Rules、skills、modesはすべてガイドです。
- センサーはBobが行動した後に報告します（フィードバック）。 テスト、リンター、型チェッカー、インタラクティブなブラウザセッション、レビューエージェントはすべてセンサーです。
1. ガイド
Bobに提供されて作業を誘導するものはすべてガイドです。それを支援する主な構成要素が3つあり、入力したプロンプトに加えてテキストをコンテキストウィンドウに挿入することで機能します。それらは、テキストがいつ届くか、何がそれをトリガーするかによって異なります。
- Rulesは常に有効です。
リポジトリルートの
agents.mdが主要なものであり、その主なアドバイスは短く保つことです。すべての行が毎ターン注意を競い合うため、rulesファイルが長いとBobはその中の個別のルールに従うのが苦手になります（rules）。 - Modesはユーザーが有効化します。 統合されているmodesは: Askは読み取り専用です。Planは計画プロセスを経て結果をAgentに渡し、Agentが行動します。カスタムmodesも簡単に追加できます（modes、カスタムモードの追加）。
- SkillsはBobが関連すると判断したときに有効化します。 skillの説明文（小さなもの）だけが常に有効です。skillの本体は必要なときだけコンテキストにロードされます。これによりskillはトークン効率に非常に優れています（skills）。
rulesファイルにあるものはすべて、そのターンに必要かどうかにかかわらず毎ターントークンを消費します。そのため最小限に保ち、残りは必要になるまで待機させましょう。
2. センサー
Bobが生成した作業についてフィードバックを与えるものはすべてセンサーです。どのシグナルが有用かはコードベースとスタックによって異なるため、必要なセット はプロジェクトごとに違い、実際に組み立てるには相応の労力がかかります。最も価値のあるセンサーはマシンで実行可能で、実装フェーズ中にBobが実行します。センサーは2つのカテゴリに分けられます。
- 計算的センサーは決定論的です: テスト、リンター、型チェッカー、コンパイラ。判定は正確で再現可能であり、Bobが頻繁に実行できるほど安価です。カバレッジはチームが構築・維持するシステムによって制限されます。
- AIベースのセンサーは柔軟で非決定論的です。レビューエージェントは意図を読み取り、リンターにルールがないものについても確認します。出力は測定値ではなく判断であり、実行ごとに異なります。コストと所要時間により、使用頻度には制限があります（コードレビュー）。
それらを組み込む方法はいくつかあり、摩擦の少ない順に挙げると:
- Hooksは最も摩擦の少ない決定論的オプションです。チェックは固定のポイントで毎回実行され、Bobが関連すると判断したかどうかに関わりません。hooksドキュメントを参照。
- Skillsはガイドとしてよく使われますが、レビューを実行するskillはセンサーであり、非決定論的なチェックを追加する最も摩擦の少ない方法です。skillsドキュメントを参照。
- **継続的インテグレーション（CI）**は、チーム全体のすべてのpull requestのパイプラインにレビューエージェントを配置します。動作中のPRレビューエージェントを参照。
詳細解説: サイクルを実行する
フェーズの境界はコンテキストの境界でもあり、それがフェーズを明確に分ける実践的な理由です: 探索の雑談は、コードが書かれる会話に持ち込む必要はありません。
1. 探索
探索はあなたの役割と手元のタスクによって大きく異なります。新しいコードベースへのオンボーディングの場合もあれば、大規模なリファクタリングの影響範囲の見積もりの場合もあります。いくつかの例:
- Bobに既存システムのアーキテクチャ図を作成させる（変更前に）。アーキテクチャ図生成チュートリアル、または動画での解説を参照。
- 2つの視点からカスタマイズされた入門ウォークスルーを依頼する: 製品を使うユーザーとしての視点と、コードを読む開発者としての視点で。自分の専門知識とタスクに関する情報を提供すると、ドキュメントの精度が上がります（コードベースの調査）。
- IBM ZとIBM iでは、プラットフォーム固有のオプションを使用する。 これらのシステムでの探索の問題は異なり、プレミアムパッケージで提供される専門ツールから大きな恩恵を受けます。IBM Z用プレミアムパッケージ（ドキュメント）とIBM i用プレミアムパッケージ（ドキュメント）を参照。
探索には、後で削除するつもりのものを構築することも含まれる場合があります。実装が安価になった今、狭いプロトタイプはアプローチがコードベースに通用するかどうかを確認する最速の方法です。Kent Beckは25年前にこれをスパイク実装と呼び、その規律は今も同じです: 何かを学ぶために構築し、学びは残し、コードは捨てる。
安価な実装は、アーキテクチャとコード品質の価値を下げるのではなく、むしろ高めます。今や動くコードを大量に生産することは簡単ですが、それが間違っているということも起こり得ます。
2. 計画
計画フェーズは最大のレバレッジがある場所です。計画が正しく把握したことはすべて2倍の恩恵をもたらします: 実装時に1回、そして変更が作者の手を離れて同僚がレビューしなければならないときにもう1回。
良い計画に必要なもの:
- 短く、かつ正確であること。 計画は読まれなければなりません。
- 不確かな部分も含めて、意図した成果を明示すること。 何が不明かを把握することが作業の大半であり、それを解明することが残りです。
- ファイルに保存すること。 計画はチャットセッションの中に置くべきではありません。
計画を作成する方法は多数ありますが、統合されたPlanモードが最も始めやすい場所です（このチュートリアルのように）。
Planモードは同意的になるように設計されており、ギャップを埋める傾向があります。多くのケースで素早いイテレーションを可能にする一方で、より厳密さが必要な場合もあります。前提が間違っていても、それに疑問を呈することなく、その前提をもとに有能な計画を作ることがあります。
計画に反論する専用のskill — たとえばMatt Pocockのgrill-me — は、前提がコードになる前に精査を得る最も安価な方法です。
スペック駆動開発（SDD）について。 この用語は幅広い意味を持ち、まだ変化し続けています。これを二者択一の決定として扱う人が多いですが、実際にはスペクトルに近いものです:
- スペックファースト: 計画が実装に先行します。これはほぼ交渉の余地がありません。
- スペックアンカード: 実装後もスペックが残り、ドキュメントとして、また実装が満たすべき基準として機能します。
- スペックアズソース: スペックがソースファイルです。人間はスペックを編集し、コードは編集しません。
どのレベルが適切かはチーム、コードベースの重要度・成熟度、そして業界によって異なります。SDDの高いレベルに伴うオーバーヘッドは、高速なイテレーションには辛い場合があります。自動車業界では、スペック駆動開発がAIより数十年前から存在しており、SDDは既存の慣行に非常によく適合しています。
3. 実装
実装は直接的なフェーズであり、Bobがほぼすべてを処理します。
Bobの作業を見守り、明確化のために介入することは任意ですが、しばしば有用です。その頻度をシグナルとして扱いましょう: 常に介入が必要な場合は問題が計画にあり、修正は前に戻ることであって、修正を続けることではありません。
実装全体を捨ててPlanモードに戻ることを恐れないでください。コードは安価な部分です。
4. 検証
検証は2つの異なるカテゴリに分かれます: 自動検証と手動検証。
自動検証は、Bobが利用できるセンサーまたはhooksによって強制されるセンサーによって駆動されます。人間の介入なしに、実装フェーズ中に頻繁に実行されます。主なカテゴリといくつかの一般的な例を示します:
- 妥当性: コンパイル、型チェック、パースは通るか?
- 計測: pass/fail、型カバレッジ
- ツール:
tsc、mypy、cargo check、javac
- 動作: 正しいことを行うか?
- 計測: パス率、ブランチカバレッジ
- ユニットテスト、インテグレーションテスト、エンドツーエンドテスト
- ツール:
pytest、Jest、Playwright、Stryker
- 保守性: このコードは保持する価値があるか?
- 計測: 複雑さ、重複、境界違反
- ツール: ESLint、Ruff、Lizard、ArchUnit
- セキュリティ: このコードは安全か?
- 計測: 深刻度別の検出数、CVE
- ツール: Semgrep、CodeQL、gitleaks、
npm audit
これらにより、Bobは自分自身のミスを発見し、実装フェーズ中に品質を向上させることができます。良いテストカバレッジはリグレッションに対する不可欠な保護であり、Bobが何も壊していないことを確認します。
このサイクルでは、検証はループの最後に独立したフェーズとして挙げられており、これは主に手動検証を指します。 手動検証は、変更を実行して観察された動作を計画で指定された動作と比較することから始まります。不一致は主に2つの原因のどちらかに絞られます:
- 実装が計画から逸脱した。修正はコードにあります。
- 計画が意図したものを反映していない。計画を精緻化する必要があります。こちらのほうがはるかに一般的です。
手動検査は、計画と実装の両方を同時にテストします。
追加の検証はCI/CDパイプラインで行うべきです。これはソフトウェアエンジニアリングにおけるよく確立された慣行ですが、ヘッドレスコーディングエージェントを使用することでさらに改善できます。一例として、Bob Shellを通じて実行されるすべてのpull requestの自動レビューは、人間のレビュアーを置き換えるのではなく補完します。動作中のPRレビューエージェントの動画とBob Shellを非インタラクティブモードで実行するドキュメントを参照してください。
チームでの作業
前のセクションで説明した内容はすべて、1人の開発者の内部ループを説明しています。外部ループは、変更がレビューキューに移動したときに始まります。すべてのdiffはより速く届くようになり、その理由の説明は少なくなる一方、レビュアーはより多くのものを読み、より少ないコンテキストの中でそれをこなさなければなりません。
エビデンスは作業とともに伝わらなければなりません。なぜは以前よりもどのようにより重要であり、それはどのようにがもはや生産するのに高価な部分ではないからです。
実践的には、計画が変更とともに伝わることを意味します: チームはそれをpull requestに添付するか、レビューと並んで元のissueに追加します。メカニズムはツールによって異なります。
外部ループがチームのプロセスに何をするかは、それ自体が別のテーマであり、後の記事で扱います。
プロンプトについてのいくつかの考察
過去数年間、LLMへの適切なプロンプトに大きな重点が置かれており、「プロンプトエンジニア」という職種カテゴリーまで生まれました。現時点では、プロンプトの多くはハーネス内で処理されています。特殊なプロンプティングテクニックの重要性は、方法論的アプローチを優先する形で低下しています。いくつかのガイドラインを示します:
- 反復はプロンプトより優れている。 Bobが求めたこと以外のことをした場合は、ロールバックしてそれを引き起こしたメッセージを書き直す。修正を続けると、間違った回答、それへの苦情、再試行のすべてがウィンドウに残ります。
- 方法論はプロンプトより優れている。 プロンプトは1つのセッションにスコープが限定されます。rulesファイル、またはBob自身が実行できるチェックは、それを生み出したセッションの後のすべてのセッションでも機能し続けます。これが積み重なっていく唯一の種類の投資です。
- シニアエンジニアが受けるようなブリーフをBobに与える。 有能な同僚に曖昧なタスクを渡すと、何が完了とみなされるか、何に触れてよいかを聞いてきます。Bobは聞いてこないので、両方をメッセージに書き込んでください。
- しないことではなく、することを伝える。 「クラスコンポーネントを使うな」は1つのオプションを除外し、残りを開いたままにします。するとBobは残りから選ぶことになり、それもまた推測です。代わりにターゲットを明示する — hooksを使ったファンクションコンポーネント — ことで、1ターンで閉じられます。
- 2回以上与えた指示はファイルに書く。 それが
agents.mdとskillsの目的です。 - より詳細なプロンプティングの手順は効果的なプロンプトの書き方チュートリアルにあります。
重要なポイント
- 構造の欠如が最大の問題です。 探索 → 計画 → 実装 → 検証のサイクルに従うことで、集中力を保ち、より速く、より一貫して目標を達成できます。
- コンテキストは希少なリソースであり、フェーズはコンテキストの境界です。 探索の雑談を実装に持ち込まないでください。
- 計画はレビューの成果物です。 計画をレビューすることは、差分をレビューするよりも優れています — 作者にとっても、レビュアーにとっても。
- 保存する価値のあるものはチャットから出す。 計画、意思決定、調査結果はファイルに保存します。ファイルは差分を取り、レビューし、バージョン管理し、別のエージェントに渡すことができます。
- 検証はマシンで実行可能であるべきです。これは計画中に設計しなければならず、後から発見するものではありません。
参考資料とさらなる読み物
- Simon Willison, Agentic engineering patterns
- Birgitta Böckeler, Harness engineering
IBM Bobドキュメントとチュートリアル: