AI×システム開発 ― 進め方とドキュメント整備のリアル

こんにちは。株式会社JMDC データウェアハウス開発部の川島です。

今年、JMDCではアドベントカレンダーに参加しています。

本記事は、JMDC Advent Calendar 2025 20日目の記事です。

1.はじめに
2.取り組みの内容
3.実際にやってみた結果
3-1. 開発が速くなった？
3-2. アーキテクチャ設計における人間の責任と重要性
3-3. AIにエラー解決を任せると堂々巡りする
4.今後の展望

1.はじめに

JMDCで使用可能なAI環境のうち、Google WorkspaceのGeminiとGitHubのGitHub Copilotの2つを中心に利用しています。
2025年上期においては、開発工程でGitHub Copilotを用いることで、開発作業の支援という形でAIを活用しておりました。
一歩踏み込んでよりAIを本格的に開発工程に組み込むため、GitHub CopilotのAgentモードを活用するために取り組んだ内容をご紹介します。

2.取り組みの内容

GitHub CopilotのAgentモードを最大限に活用するためには、AIに適切な形で情報をインプットできるようにする必要があります。
そのために、4つのアプローチで開発プロセスの刷新に取り組みました。

2-1. ドキュメントのMarkdown化とGit一元管理

これまでの開発では、設計書や仕様書、ノウハウ資料などがExcelやConfluence等の様々な場所に散在していました。しかし、これらのバイナリ形式や分散した配置は、AI（Copilot）がコンテキストとして読み込むには不向きです。

そこで、すべてのドキュメントをMarkdown形式に変換し、ソースコードと同じGitHubリポジトリ内で管理することにしました。

設計書: 基本設計、詳細設計をMarkdownで記述。
ノウハウ: 開発環境の構築手順やトラブルシューティングもMarkdown化。
メリット:
- AIの可読性向上: テキストベースであるため、Copilotが容易に内容を理解し、回答の根拠として引用できるようになりました。
- バージョン管理: ドキュメントの変更履歴がGitで追えるため、変更箇所が明確になりチーム内のレビューにおいても便利になりました。
- コンテキストの統合: コードとドキュメントが同じ場所にあることで、AIは「仕様（ドキュメント）」と「実態（コード）」の両方を同時にインプットすることが可能になりました。

2-2. Instructionsファイルの整備

AIにはプロジェクトのルールを示し、ルールに沿ったコードを出力させる必要があります。これを実現するために .github/instructions 配下に配置する Instructionsファイル を作成しました。

役割: プロジェクト固有のコーディング規約、命名規則、ディレクトリ構成のルール、振る舞い（「熟練のエンジニアとして振る舞え」など）を定義します。
構成:
- general.instructions.md: 全体共通のルール（仕事の進め方、Gitの運用など）。
- python.instructions.md / csharp.instructions.md: 言語ごとの実装ルール。
効果: 毎回プロンプトで「変数はキャメルケースで」と指示しなくても、AIが自律的に規約を守ったコードを出力するようになります。

2-3. 「設計書→タスクリスト→プロンプト」の細分化プロセス

AIに「この設計書通りにシステムを作って」と丸投げしても、複雑な仕様を全て把握することはできず、アウトプットのクオリティが低くなっていました。
そこで、作業をAIが処理可能な粒度まで分解するようにプロセスを分解しました。

設計書（Design）: システムの全体像や仕様をMarkdownで定義。
タスクリスト（Task List）: 設計書を元に、実装作業を「1機能」「1メソッド」単位まで細かく分解し、リスト化します。
プロンプトファイル（Prompt File）: 分解された1つのタスクを実行するための、具体的な指示書を作成します。

このフローにより、AIは「今、何をすべきか」が明確になり、ハルシネーションや文脈の喪失を抑制することができました。
もちろん、これらを全て手作業で行うわけではありません。設計書を元にタスクリストを生成し、そこからプロンプトを作成する工程自体もAIに実行させることで、効率と品質を両立させました。

2-4. Geminiとのクロスレビュー体制

GitHub Copilotをメインに活用していましたが、セカンドオピニオンとして作成した各ドキュメントを、Geminiにも読み込ませてレビューを行いました。

設計レビュー: Copilotが生成した設計案やコードをGeminiに投げ、「論理的な矛盾はないか？」「セキュリティリスクはないか？」を客観的に評価させます。
効果: 「Copilot（実装者）」と「Gemini（レビュアー）」というAI同士のダブルチェック体制を作ることで、人間がレビューする前の段階で品質をさらに引き上げることができました。

また、1つのAIや1つのチャットでエラーが解消できずに行き詰まった場合においても、会話履歴をクリアした別のモデルを採用することで、問題の解決につながる場面がありました。
そのため、AIの成果物をAIを使ってレビューすることは、人の負担を削減するために、効果的だと感じました。

3.実際にやってみた結果

私の担当しているシステムでは、現在オンプレミスで稼働しているシステムをAWSへ移行するプロジェクトを計画しています。
その技術検証として、以下の実装と性能検証を本開発の前に行いました。

CSVファイルのコンテナ処理
RDS(PostgreSQL)からデータを取得するAPIと、API Gateway経由で取得した結果を表示するWindowsクライアントアプリ
SQSとLambda、RDBを組み合わせた同時実行・排他制御

これらの開発の中で、私が感じたことをご紹介します。

3-1. 開発が速くなった？

開発スピードが速くなったかといえば、ソースコードを書く時間という意味では圧倒的に速くなったことは間違いありません。
一方で、設計書の作成は、より細かく作成する必要が生じますし、既存資産の流用ができず新たにAI活用が可能なように修正や新規作成を迫られる場面がありました。
また、今回採用したプロセスでは、細分化してアウトプットを行うことで、設計書から直接プログラムを作成する場合よりも品質面において、大きな効果が得られた反面、人間側のレビューコストが高まりました。
工数という面においては、現時点でも想定以上の結果が得られましたが、レビューを含めた人間側の制約をどう克服するかも重要に感じました。

3-2. アーキテクチャ設計における人間の責任と重要性

今回の成果物の1つである実行制御について、設計時点で構想をGeminiと相談して決め、それをベースに設計資料を作成し、実装を行いました。
ところが、実際に動かしてみると期待する排他制御が機能せず、排他対象となる処理が実行中に、次の処理を順番待ちさせることができませんでした。
これを突き詰めて調査していくと、そもそもアーキテクチャが問題であり、期待した動作は実現できないような内容になっていました。
私自身の実装内容に対する解像度が低く、適切なレビューができていなかった面がありますが、どういうアーキテクチャで実装するかをAIに丸投げするのは危険だと感じました。

3-3. AIにエラー解決を任せると堂々巡りする

成果物を実行するとエラーになることがあります。簡単なエラーの場合でしたら、エラーメッセージを貼り付ける、エラーログのスクショを添付することで、解決策を提示したり、コードを修正してくれます。
これはこれで便利なのですが、時々行き詰ります。エラーメッセージに対し、何度も解決策を提示するものの同じエラーが出続けるケースが散見されました。
このようなケースでは、人間が介入してエラー原因の分析を行う必要があります。今回の場合ですと、API Gatewayに関するAWSインフラの設定で躓きました。