AIエージェントに何かを作らせる前に「どこまで仕様を書くべきか」— 初めてのエージェント開発で詰まった壁とその突破口

9月23日、Atomic Objectが「My First Agentic Project: The Blank Page Was the Hardest Part」と題した記事を公開した。AIエージェントを使った初めての開発プロジェクトで直面した「白紙の壁」と、そこから得た実践的な知見について詳しく紹介されている。

「何から書けばいいのか」が最初の壁だった

エージェント開発（Agentic Development）とは、AIエージェントが仕様やコンテキストをもとにコードを自動生成・実装まで担う開発スタイルで、2024年以降急速に注目を集めている。

記事の著者は、Atomic Objectのエージェント開発プレイブックを読み込み、最新のモデルや動向もキャッチアップしていた。それでもプロジェクトが始まると、疑問が噴出した。

「システム全体を最初に設計しなければいけないのか？どれだけの仕様を書いてからコードを書き始めればいい？まさかウォーターフォールに戻るのか？」

問題はツールがコードを書けるかどうかではなかった。「エージェントに何かを作らせる前に、プロダクトのどこまでを"紙の上"に存在させておく必要があるのか」という判断に詰まったのだ。

コンテキストを集めることが突破口になった

最初の一歩になったのは、すでに手元にあるコンテキストを集めてエージェントに渡すことだった。

具体的には以下の素材を用意した。

キックオフミーティングの全文文字起こし（クライアントの言葉や決定事項が含まれている）
Figmaで作成したデザイン（エージェントが目指すべき視覚的なターゲット）
過去のAtomic Objectプロジェクトから引き継いだエージェントスキル集（原文：agent skill library。プロジェクト間で再利用可能なエージェント向け手順・知識のまとまり）

これらを揃えた上で、チーム全体で初期仕様セットを構築した。システム全体の設計が完成していなくても、エージェントが意味のある最初の一歩を踏み出せるだけのコンテキストがあれば十分だ、という考え方に切り替えたことが転機になった。

「すべての決定を事前に予測する必要はない。エージェントが自分の仮定でギャップを埋めてしまわないよう、最低限の方向性を示せばよい」というのが得られた教訓だ。

アジャイルの本質はエージェント開発でも変わらない

Atomic Objectのプレイブックは、Definition（定義）→ Planning（計画）→ Implementation（実装）→ Review（レビュー）というサイクルを提唱している。定義と実装は並行して進み、短いイテレーションでチームの理解とソフトウェアの状態を近い距離に保つ設計だ。

ただし、詳細なプレイブックは「すべてのアーティファクトとセレモニーを完璧に整えてから始めなければ」というプレッシャーを生む側面もある。著者はそれが初期の不安を増幅させたと振り返っている。

重要な点として、プレイブックの序文にも明記されている通り、アジャイル開発の基本原則はエージェント開発でも有効だ。むしろエージェントは「曖昧な指示を大量の誤ったコードに変換する速度」が速いため、明確な方向性・信頼できるテスト・チームの連携がより重要になる、と著者は述べている。

仕様は生きたドキュメントとして変化させ続けること。プロセスは機械的なルールではなくプロジェクトに応じて調整すること。この判断はエンジニアが担い続ける——これらは元記事で著者が実際に経験から導いた結論だ。

エージェントがフロントエンドを組み上げてから、ペースが変わった

デザインを渡したエージェントがフロントエンドを構築し終えると、状況は一変した。

「白紙」が消えた。具体的に触れて確認できるものができた時点で、機能追加のスピードが上がり、仕様上にしか存在しなかった機能が大きな塊として実装されていった。

「ゴールに向かって想定よりずっと速く進んでいた。これらのツールが存在する前には想像もできなかったペースで」

この段階で初めて、ツールが「理論」でなく「実用」として機能していると実感できた、と著者は書いている。

速度が増すほど、テストの重要性も増す

実装が速いと、プロダクトが「完成した」ように見えるのも早い。コア機能がある、画面がデザインと一致している、基本操作が動く——しかしその磨かれた第一印象がコーナーケースや見落とした挙動を隠す。

著者がたどり着いた結論は「エンジニア全員がテスターになる必要がある」だ。

予期しない操作パスを試す
プロダクトをデザインや要件と照らし合わせる
ハッピーパス以外で何が壊れるかを問い続ける

テストは実装フェーズの後に行う作業ではなく、日々のエンジニアリング作業の一部になる。エージェントはテストの作成・実行を補助できるが、「何をテストすべきか」の判断、怪しい挙動の察知、「これはクライアントの問題を本当に解決しているか」という評価は、人間が担い続ける。

次のプロジェクトでやること

著者が次回持ち込む方針は明確だ。

空の仕様を前に悩む時間を減らす
すでにあるコンテキストから始める
検証できる最小のスライスを定義してエージェントに渡す
エージェントが生み出した時間を、作ったものをテストするために使う

「プロセスはプロジェクトに合わせて調整する」という視点も残している。コンテキストが十分なら定義してすぐ着手できるが、探索が先に必要なこともある。どの戦略を選ぶかの判断には、プレイブックが提供するDefinition Strategy chooser（プレイブック内「Managing Project Outcomes」セクションに収録）がチームで何度も参照されたという。

詳細はMy First Agentic Project: The Blank Page Was the Hardest Partを参照していただきたい。