🧭

非ソフトウェア技術者の「AI開発の限界と落としどころ」〜仕様駆動開発でローカルAgentic RAGをスクリプト化〜

に公開
アーキテクチャ
Agent
生成 AI
RAG
仕様駆動開発
tech

概要

Colab完結：ローカルAgentic RAG + Gradio UI の続きです。
前回は、Gradio UI 付き ローカルLLM の Agentic RAG を、Colab Notebook で実装しました。ただ、Notebook は、ソフトウェアとして保守・拡張できないので、現場（本番環境）で使えるツールにはなりません。そこで、この Agentic RAG を保守・拡張しやすい設計でスクリプト化することを行いました。
ただ私は、ソフトウェア技術者ではないので、機械設計技術者が、保守・拡張しやすいソフトウェア設計を仕様駆動開発を使って実現できるのか？、というのが、この記事の主旨になります。

結論（一言で）

非ソフトウェア技術者側の役割は、AI を使ってドメイン知識を反映した精度の高い PoC を高速に自作・実証し、プロのソフトウェア技術者へバトンを渡す、位置付けになると考えます。

逆に言うと、現場（本番環境）で使うソフトウェア開発は、プロのソフトウェア技術者にやってもらった方がよい。

仕様駆動開発で実現できたこと / 技術的なハードル

最近、AI を使うとソフトウェアを内製化できる、SaaS 不要、みたいな記事を目にしますが、自分でやってみると、世の中そんなに甘くない、というのが所感です。
AI で、とりあえずのソフトウェアを作ることはできるかもしれませんが、プロでないと、ソフトウェアの性能、品質、保守、拡張性のいずれも、担保できないという印象です。

実現できたこと

  • 保守・拡張しやすい Agentic RAG のスクリプト化。
  • Agentic RAG ソフトウェアの設計ドキュメントの作成。
  • ソフトウェアの修正過程のドキュメント化。
  • ソフトウェアの単体テストの作成と実行。
  • 上記を AI に自動でやらせる。（自分では 1文字もコードを書かない。）

    夕方に仕様を AI に投げて、次の日の朝にソフトウェアができあがっている、というのは、技術的には、実現可能です。

非ソフトウェア技術者に対するハードル

  • 設計ドキュメントのレビューがきつい。
    保守・拡張しやすいソフトウェアを作るためには、ディレクトリ構成(GitHubリンク) や、クラス図(GitHubリンク) が大事なところですが、結局、ソフトウェア全体の設計が頭に入っていないとレビューできない。 非ソフトウェア技術者にできる仕事ではない。

    これを自力で（AI を使わずに）設計・実装できるソフトウェア技術者は、普通にすごいと思います。

  • 設計ドキュメントを作成するための、AI への作成指示プロンプトがきつい。
    「何かうまいことやって」、と AI に指示しても、保守・拡張しやすいソフトウェア設計にはなりません。結局、ソフトウェアアーキテクチャが分からないと、AI にうまく指示を出すことができず、望むソフトウェア設計はできません。

    プロダクト要求定義書（PRD）の作成指示(GitHubリンク)

    RAG 特有の点では、日本語の RAG なので、Embedding / Reranker とも、日本語性能がトップクラスの cl-nagoya/ruri-v3 シリーズを選定していますが、どのアーキテクチャを使用するか、こちらで選定して AI に指示しないと、望む実装にはなりません。

    技術仕様書（architecture.md）の作成指示(GitHubリンク)

  • ソフトウェア初回実装後の、ソフトウェアレビューがきつい。
    実装の前に、ソフトウェアの設計ドキュメントを AI にしっかりと作らせたので、最初からほぼ動作するコードが生成されましたが、動作させてみたり、コードレビューをすると、漏れがあり、修正をかけています。
    一番重大だった修正事項は、Ruri-v3 Embedding プレフィックスの追加(GitHubリンク) で、実装が、Ruri のモデルカードで要求されるとおりの使い方になっておらず、Ruri の性能を使い切れていない事項でした。これも、漫然と AI にレビューさせても引っかからないので、ソフトウェアのどの部分を重点的にレビューするか、どのあたりに落とし穴があるかなどの経験値を持っていないといけない、ということだと思います。

    コード実装後の修正内容(GitHubリンク)

