AI コーディングエージェントと協働する Design Doc 作成フロー - 実践から学ぶコンテキストエンジニアリング

本記事は、#IVRy_AIブログリレー の 9 月 8 日（6 日目）の記事です。昨日は、インサイドセールスののすけさんが「若手3人が語る！成果を加速させるインサイドセールス×AI活用の最前線」という記事を公開しました。
https://note.com/n0suke_/n/n61d69d08a3d5

ブログリレーの記事一覧は「IVRy AIブログリレー全記事まとめ」をぜひご覧ください。

1. なぜ今 Design Doc x AI なのか

みなさんご存知のように最近の LLM の進化により、エンジニアリングの現場は劇的に変化しています。

Claude Code や Cursor、Codex といったツールの登場により、実際のコーディング作業の多くを AI に移譲できるようになってきました。社内でも「ほとんどコードを書かずに日本語で指示を出すだけ」という声が上がるほど、開発体験は根本的に変わりつつあります。

一方で、この変化は新たな課題を生まれています。AI が生成するコードの量とスピードは人間のレビュー能力を超えてきているといっても良いでしょう。Dev Class の調査では、すでに 3 分の 1 のエンジニアが AI 生成コードをデプロイ前に十分レビューできていないという結果も出ています。「人間によるコードレビューは持続可能ではなくなっている」と同調査では触れられています。

この状況下で、注目したのがコードを書く前の設計フェーズ、つまり Design Doc の作成プロセスです。社内のエンジニアメンバーとのディスカッションを重ねる中で、AI に実装を任せる前にしっかりとした設計書を作成し、そこで品質を担保するアプローチが有効ではないかという仮説に至りました。従来の Design Doc 作成は工数が大きく、実装と乖離しやすいという課題もありました。また、今の AI では普段 Design Doc を書くべきとされるスコープよりも少し狭い段階で始めるのが現実的だと考えました。これらの叩き台を作るところは今の AI コーディングツールでも十分できるのではないか？というのが出発点でした。
現在では、このような設計駆動開発を実践した IDE として Kiro が有名だと思います。

このあたりの AI コーディングツールを中心としたエンジニアリングについては別途スライドで公開している資料があるので興味ある方はみてみてください。

2. エンジニアと AI の協働実験 - 第 １ ステップ

そのため、Claude Code で使える Design Doc 作成フローというのを題材にして取り組んでみました。最初は、Cladue Code Action として GitHub Actions 経由で発火できるようにしておくことで、Design Doc の作成を IDE に向き合わずともできる体験を実現できないか？と始めてみました。

第一弾としては、とある Amazon DynamoDB に対して格納するデータの上限サイズに関連する技術的課題が露呈しており、そこに対して Design Doc を作成してみることにしました。
背景情報としては、タスク管理ツールとして利用している Linear と、スタック情報が蓄積されている Notion に背景情報を入力として、Claude Code Action 経由で Design Doc を作成してもらうというものです。
ここの発火までの流れについても、Zapier などを使ってどうにか開発フローに溶け込ませるような流れにできないかなと試行錯誤していました。

そして、最初の結果をエンジニアの negipo さんにレビューしていただいたところ、いろいろな課題感が浮き彫りになりました。（negipo さんの入社エントリー）

実行の仕方が難しい

• マニュアルが存在していない
• 固定フローを想定したものだったのでアドホックにやろうとする時の事前設定が複雑すぎる
• Notion、Linear、GitHub など入力インターフェースが分散していて、どこに何を入力すればいいのかわからない。
• Zapier の設定不備によりそもそも動作しない

このようなまあまあ散々な結果となっていました。

これだけ使いにくいものでしたが、 negipo さんに実際に使っていただき、貴重なフィードバックを得ることができました。やはりこうした取り組みは 1 人では限界があり、チームでの試行錯誤が不可欠だと実感しました。

内容的にも使用に耐えるものではない

また、内容面においても、

• 大枠として想定していた方向性は問題なし
• データの読み込みにのみに焦点があたっており、更新系についての考慮が漏れていた
• マルチリポジトリに渡った理解ができていない（単一リポジトリのみで実行しているため）
• DynamoDB の容量問題を解決するはずだったのに、音声認識精度改善についての調査報告が入っていた（機械学習特有の調査も同時に行わせる想定だったため、Claude Code 側が無理やり調査を行ってくれた模様）

のような問題が発生していました。

