メインコンテンツへスキップ
見出し画像

AI駆動開発って何? 非エンジニアの方向けにやさしく説明してみます

    私がやっている「AI駆動開発」について、できるだけ非エンジニアの方にもわかるように説明してみます。
    (私は数十年プログラム開発に携わってきた組み込み系プログラマです。私の開発方法をAIエージェントにやってもらっているだけです)

    難しそうに聞こえるかもしれませんが、やっていることを一言でいうと、
    AIにいきなりコードを書かせるのではなく、先に「設計図」を作ってから開発を進める方法です。

    家を建てるときも、いきなり木を切って組み立てたりしませんよね。
    まずは設計図を作ります。AI駆動開発もそれと同じです。


    まず最初に作るのは「仕様書」です

    私が最初に作るのは「仕様書」です。
    これはChatGPTと相談しながら作ります。

    たとえば、

    • どんな機能が欲しいか

    • どんな流れで動いてほしいか

    • 何を自動化したいか

    • どこまでをAIに任せるか

    といったことを、会話しながら整理していきます。

    この段階では、まだプログラムを書きません。
    まずは「何を作るのか」をはっきりさせます。

    これが最初の土台になります。


    AIが読みやすいのは「テキストファイル」です

    ここで意外に大事なのが、AIが理解しやすい文書の形です。

    人間なら Word や Excel や PowerPoint でも読めますが、AIエージェントにとって特に扱いやすいのは、実はテキストファイルです。

    テキストファイルは余計な飾りがなく、内容の構造がそのまま見えるからです。
    AIにとっては、とても食べやすいごはんみたいなものです。やわらかい説明より、形がはっきりしているほうが得意なのです。


    そこで使うのが Markdown(マークダウン)記法です

    テキストファイルだけだと、ただの文字の並びに見えるかもしれません。
    そこで使うのが Markdown(マークダウン)記法 です。

    Markdownは、シンプルな記号を使って文章の構造を表現する方法です。

    たとえばこんな感じです。

    # 大見出し
    ## 中見出し
    ### 小見出し

    これだけで「ここが大きな見出し」「ここが次の話題」とわかります。

    人間にも読みやすく、AIにも読みやすい。
    だから仕様書や設計書を作るときにとても便利です。

    Markdownで書いたファイルは、拡張子に `.md` を使うことが多いです。
    そのため、仕様書なら `SPEC.md` のような名前になります。


    仕様書はこんな感じで作ります

    私はChatGPTと相談しながら、まず `SPEC.md` という仕様書を作ります。

    たとえば、こんなイメージです。

    # SPEC.md
    # バーチャル専門誌 日刊AIエージェント
    
    Version: 0.2-draft
    Status: Draft
    
    ## 1. 概要
    本システムは、Grok のタスク機能を用いて X 上の AI 関連バズ投稿を定期収集し、
    Gmail に届いた通知メールをもとに記事を作成し、
    GitHub Pages 上で専門誌として公開するものである。

    ここでは「どんな仕組みのシステムなのか」を文章で整理します。

    つまり、いきなりコードではなく、
    まずはAIに「何を作るか」をはっきり伝えるための説明書を作るわけです。


    次はAIに「レビュー」してもらいます

    仕様書を作ったら、それで終わりではありません。
    次は、その仕様書をAIエージェントに読んでもらってレビューしてもらいます。

    ここで使うのが、たとえば

    • Claude Code

    • Codex CLI

    のようなAIエージェントです。

    依頼のしかたは、たとえばこんな感じです。

    SPEC.mdを読んでレビューしてください。不明点はQAシート(QandA.md)に書いてください。

    するとAIは、

    • この条件は本当に決まっているか

    • ここは曖昧ではないか

    • この仕様だと実装方法が分かれそうではないか

    といった点を質問として返してきます。

    これがとても大事です。
    人間が「これで十分説明したつもり」と思っていても、AIは意外なところで引っかかります。
    逆にいうと、そこがあいまいな部分なのです。


    QAシートで「認識のズレ」を減らします

    AIが質問を書いてくる先が、`QandA.md` のようなQAシートです。

    たとえば、こんな内容になります。

    • このメールアドレスは実際に確認済みですか?

    • 実行時刻は本当に指定できますか?

    • この機能は外部APIを使うのですか、それとも画面操作ですか?

    こういった質問に対して、今度はChatGPTに回答案を書いてもらいます。
    そして、その回答をAIエージェントへ返します。

    すると、仕様書がさらに具体的になっていきます。

    この流れの良いところは、AIが勝手に想像して暴走しにくくなることです。
    ここを飛ばすと、後で「そんなつもりじゃなかった」が大量発生します。
    開発における小さなホラーです。


    次に「設計図」を作ります

    仕様書のレビューが終わったら、次は設計に進みます。

    ソフトウェアの設計では、UML(Unified Modeling Language)という考え方がよく使われます。
    これは、設計図を共通のルールで表現するための方法です。

    ただし、普通の図はAIエージェントにとって少し扱いにくいことがあります。
    画像としての図より、テキストのほうが理解しやすいからです。

    そこで便利なのが Mermaid(マーメイド)記法 です。

    Mermaidは、図をテキストで書ける記法です。
    見た目は図になりますが、中身はテキストなのでAIにも読みやすいのです。


    最初に作るのは「ユースケース図」です

    設計で最初によく作るのが「ユースケース図」です。

    画像

    これは、
    このシステムにはどんな機能があるのか
    を整理するための図です。

    たとえば、

    • 読者が記事を読む

    • 管理者が内容を更新する

    • AIが記事を生成する

    • システムが定期的に実行される

    といった「誰が何をするか」を整理します。

    AIエージェントには、たとえばこう依頼します。

    SPEC.mdを元に、ユースケース図(USECASE.md)をMermaid記法で書いてください。不明点はQAシート(QandA.md)に書いてください。

    すると、仕様書をもとに、システム全体の機能一覧が見えるようになります。


    次に作るのは「シーケンス図」です

    次に作るのが「シーケンス図」です。

    画像

    これは少しだけ難しそうに見えますが、考え方は単純です。
    登場人物どうしが、どんな順番でやり取りするかを表した図です。

    たとえば、

    1. スケジューラーが開始する

    2. 作品候補を選ぶ

    3. 元データを取得する

    4. 翻訳する

    5. チェックする

    6. 公開する

    というように、処理の流れを順番に見えるようにします。

    AIエージェントには、たとえばこんなふうに頼みます。

    USECASE.mdに従って、シーケンス図(SEQUENCE.md)をMermaid記法で書いてください。不明点はQAシート(QandA.md)に書いてください。

    ここまで来ると、
    「この機能を動かすには、誰と誰が、どんなやり取りをしないといけないのか」
    がかなりはっきりします。


    さらに「クラス図」を作ります

    シーケンス図までできると、必要な登場人物もだいぶ見えてきます。
    そこで次に作るのが「クラス図」です。

    画像

    クラス図というのは、
    システムの中にどんな部品が必要で、それぞれがどんな機能を持つか
    を整理する図です。

    初心者向けにかなりざっくり言うと、

    • 誰がいるか

    • その人は何ができるか

    を一覧にする感じです。

    AIエージェントには、こんなふうに依頼します。

    SEQUENCE.mdを元に、クラス図(CLASS.md)をMermaid記法で書いてください。不明点はQAシート(QandA.md)に書いてください。

    ここまでくると、必要な部品や機能がだいぶ整理されます。


    ここまでが「設計」です

    仕様書を作り、レビューし、設計図を作る。
    ここまでが「設計」の段階です。

    この工程をしっかりやっておくと、AIに実装を頼んだときに、かなりブレにくくなります。

    逆に、ここを省いて最初から

    • アプリを作って

    • 動くものを出して

    • なんかいい感じにして

    と頼むと、たしかに一瞬で何かは出てきます。
    でも、その「何か」が本当に欲しかったものかは別問題です。

    これが、いわゆる雰囲気で進める開発と、設計を先に固めるAI駆動開発の大きな違いだと思っています。


    テストを先に考えることもできます

    クラス図までできると、必要な機能が見えてきます。
    そうすると、その機能を試すための「テストケース」も先に考えられます。

    この考え方を TDD(テスト駆動開発) といいます。

    難しく聞こえますが、やっていることはわりと素朴です。

    「この機能にこういう入力をしたら、こういう結果が返るはず」

    という確認項目を、先に書いておくのです。

    つまり、あとから「たぶん動く」ではなく、
    先に「どうなれば正しいか」を決めておくわけです。

    AIエージェントには、たとえばこう依頼できます。

    CLASS.mdを元に、TDD用のテストケースを作ってください。不明点はQAシート(QandA.md)に書いてください。


    ここまで出来ていれば、AIに実装を任せやすくなります

    ここまで設計できていれば、AIエージェントに

    • 実装して

    • テストして

    • 動作確認して

    と頼んでも、変な方向に進みにくくなります。

    なぜなら、AIが読むべき材料がそろっているからです。

    • 仕様書がある

    • QAシートがある

    • ユースケース図がある

    • シーケンス図がある

    • クラス図がある

    • テストの考え方も整理されている

    ここまでそろっていれば、AIにとっても「何を作ればいいか」がかなり明確になります。


    私が考える「バイブコーディング」との違い

    最近は、AIにざっくりお願いしてどんどんコードを書かせるやり方も広まっています。
    それ自体は悪いことではありませんし、試作にはとても便利です。

    ただ、私がやっている方法は少し違います。

    私は、AIにいきなり作らせる前に、AIが理解しやすい形で設計書をそろえることを大事にしています。

    つまり、

    • 思いつきでそのまま実装するのではなく

    • 先に仕様を固めて

    • 設計の矛盾を減らして

    • テスト観点も用意してから

    • 実装に入る

    という流れです。

    このほうが、後での手戻りが少なくなります。
    最初は少し遠回りに見えて、実はかなり近道です。開発あるあるですね。


    AI駆動開発とは何か

    AI駆動開発(AI-Driven Development)とは、
    生成AIやLLMを開発プロセスの中心に置き、設計、コード生成、テスト、公開までをAIに大きく支援してもらう開発手法です。

    ここで大事なのは、AIを単なるお手伝いではなく、
    設計書を読んで動ける実装担当に近い存在として扱うことです。

    そのかわり、人間の役割はなくなりません。
    むしろ、次の役割がより重要になります。

    • 何を作るか決める

    • あいまいさを減らす

    • レビューする

    • 品質を確認する

    • 最後に責任を持つ

    つまり、人間は「全部自分で書く人」から、
    方向を決めて品質を守る人へと役割が変わっていくのだと思います。


    まとめ

    私がやっているAI駆動開発を、初心者向けにかなりやさしくまとめると、次の流れになります。

    1.ChatGPTと相談して仕様書を作る

    マークダウン記法で仕様を「SPEC.md」で書いてください

    2.AIエージェントにレビューしてもらう

    SPEC.mdをレビューしてください。不明点はQAシート(QandA.md)に書いて下さい。

    3.QAシートであいまいさを減らす

    ChatGPTにSPEC.mdとQandA.mdを張り付けて以下を聞きます。出てきた回答をレビューしたAIに渡します。

    QAシートに回答してください。

    4.Mermaid記法で設計図を作る

    SPEC.mdを元に、ユースケース図(USECASE.md)をMermaid記法で書いてください。不明点はQAシート(QandA.md)に書いてください。

    USECASE.mdに従って、シーケンス図(SEQUENCE.md)をMermaid記法で書いてください。不明点はQAシート(QandA.md)に書いてください。

    SEQUENCE.mdを元に、クラス図(CLASS.md)をMermaid記法で書いてください。不明点はQAシート(QandA.md)に書いてください。

    5.テスト観点を先に整理する

    CLASS.mdを元に、TDD用のテストケースを作ってください。不明点はQAシート(QandA.md)に書いてください。

    6.そのうえでAIに実装してもらう

    実装してください

    つまり、
    AIにコードを書かせる前に、AIが迷わないように道案内を作っておく
    ということです。

    これが私のやっているAI駆動開発です。

    実際にどうやったのかは、以下のnoteで詳しく説明しています。

    実際に私が作ったSPEC.md,USECASE.md,SEQUENCE.md,CLASS.md,QandA.mdも公開しています。


     
     
    猫好きプログラマ。半導体会社の技術者 Q&AサイトのQuoraでフォロワー数6000人の「ChatGPT情報交換所」を主宰する程生成AI好き ポートフォリオ https://hantani-portfolio.pages.dev/

    あなたへのおすすめ