非ソフトウェア技術者にとっての落としどころ

  • 個人的な主観ですが、何となく、500 行程度のコードをモジュール化して実装する（+ 単体テスト）、ぐらいが、非ソフトウェア技術者の分相応なのかなと思います。
  • 今回作成したソフトウェアの設計ドキュメントの内、プロダクト要求定義書（PRD）と、開発ガイドライン（Development Guidelines）を簡素にしたもの、また、CLAUDE.md (プロジェクトメモリ)を簡素にしたものを準備するぐらいでしょうか。
  • 作成できるアプリケーションとしては、前処理スクリプト、ダッシュボード、データサイエンス/機械学習などの、コア要素、かつ、比較的簡単なものあたりがターゲットになります。

これが、非ソフトウェア技術者側の役割は、AI を使ってドメイン知識を反映した精度の高い PoC を高速に自作・実証し、プロのソフトウェア技術者へバトンを渡す、位置付けになると考えます。

今回行った仕様駆動開発の手順

今回の仕様駆動開発は、次の手順で実施しました。事前に、Agentic RAG の Notebook を作成しており、機能に関する実装要件は理解できている状態で始めています。
また私は、機械設計技術者であって、保守・拡張しやすいソフトウェア設計技術を持ち合わせていないので、Robert C. Martin（Uncle Bob）の原著『Clean Architecture』に基づく設計思想をアーキテクチャ方針として明示してください。と、有名なフレームワークを使って指示するようにしています。（リファクタリングなどをさせるときも、同様な方法をとっています。）

仕様駆動開発の手順
前提：CLAUDE.md (プロジェクトメモリ) は、実践Claude Code入門 という書籍の chapter 4 の CLAUDE.md をそのまま流用しています。

西見公宏，吉田真吾，大嶋勇樹, 実践Claude Code入門 ―現場で活用するためのAIコーディングの思考法, 技術評論社, 2025

  1. プロダクト要求定義書（PRD）を作成させるための指示プロンプト案を、自分で作成する。
  2. プロンプト案、自分で作成した README.md（この Agentic RAG に必要なアーキテクチャなどがまとめられている）、Agentic RAG の Notebook 実装を、Gemini に渡し、プロダクト要求定義書（PRD）を作成させるための指示プロンプトを清書させる。
  3. Claude Code に、指示プロンプトを渡し、プロダクト要求定義書（PRD）を作成させる。
  4. Gemini に、Claude Code が作成したプロダクト要求定義書（PRD）をレビューさせる。
  5. Gemini のレビュー結果を Claude Code に input し、修正させる。
    → 同様な手順を、残りのソフトウェアの設計ドキュメント類に適用し、全ての設計ドキュメントを作成する。
  6. 全ての設計ドキュメントが完成した後、Claude Code に、実装を開始するよう指示する。
  7. Claude Code がソフトウェアを実装する。
  8. 実装完了後、ソフトウェアの動作確認を行う。
  9. 動作確認結果のフィードバックを Claude Code に返し、ソフトウェアを修正する。

今後の予定

  • Agentic RAG の構築 / 仕様駆動開発を試してみる、というのがモチベーションだったのですが、一通り目的が達成できたことと、実際にやってみると、非ソフトウェア技術者向けにスケールできなさそうなので、本プロジェクトはここで完了とします。
  • 次（時期未定）は、小規模な MLOps パイプラインに手を出してみるつもりです。

おわりに

ここまで本記事をお読み頂き、大変ありがとうございました。本記事がお役に立つと幸いです。

参考（GitHub リンク / 前回記事）

Discussion