また、セキュリティリスクやプライバシーリスクの項をテンプレートで設けていたところ、これらの項目については過度に詳細な検討がなされており、本来フォーカスしてほしい設計の革新部分がむしろ曖昧になっていたというバランスの悪さも目立ちました。

そのほかにも、negipo さんよりは、

「アイブリーのサービス全体のコンテキストを持っていないために気の回し方が不自然」

といった指摘も受けましたが、一方で「サイズによって複数のストラテジを組み合わせる方針は思いついていなかった」という部分的な評価もあり、完成品を作るというよりも 設計における幅を広げる という面での有効性が垣間見えた結果となりました。

3. エンジニアと AI の協働実験 - 改善ステップ

第一弾となるものについて得られたフィードバックやインサイトをベースとして、Design Doc 作成において使用していたプロンプト周りの大幅なアップデートを加えました。

具体的には、完成品をいきなり出すのではなく、設計における選択肢の幅を出すことを目的 としてアップデートを行いました。

• 複数の候補を出させてそれらについて同じ粒度で詳細化した上で比較検討するように Design Doc のテンプレートおよびプロンプトの調整
• 不要な機械学習系の調査については行わないように調整（必要に応じて行うように判断を任せるスタンス）
• 成果物として Notion に出させる想定だったが、ローカルの Markdown ファイルとして出力する形に変更（Notion への書き込みで余分な token 消費が行われる）
• Claude Code Action ではなく、ローカルの Claude Code のカスタムコマンドとして動かすように変更

上記のような改善を加えた結果、かなり前向きなフィードバックをいただくことができました。

これらを踏まえることで、アシスタントといった立ち位置での Design Doc 作成を行うことができるようになりました。

4. コンテキストエンジニアリングの実践と課題

上記の取り組みを踏まえて、12-Factor Agentsでも言及されているようなコンテキストエンジニアリング観点に落とし込んだ時の実践もいくつか行ったため、そちらについていくつかかいつまんで紹介します。

実践内容

情報源の整備（MCP）

MCP を通じて、AI コーディングツールがさまざまな情報にアクセスしやすいように工夫を行いました。MCP として整備したのは、すでに触れていますが、下記のツールを MCP として入れています。

• Linear
• Notion
• Slack (Ubie さんで公開されているもの) を活用
• o3-search-mcp

また、LLM ごとによって考えのクセなどが異なることと、当時は Claude Code 自身の Web 検索の挙動が安定していなかったこともあり、MCP 経由で Web 検索を有効化した MCP である o3-search-mcp を導入することで、成果物に対するセルフレビューや Web 調査についての外出しを行うといった工夫も入れていました。

当たり前ですが、これらを用意するだけでは不十分ではあり、実装の背景となる情報を Notion なり Linear なりで詳細に書いておく必要があります。これらのドキュメンテーション周りの整備についてはまだまだ課題感が残るものとなってます。

段階的アプローチによる品質の向上

また、今回 Design Doc の作成においてはいきなり完成品を作らせるのではなく、いくつかのフェーズに分けて作成を行わせています。

1. 調査フェーズ: 与えられた情報やコードベースを調査する
2. 設計フェーズ: 調査フェーズで得られた情報をベースに、設計方針をたてる
3. 文書化フェーズ: 設計した内容をドラフトとして書き起こす
4. レビューフェーズ: o3-search-mcp 経由でセルフレビューを実施し、その内容を踏まえた上でアップデートを行う

このようなフェーズを区切ることで、1 つ 1 のフェーズの成果物がコンテキストとして出てくるという形になります。こちらについても、ある意味コンテキストエンジニアリングと解釈できるものになると思っています。

また、文書を書かせるところでは 箇条書きを原則禁止 というルールを適用しています。個人の経験上、AI に書かせたドキュメントで箇条書きされた箇所があるとどうしても目が箇条書きを上滑りしてしまう経験がありました。そのため、上滑りしない & 論理関係を明文化させることによる読者の理解向上を意図して、原則文章（Narrative）形式での記載を強制させました。

プロンプト経由でこれらを指示することで、人間にとって解釈が可能で、かつアクションが打てるものとして有用性をましたものと言えます。

その他プロンプトでの工夫

上記のプロンプトの改善で工夫したところとしては、AI そのものにプロンプトを改善させたことも挙げられます。すでに実践されているケースは多いと思うのですが、Anthropic 社によって公開されているプロンプトエンジニアリングに関するドキュメントを読み込ませながらアップデートを加えることで、よりシンプルかつ明瞭なプロンプトにアップデートされました。

