この記事は、サイバーエージェントの 2025 年デベロッパー Advent Calendar の 13 日目として書かれたもので、著者は サイバーエージェント の生成 AI およびバックエンドのテックリードとして、著者が「Spec 駆動開発基盤」と呼ぶものの上で既存の大規模アプリケーションのリニューアルを推進している。著者はこの取り組みを、単に AI エージェントツールを導入することにとどまらず、コード生成、仕様書の作成、プロジェクト管理、運用をプロンプトベースで構築・運用できるよう、既存のシステムとワークフローを作り直すものだと説明している。執筆時点で、この取り組みは PoC の段階にあった。
記事はこの取り組みを、サイバーエージェントがプロダクト開発チーム向けに定めた AI 成熟度レベル の上に位置付け、最上位のレベル（L4「PRD to Production」）に到達するには 仕様駆動開発 への転換が必要だと論じ、その転換の成否を分けるものとして コンテキストエンジニアリング を挙げている。記事の主な貢献は、著者自身の PoC から導き出された カスタムスラッシュコマンド の設計プラクティス群である。
要点
- 記事は仕様駆動開発を、仕様書を人間が読むためのドキュメントとしてではなく、AI がコードを生成するための構造化されたコンテキストとして再定義する手法と定義しており、これによりドキュメントがコードを生み出す信頼できる唯一の情報源（single source of truth）になるとしている。
- この手法の主な利点は、プロセスに対する「健全な強制力」だと論じる。仕様書を書いたり更新したりしなければ正しいコードを生成できないため、ドキュメントは実装と歩調を合わせ続け、ドキュメントが最新であれば、新しく加わったメンバーは仕様書を読む代わりに AI エージェントや RAG システムに機能の仕様を尋ねられるようになる。
- 一方で、基盤そのものの構築は難しく、未成熟な基盤は新たな技術的負債となって、開発チームに非効率なプロセスを強いることになると警告している。
- コンテキストエンジニアリングを、LLM に与える入力情報の質と量を戦略的に設計・制御することと定義し、出力がうまくいかないプロンプトを診断して修正するための手段として扱っている。
- コンテキストエンジニアリングが対処する 3 つのコンテキストの問題を挙げている。コンテキストロット（記事は、長いセッションの中で LLM が保持している前提が古くなっていくことだと説明し、その主な原因を入力トークンが多すぎて初期の指示が埋もれてしまうことに帰している）、コンテキストの混乱、そして コンテキストポイズニング である。
- 実装手段としてカスタムスラッシュコマンドを提示し、3 つの利点を挙げている。標準化され再現性のあるプロンプトエンジニアリング、読み込むべき仕様書ファイルをコマンドで指定することによるコンテキスト注入の自動化、そしてプロンプトをリポジトリ内のコードとしてバージョン管理できることである。
- 単一責任：Web 調査、ドキュメント作成、ガイドラインのチェック、ドキュメントの修正を連結した初期のコマンドは、ノイズの多い検索結果に引きずられ、仕様から外れたコードを生成し、ガイドラインのチェックを飛ばしてしまった。これを順番に実行する別々のコマンド（
create-reference、create-best-practices、create-design-doc、review-architecture）に分割したところ、出力の品質が向上し、誤った指示の箇所も特定しやすくなった。これは著者自身の PoC での経験である。 - コンテキストの最小化：無関係なエージェント用ファイルや大規模なコードベース全体など、不要なドキュメントを読み込むと S/N 比が下がり、重要な指示が埋もれ、コストとレイテンシも増す。記事は必要最小限の情報だけを注入することを推奨している。
- 出力とテンプレートの事前定義：記事はコマンドを関数（入力となるコンテキストとプロンプト、ロジック、出力される成果物）になぞらえ、まず出力の構造を定義するよう求め、テンプレートを使って出力の形式を強制する。モデルが賢いほど、自由を与えると形式がぶれるというパラドックスも述べている。
- コマンドをテスト可能にする：ToDo アプリのようなドメインに依存しないサンドボックスで、まず人間が理想的な出力をゴールデンデータとして書き、コマンドの出力がそれに一致するまで調整する。記事はこのゴールデンマスター方式をコマンドの品質管理の手法として提案している。
- 1 コマンド 1 成果物：レビューや調査のコマンドも含め、すべてのコマンドは結果をコンソールに残すのではなく Markdown ファイルとして永続化すべきだとする。ファイルがコマンド間のインターフェースとなり、読み込みの多いレビューのステップと書き込みのステップを、その間でコンテキストをクリアして切り離せるようになる。ただし、分割を細かくしすぎるとコマンドの実行順序を管理する認知コストが上がることにも触れている。
- ツール依存の回避：ツール固有の機能やツール名はプロンプトに含めず、コマンドの中核となるロジックは
docs/配下に置き、ツール固有の設定はそれを参照する薄いラッパーとしてのみ機能させるべきだとする。著者は Claude Code の SubAgents を採用しなかった。PoC では委譲のほうが通常のコマンドよりも制御にコストがかかり、品質も不安定だったと報告しており、SubAgent が必要だと感じるのはタスクが複雑すぎる兆候だと結論付けている。 - シンプルな指示：プロンプト内の長い説明や if-else の分岐は、コマンドが多くを抱え込みすぎており分割すべきだというシグナルとして扱われる。
- 著者は、仕様駆動開発はまず自分が管理できる範囲 ―― 自分自身のタスクや小さなチーム ―― で導入し、徐々に広げていくよう勧めている。ステークホルダーの多い成熟した組織ほど、ワークフローと成果物の定義が難しいためである。
背景
これらのプラクティスはいずれも、1 社の内部で進行中の PoC から得られた著者自身の知見であり、計測された結果や確立された慣行ではない。記事自身もそれらを PoC を通じて得た知見として位置付け、そのことを明言している。冒頭で示される 4 段階の成熟度モデルは、サイバーエージェント独自の社内定義として提示されている。