AIコーディングエージェントのための仕様書の準備

AIコーディングエージェントが単なる質問応答ツールから、リポジトリの直接編集、コマンド実行、ブランチ作成、そして人間によるレビューを依頼する能動的な実行者へと進化したことで、作業前に仕様書を作成する重要性が飛躍的に高まっています。これにより、プロンプトの設計を再考する必要があります。エージェントが共有コードベースを操作する場合、プロンプトは個人的なメモではなく、チームに公開されるタスク割り当て書となります。

優れたコーディングエージェント用仕様書は長文である必要はありませんが、次の5つの核心要素を明確に伝える必要があります。タスクの背景（なぜ行うのか）、変更すべき動作、維持すべき制約、正しさを定義する例やシナリオ、そしてレビュアーが確認すべき検証証拠です。これら5要素は、仕様駆動開発、振る舞いシナリオ、イシューテンプレート、軽量設計ドキュメントなど、さまざまな方法論の基盤を形成します。どのフレームワークを採用するにせよ、重要なのは仕様がエージェントに行動に十分なコンテキストを提供し、チームに結果をレビューするための十分な構造を提供することです。

仕様とプロンプトの本質的な違いは、プロンプトが作業を開始するのに適している一方で、セッション履歴の中に消えやすいのに対し、仕様はタスクを具体化し、チームが継続的にレビューできる可視性を持つことです。プライベートプロンプトには略語、欠落したコンテキスト、暗黙の前提が含まれることがあり、これは単独での説明や使い捨てスクリプトでは許容されても、チームでのエンジニアリング作業には弱く、プルリクエストとの比較が難しく、変更理由の理解を妨げます。仕様はタスク割り当てに目に見える形を与え、実装の前・中・後を通じてチームが検査できるようにします。

最も強力な仕様は、小さな振る舞い契約のように機能します。要件はシステムがすべきことを示し、シナリオは具体的な例（多くの場合Given/When/Then形式）を提供し、設計ノートやタスクリストは技術的アプローチを記述します。この分離は、AI支援エンジニアリングにおいて最も有用な規律の1つです。意図と実装が早期に混ざり合うと、エージェントが本来必要な振る舞いを逃し、実装の詳細に過度に適合する可能性があります。アサインメントレイヤーは次の3つの質問を明確に分離します。どの振る舞いを変更すべきか？どの制約や例が正しさを定義するか？現在適切な実装パスは何か？実装はエージェントがコードベースを読むにつれて進化できますが、要件はレビュアーが「この作業は要件を満たしているか？」と問える程度に安定している必要があります。

具体例として、不安定なログインテストの修正を考えます。「不安定なログインテストを修正し、必要なものを更新してください」というプライベートプロンプトは曖昧です。より良い仕様は作業を限定します。観察された問題（コールバックリクエストがセッションレコードより先に到着する）、期待される動作（単一セッション作成とリダイレクト）、制約（認証チェックを弱めない、スリープを追加しない）、検証（該当テストファイルの実行）。これにより、エージェントに境界を与え、レビュアーに比較対象を提供します。

仕様駆動の作業は、チームが仕様を儀式化しなければ、ウォーターフォールモデルと同義ではありません。仕様は軽量で反復可能、既存コードベースを優先し、実装からの学習に応じて変更されるべきです。規律は「コード前に完璧な計画を書く」ことではなく、「可視の意図と実装された現実を同期させ続ける」ことです。

可視のタスク割り当てがあれば、レビュアーの質問は「この差分は問題ないか？」から「この差分は、指定された制約の下で、検査可能な証拠とともに、合意された振る舞い変更を満たしているか？」へと変わります。これはより優れた質問です。仕様はエージェントの開始を助けるだけでなく、チームの整合性を維持します。

AIコーディングセッションは一時的ですが、リポジトリは永続的です。仕様をリポジトリに保存し、機能や変更ごとに整理し、コードとともに更新することで、人間とエージェントの両方に役立つ永続的なコンテキストとなります。エージェントのコンテキストは失われがちですが（チャット履歴のクリア、コンテキストウィンドウの飽和、異なるモデルの使用）、仕様は意図に永続的な居場所を提供します。仕様はコード、テスト、ドキュメントを置き換えるのではなく、それらを結びつけます。

仕様は明確に境界付けられた作業（振る舞い変更、バグ修正、互換性更新、小機能、移行ステップ、CI修復、制約の明確なリファクタリング）に最も適しています。これらのケースでは、チームは望ましい変更を記述し、結果が適合するかを検査できます。AIコーディングエージェントの能力が高まるにつれ、エージェントが満たすべきタスク割り当てを保持することがますます重要になります。この原則は特定のツールを超えて広がります。エージェントが共有コードに作用するなら、その仕様と結果はチームによって検査可能でなければなりません。