さらに、手続き型での指示も加えつつも 成果物とその成功基準を明確に定義 したのもプロンプトを構築でのポイントです。AI に対して「テストが通るようになるまで実装を進めて」と指示するのと同じなのですが、「具体的にどういう状態になっていることが望ましいのか？」というのを宣言的に定義することによって、途中寄り道してしまったとしても AI 自体が目的を見失わずに目的を完遂できるようになります。
とはいえ、進め方についてはある程度ゆるいレールを敷いてあげることによって、ベースラインとなるクオリティを担保するような工夫をしています。
この２つのバランスを意識することも、プロンプトを構築する上で工夫したポイントでした。

実践における課題

GitHub Actions 上で MCP サーバーを動かす

一方で、ローカルで実現する分には問題ないのですが今回利用している MCP サーバーでは Machine to Machine での認証・認可に対する整備が発展途上です。そのため、GitHub Actions 上で Claude Code Action を動かす場合は固定の API キーを発行する必要が出てきますし、リモート MCP サーバーではなくローカル MCP サーバーとなるため、手元で Claude Code を動かす時とまた異なった認証・認可の設定を行う必要があります。

OAuth Token ベースでのアクセスになってくれるとセキュリティ的には好ましいのですが、まだそこのサポートは待つ必要がありそうです。

MCP ツールが多すぎることによるコンテキストの圧迫

最近サポートされた Claude Code での /context コマンドで Claude Code 内部でのコンテキストの占有量であったり内訳が見れるようになりました。

MCP tools の中でどこがどれぐらいのトークンを消費しているのかの詳細も見れるようになっています。

 MCP tools · /mcp
...
 └ mcp__notion__notion-create-pages (notion): 4.1k tokens
 └ mcp__notion__notion-update-page (notion): 2.0k tokens
 └ mcp__notion__notion-move-pages (notion): 867 tokens
 └ mcp__notion__notion-duplicate-page (notion): 537 tokens
 └ mcp__notion__notion-create-database (notion): 7.2k tokens
 └ mcp__notion__notion-update-database (notion): 7.0k tokens
 └ mcp__notion__notion-create-comment (notion): 2.0k tokens
...

これで試しに実行してみたところ、MCP tools の項目のみだけで 5 万トークン近くも消費していることになっていました。Claude は 20 万トークンまでしかコンテキストとして考慮できないため、そのうち実に 1/4 をデフォルトで消費している計算です。
これらを深掘りしてみると、Notion 周りで普段使いしていないところで多くのコンテキストを消費していることがわかってきています。
しかしながら、筆者が調査した限りでは個別にこれらの tool をコンテキストから除外するという方法はサポートされていない模様で、現状試行錯誤しているフェーズとなります。

まとめと今後の展望

今回は、AI を活用した Design Doc 作成における実践例について、赤裸々に語りました。
さまざまな難点や考慮事項が発生していく中で、今回取り組んだ題材や個人で行っていた対話フロー周りの改善においては役立てられました。このようにドキュメントそのものは開発に役立つものの 1 つにまで昇華させることができるようになりました。
しかしながら、私個人の野望としては、「AI によって自律的に End-to-End で開発できる領域を広げていく」ところにあります。ここを目指さないとチーム全体の開発生産性を 10 倍、100 倍にすることは不可能なのではないか、とさえ感じています。

今回の、Design Doc の作成のより開発の全体サイクルの中での一部の補助ができそうという見込みができました。今後は開発の流れ全体におけるボトルネックの特定や、ビジネス貢献までを見据えた上での取り組みをしていきたいと思います。

最後に宣伝

2025 年 08 月 22 日に生成 AI に関する書籍を出しました。今回ご紹介したような取り組みの背景となるような知識について、一通り学べるようなものとなってます。
もしよければ、お手に取って読んでいただけると嬉しいです。

Amazon のリンクはこちら
https://www.amazon.co.jp/dp/4296205234

以前書かせていただいた書籍宣伝ブログ
↓↓

https://zenn.dev/ivry/articles/492e8e19de3906

また、IVRy では「イベントや最新ニュース、募集ポジションの情報を受け取りたい」「会社について詳しく話を聞いてみたい」といった方に向けて、キャリア登録やカジュアル面談の機会をご用意しています。ご興味をお持ちいただけた方は、ぜひ以下のページよりご登録・お申し込みください。

https://ivry-jp.notion.site/209eea80adae800483a9d6b239281f1b
https://herp.careers/v1/ivry/wmZiOSAmZ4SQ