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

AI駆動開発を拗らせた結果、プロンプトは1行になった。それでもAIの精度が上がった。

    こちらは2026年8月現在のお話です。

    前回の記事では、私がAIを活用するうえで、「AIを使って作業する」という考え方から、「AIが作業しやすい環境を先に作る」という考え方へ変わったことを書きました。

    前回の記事はこちらです。

    前回の記事の最後には、

    私が個人開発をする上で、どのようなAIフレンドリーな環境を用意しているかは、次回以降で紹介させていただきます。

    と書きましたので。
    その続きになります。
    今回はなぜプロンプトが一行になったのかと合わせて、現に私が採用してる開発フローについて紹介したいと思います。

    毎回noteの文頭にも書いていますが、現在、私は個人でサッカーのスタッツサイト「Tricolore Stats」を開発しています。
    私は本職のエンジニアではありません。
    プログラムを一からすべて自分で書いているわけでもなく、ChatGPTやCursorなどのAIにかなり助けてもらいながら開発しています。
    というより、AIにほとんど作ってもらっています。
    AIがないとここまでの規模のサイトはできませんでし維持もできなくなってきてます。
    その一方で、AIに開発を任せる範囲が広がるにつれて、別の問題も出てきました。

    ・AIに細かく指示しなければ、思ったとおりに動いてくれない。
    ・指示を細かくすると、今度はプロンプトが長くなりすぎる。

    長いプロンプトを書いたとしても、毎回同じ品質の回答になるとは限らない。そんな状態が続いていました。

    しかし、開発環境やドキュメント、GitHubの運用を少しずつ整えた結果、現在は極端に言えば、次の1行で作業を始められるようになりました。

    Issue #○○に沿って、調査から開始してください。

    以前より指示は短くなっています。
    それでも、AIの調査や設計、実装の精度は上がりました。

    今回は、なぜそのような状態になったのか、実際にどのような準備をして、どのような工程で開発を進めているのかを紹介します。

    以前は毎回、長いプロンプトを書いていた

    以前の私は、AIへ開発を依頼するとき、かなり長いプロンプトを書いていました。

    例えば、画面の修正を依頼するときには、

    • このファイルを修正してください

    • 既存の処理へ影響を与えないでください

    • 指示していないファイルは変更しないでください

    • スマートフォン表示も確認してください

    • 必要なテストを実行してください

    • 変更したファイルを最後に一覧で報告してください

    • 不明点がある場合は勝手に判断しないでください

    • 現在の仕様を確認してから作業してください

    など、思いつく限りの注意事項を書いていました。

    過去にAIが間違えたことがあれば、その内容もプロンプトへ追加します。

    その結果、実装してほしい内容よりも、注意事項の方が長くなることもありました。

    AIへ詳しく説明すればするほど、精度が高くなると思っていたからです。

    もちろん、ある程度は正しいと思います。

    何も説明せずに「いい感じに直してください」と依頼するより、目的や条件を伝えた方が良い結果になります。

    しかし、同じルールを毎回プロンプトへ書く方法には限界がありました。

    なにしろ、書き忘れることもあります。

    以前のチャットでは伝えていても、新しいチャットでは引き継がれないことがあります。

    AIごとに伝え方を変える必要もあります。

    そし1番は、毎回長いプロンプトを準備すること自体が大変です。

    AIに作業してもらうために、人間が毎回長時間かけて指示書を書く。

    それでは、少し本末転倒です。

    人間が書くプロンプトは、毎回同じ品質にはならない

    もう一つ問題だったのは、人間側の状態によってプロンプトの内容が変わることです。

    人間は機械ではありません。

    時間に余裕があるときは、背景や条件を丁寧に整理できます。

    一方で、不具合が発生して焦っているときや、何度も同じ失敗が続いたときは、少し感情的な書き方になることがあります。

    例えば、

    前にも同じことがあったので、今回は絶対に関係ない場所を変更しないでください。

    なぜこの処理を勝手に変更したのでしょうか。必ず既存仕様を確認してください。

    といった形ですね。気持ちは分かります。
    というより、実際に私もそのような指示を書いていました。

    しかし、感情的な表現を増やしても、AIが守るべきルールが明確になるとは限りません。

    むしろ、重要な指示と感情的な文章が混ざり、何を優先すべきか分かりにくくなることもあります。

    また、長いプロンプトを書くことが面倒になり、「前回と同じ感じでお願いします」と言った行きつけの美容院での注文のようになったり「いつものルールで対応してください」と省略したくなることもあります。

    しかし、新しいチャットや別のAIには、その「いつものルール」が分かりません。

    人間側の余裕、体調、感情、作業時間によって、プロンプトの品質が変わる。

    それでは、AIの成果物も安定しません。

    そこで、毎回人間が同じ説明を正確に書くことを期待するのではなく、人間が詳しく書かなくても同じルールが適用される環境を作ろうと考えました。

    プロンプトを書く能力に開発品質を依存させない。

    これも、AIフレンドリーな環境を整え始めた大きな理由です。

    AIが間違える原因は、AIだけではなかった

    AIが間違った修正をした場合、

    「AIの精度が低い」

    「まだAIには任せられない」

    と考えるのは簡単です。

    私も以前は、そう思うことがありました。

    しかし、何度も同じような失敗を経験する中で、AI側だけに原因があるわけではないと感じるようになりました。

    例えば、プロジェクト内に似た内容のドキュメントが複数あったとします。

    一方には古い仕様が書かれていて、もう一方には新しい仕様が書かれている。

    人間であれば、更新日や過去の経緯から、どちらを参考にすべきか判断できるかもしれません。

    しかし、AIから見れば、どちらもプロジェクト内に置かれた正式そうな資料です。

    AIが古い資料を読んで間違えたとしても、そもそも古い資料を整理せずに残していた側にも問題があります。

    また、README、設計書、Issue、チャットの中で、それぞれ少しずつ違う指示を出していた場合も同じです。

    AIは暗黙の了解を理解できません。

    「普通はこの資料を優先するだろう」

    「このファイルは昔のものだから読まないだろう」

    「このルールは当然知っているだろう」

    と期待しても、AIには伝わっていません。

    つまり、AIが迷っていた原因の一部は、プロジェクト内の情報が整理されていなかったことでした。

    これは、人間が新しくプロジェクトへ参加する場合も同じだと思います。

    資料の場所が分からない。

    正式な仕様がどれか分からない。

    変更してよい範囲が分からない。

    テスト方法が分からない。

    その状態で「既存の仕様に合わせて正しく実装してください」と言われても、難しいはずです。

    そこで、AIを単なるコード生成ツールではなく、新しくプロジェクトへ参加した開発メンバーのように考えることにしました。

    AIが最初に読む場所を用意する

    最初に整えたのが、AIインデックスです。

    AIインデックスとは、簡単に言えば、

    「このプロジェクトで作業する場合は、まずここを読んでください」

    という案内板です。

    プロジェクトが大きくなると、ドキュメントも増えていきます。

    例えば、一般的なWebサービスであれば、次のような資料が考えられます。

    • プロジェクト全体の概要

    • フロントエンドの開発ルール

    • バックエンドの構成

    • データベースの設計

    • クラウド環境の運用手順

    • GitHubの運用ルール

    • テストの実行方法

    • 障害が起きた場合の対応手順

    • 機能ごとの設計書

    • 過去の調査結果

    これらをすべて同じ階層へ置いてしまうと、AIはどこから読めばよいか分かりません。

    そこで、最初にREADMEやAI用のインデックスを読み、そこから作業内容に応じた資料へ進める構成にしました。

    例えば、AIインデックスには、次のような内容を書きます。

    # AI作業インデックス
    
    ## 作業開始時に必ず読むもの
    
    1. `README.md`
       - プロジェクトの目的
       - 使用技術
       - 基本的なディレクトリ構成
    
    2. `docs/AI_INDEX.md`
       - 作業内容ごとの参照先
       - 正本ドキュメントの一覧
       - 変更禁止範囲
    
    3. `.cursor/rules/core-rules.mdc`
       - AIが常に守る共通ルール
    
    ## 作業別の参照先
    
    ### フロントエンドを変更する場合
    
    - `docs/frontend/architecture.md`
    - `docs/frontend/coding-standards.md`
    - `docs/testing/frontend-test-guide.md`
    
    ### バックエンドを変更する場合
    
    - `docs/backend/architecture.md`
    - `docs/backend/api-design.md`
    - `docs/testing/backend-test-guide.md`
    
    ### データベースを変更する場合
    
    - `docs/database/schema.md`
    - `docs/database/migration-guide.md`
    
    ### GitHub Issueを扱う場合
    
    - `docs/process/issue-workflow.md`
    - `docs/templates/issue-template.md`
    
    ## 優先順位
    
    情報が競合する場合は、次の順番で判断する。
    
    1. 対象Issueの受け入れ条件
    2. 正本の設計書
    3. プロジェクト共通ルール
    4. README
    5. 過去のIssue・Pull Request
    6. 一時的なメモ
    

    実際には、プロジェクトの規模や構成に合わせて内容を変えます。

    重要なのは、すべての内容をAIインデックスへ書くことではありません。

    「何が、どこに書かれているか」

    「どの情報を優先するか」

    「今回の作業では、どの資料を読むべきか」

    を案内することです。

    人間が図書館の案内図を見てから目的の棚へ向かうように、AIにも読む順番を用意しました。

    これだけでも、AIが関係のない資料を大量に読んだり、古い資料を優先したりする可能性が減りました。

    同じ情報を複数に書かない「正本化」

    次に進めたのが、ドキュメントの正本化です。

    正本とは、その情報について最も正式で、優先される資料のことです。

    英語では「Single Source of Truth」と呼ばれる考え方に近いものです。

    例えば、テストの実行方法が、

    • ルートのREADME

    • テスト用のREADME

    • 開発手順書

    • 過去のIssue

    • 個人用のメモ

    にそれぞれ書かれていたとします。

    すべて同じ内容ならまだよいのですが、更新のタイミングがずれると、少しずつ違う説明が残ります。

    この状態では、AIがどれを信じればよいか分かりません。

    そこで、同じ情報は原則として1か所だけに詳しく書くようにしました。

    ほかのドキュメントには同じ説明を繰り返さず、

    「詳細はこのドキュメントを参照してください」

    というリンクだけを置きます。

    例えば、フロントエンドのコーディングルールは、専用のドキュメントを正本にします。

    READMEには細かなルールをすべて書かず、そのドキュメントへの案内だけを記載します。

    ルールを変更する場合も、正本だけを更新します。

    正本の一覧も、次のように整理できます。

    # 正本ドキュメント一覧
    
    | 分野 | 正本 | 役割 |
    | --- | --- | --- |
    | プロジェクト概要 | `README.md` | サービスの目的と全体構成 |
    | フロントエンド | `docs/frontend/architecture.md` | UI構成と設計方針 |
    | コーディング規約 | `docs/frontend/coding-standards.md` | HTML・CSS・JavaScriptのルール |
    | API仕様 | `docs/backend/api-design.md` | APIの入出力とエラー仕様 |
    | データベース | `docs/database/schema.md` | テーブルとデータ構造 |
    | テスト | `docs/testing/test-policy.md` | 必須テストと実行条件 |
    | Git運用 | `docs/process/git-workflow.md` | ブランチ、コミット、PRの規則 |
    | 本番運用 | `docs/operations/production-guide.md` | デプロイと障害対応 |
    

    こうすることで、AIへ毎回、

    「今回はこの資料を優先してください」

    と伝える必要が減りました。

    また、正本化はAIのためだけではありません。

    個人開発では、数か月前の自分がなぜその判断をしたのか、分からなくなることがあります。

    当時は当然だと思っていたことでも、時間が経つと忘れます。

    そのため、プロジェクトの記憶を自分の頭やチャット履歴だけに残すのではなく、正式なドキュメントとしてリポジトリへ残すようにしています。

    未来の自分も、新しく参加した人とほとんど同じです。

    ルールは、お願いではなく判断基準として書く

    AI向けのルールも整備しています。

    以前は、プロンプトの中へ、

    「関係ないファイルを変更しないでください」

    「既存の処理を壊さないでください」

    と書いていました。

    しかし、このような表現だけでは、AIが実際に何をすればよいか分からないことがあります。

    そこで、ルールはできるだけ行動へ変換できる形で書きます。

    例えば、次のような内容です。

    # AI共通作業ルール
    
    ## 作業開始前
    
    - 最初に `README.md` と `docs/AI_INDEX.md` を読む
    - 対象Issueの本文と受け入れ条件を確認する
    - 未コミットの変更がある場合は、内容を確認するまで編集しない
    - 既存コードを変更する前に、関連する正本ドキュメントを確認する
    
    ## 変更範囲
    
    - Issueに記載された対象ファイルのみ変更する
    - 対象外の問題を発見しても、同じ変更へ混ぜない
    - 対象外の問題は「別Issue候補」として報告する
    - 大規模なリファクタリングを同時に行わない
    
    ## 調査
    
    - 調査依頼ではコードを変更しない
    - 確認済みの事実と推測を分けて報告する
    - 原因が確定していない場合は「原因候補」と記載する
    - 読んでいないファイルの内容を推測しない
    
    ## 実装
    
    - 既存の公開仕様を変更しない
    - 既存の関数や共通処理を再利用できるか確認する
    - エラー時の動作を実装する
    - ユーザー入力は使用前に検証する
    
    ## 検証
    
    - 変更前の不具合が再現することを確認する
    - 変更後に不具合が解消したことを確認する
    - 既存の正常な動作が維持されていることを確認する
    - 実行したテストと結果を報告する
    
    ## 禁止事項
    
    - 明示的な依頼なしにcommit、push、mergeを行わない
    - 本番環境の設定を変更しない
    - APIキーや認証情報をコードへ書かない
    - テストを通すためだけに期待値を変更しない
    

    ポイントは、「丁寧に作業してください」のような抽象的なお願いだけにしないことです。

    何を読むか。

    何を変更してよいか。

    何を報告するか。

    どの条件で止まるか。

    どの操作は禁止されているか。

    AIが次の行動を判断できる形にします。

    また、ルールを増やしすぎると、今度はAIが重要なルールを見落とします。

    そのため、すべての作業で必要な共通ルールと、フロントエンドやバックエンドなど分野別のルールを分けています。

    プロンプトを短くするために、巨大なルールファイルを一つ作るだけでは、別の問題が発生します。

    AIが必要なルールだけを段階的に読める構造が必要です。

    ドキュメントを説明書ではなく、判断基準にする

    以前のドキュメントは、完成した機能の説明が中心でした。

    「この機能は、このように動きます」

    という説明です。

    もちろん、それも必要です。

    しかし、AIへ開発を任せる場合は、それだけでは足りません。

    必要なのは、

    「新しく変更するときに、どう判断するか」

    という基準です。

    そのため、現在は次のような内容もドキュメントへ記載するようにしています。

    • どのファイルが何を担当しているか

    • 新しい処理をどこへ追加するか

    • 変更してはいけない範囲はどこか

    • 正常時だけでなく、エラー時にどう動くか

    • パソコンとスマートフォンでどう表示するか

    • 入力値をどこで確認するか

    • 変更後にどのテストを実行するか

    • 何を確認できれば作業完了とするか

    例えば、画面のデザインをAIへ依頼する場合も、

    「今風で見やすい画面にしてください」

    だけでは、毎回違うデザインになります。

    そこで、

    • ページ全体の構造にはCSS Gridを使う

    • 小さな横並びにはFlexboxを使う

    • 本当の表形式データ以外にはtableを使わない

    • モバイル表示を基準に設計する

    • 共通の色や余白はデザイントークンを使う

    • 既存のJavaScriptが参照しているIDやクラスは勝手に変更しない

    など、判断の基準をドキュメント化しています。

    これにより、AIへ毎回細かく説明しなくても、同じ方針で実装しやすくなりました。

    AIに正しい答えを毎回考えさせるというより、AIが迷わず判断できる選択肢を先に用意するイメージです。

    ファイル同士の関係を示す

    開発を進める中で、ファイル同士の関係を表す資料も作るようになりました。

    ここで言う資料とは、どのファイルや機能が、何と関係しているかを示す対応表のようなものです。

    プロジェクトでは、1つのファイルだけを変更すれば終わるとは限りません。

    例えば、TypeScriptの元ファイルを変更した場合、実際にブラウザで読み込まれるJavaScriptも更新する必要があります。

    設定ファイルを変更した場合は、その設定がクラウド上の処理へ正しく含まれているか確認する必要があります。

    URLの構造を変更した場合は、画面だけでなく、サイトマップ、canonical、リダイレクト、SEO用のデータなどにも影響する可能性があります。

    人間であれば、経験から関連箇所を思い出せるかもしれません。

    しかし、AIが毎回すべての関係を推測すると、更新漏れが起きます。

    そこで、

    「このファイルを変更した場合は、これらも確認する」

    という関係を明文化しました。

    例えば、次のような形です。

    # 変更影響資料
    
    ## `src/components/header.ts` を変更した場合
    
    確認対象:
    
    - `public/js/components/header.js`
    - `tests/unit/header.test.ts`
    - `tests/e2e/navigation.spec.ts`
    - 日本語版・英語版のヘッダー
    - モバイルメニュー
    - キーボード操作
    
    必須コマンド:
    
    - `npm run build`
    - `npm run test:unit -- header`
    - `npm run test:e2e -- navigation`
    
    ## URL生成処理を変更した場合
    
    確認対象:
    
    - 内部リンク
    - canonical
    - sitemap
    - リダイレクト
    - OGP URL
    - 構造化データ
    - 旧URLとの互換性
    

    さらに、可能なものは自動テストで確認します。

    AIへ、

    「忘れずに更新してください」

    とお願いするだけではなく、更新を忘れた場合にCIが失敗する仕組みを作ります。

    CIとは、コードをGitHubへ登録した際に、テストやチェックを自動実行する仕組みです。

    人間やAIの注意力に依存するより、仕組みで止めた方が確実です。

    AI駆動開発では、AIが間違えないことを期待するだけでなく、間違えた場合に検知できる環境を作ることが重要だと感じています。

    AIごとに役割を分ける

    現在は、1つのAIだけにすべてを任せていません。

    複数のAIへ役割を分けています。

    私の現在の開発では、大まかに次のような分担です。

    ChatGPT:相談、要件整理、Issue作成

    最初に相談することが多いのはChatGPTです。

    「この機能を追加したい」

    「この動きは不具合ではないか」

    「次に何を優先すべきか」

    といった、まだ整理されていない内容を相談します。

    ChatGPTと会話しながら、

    • 何を実現したいのか

    • 現在確認できている事実は何か

    • 何が推測なのか

    • どこまでを今回の対象にするか

    • 何を確認できれば完了なのか

    を整理し、GitHub Issueとして登録できる形へ変えます。

    私の場合、最初から完璧な要件を用意できるわけではありません。

    会話をしながら、自分が本当に困っていることや、実現したいことを整理していきます。

    この部分は、普段の相談相手として使っているChatGPTが向いていると感じています。

    Cursor:実際のファイルを読んだ調査、設計、実装

    Cursorには、実際のプロジェクトファイルを読んでもらいます。

    Issueを確認し、README、AIインデックス、関連ドキュメント、既存コードの順に調査します。

    ここで重要なのは、最初からコードを修正させないことです。

    特に影響範囲が大きそうな作業では、

    「まずは読み取りだけで調査してください」

    と依頼します。

    実装前に、

    • 現在どのような処理になっているか

    • 不具合の原因候補は何か

    • どのファイルへ影響するか

    • 既存の仕組みを利用できるか

    • 設計が必要な規模か

    を確認します。

    調査内容に問題がなければ設計へ進み、設計が固まった後に実装します。

    以前は、AIへすぐ修正を依頼し、途中で認識違いに気づくことがありました。

    現在は、調査、設計、実装を分けることで、大きな手戻りを減らしています。

    CodeRabbit:Pull Requestのコードレビュー

    実装が終わったらPull Requestを作成し、CodeRabbitにレビューしてもらいます。

    Pull Requestとは、変更したコードを正式なブランチへ取り込む前に、変更内容を確認するための仕組みです。

    CodeRabbitには、

    • バグの可能性

    • セキュリティ上の問題

    • テスト不足

    • 保守しにくい書き方

    • 既存コードとの不整合

    などを確認してもらいます。

    実装したAIに、そのまま自分のコードをレビューさせることもできます。

    しかし、同じAIは同じ前提や思い込みを引き継ぐ可能性があります。

    そのため、実装とレビューを別のAIへ分けています。

    人間の開発でも、コードを書いた人とは別の人がレビューするのと同じ考え方です。

    Geminiなど:設計の別視点レビュー

    規模が大きい機能では、設計書を別のAIにも確認してもらいます。

    特に、

    • データの整合性が壊れないか

    • 同時に処理が実行された場合に問題がないか

    • 途中で失敗した場合に復旧できるか

    • 運用負荷が高くならないか

    • 将来の拡張を妨げないか

    など、実装だけではない観点を確認します。

    複数のAIが同じ意見になることもあれば、意見が分かれることもあります。

    意見が分かれた場合は、どちらが正しいかをAIの多数決で決めるわけではありません。

    それぞれの理由を確認し、最終的には人間が判断します。

    AIを正解を出す機械として扱うのではなく、それぞれ異なる視点を持つ担当者として使っています。

    AI自身に、開発環境のアンケートも行っている

    最近は、AIに作業を依頼するだけでなく、AI自身へ開発環境についてアンケートを行うことも試しています。

    例えば、同じリポジトリを読ませた複数のAIへ、次のような質問をします。

    # AI作業環境アンケート
    
    以下のプロジェクト資料を確認し、回答してください。
    
    ## 質問
    
    1. 作業開始時に最初に読むべき文書は明確でしたか
    2. 対象作業に必要な資料を迷わず見つけられましたか
    3. 正本となる文書は明確でしたか
    4. 複数の文書で内容が競合していませんでしたか
    5. 変更してよい範囲と禁止範囲は明確でしたか
    6. 作業の完了条件は判断できましたか
    7. 不足しているドキュメントはありましたか
    8. 読まなくてもよい情報が多すぎませんでしたか
    9. ルールの中で、解釈が分かれそうな表現はありましたか
    10. この環境で誤った変更が起きるとしたら、どこが原因になりそうですか
    
    ## 回答形式
    
    - 評価: 1〜5
    - 根拠
    - 問題となる文書や箇所
    - 改善案
    

    これは、AIの回答をそのまま正しいものとして採用するためではありません。

    人間には分かりやすいつもりの資料でも、AIから見ると参照順が曖昧なことがあります。

    逆に、人間から見ると長すぎると思った説明が、AIには必要な場合もあります。

    複数のAIへ同じ質問をすると、共通して指摘される箇所が見えてきます。

    例えば、

    • どの文書が正本なのか分からない

    • READMEと設計書の説明が重複している

    • 対象外の定義が曖昧

    • テストの選択基準が不足している

    • ルールが多すぎて優先順位が分からない

    • 古いドキュメントを除外する基準がない

    といった指摘です。

    AIが働きやすい環境を作るのであれば、実際にAIへ感想を聞いてみる。

    少し変な話にも見えますが、利用者へアンケートを取るという意味では、それほど不自然ではないと思っています。

    AIを擬人化したいわけではありません。

    人間が作ったAI向けの案内が、AIから見て解釈可能かを確認するテストに近いです。

    検証のために既に大小何件かタスクでアンケートは実施示しましてが、割と参考になるような回答をしてくれています。

    今後は、アンケート結果を定期的に比較し、

    • 資料へたどり着くまでの手順が短くなったか

    • 正本の判定が一致するようになったか

    • 不要な読み込みが減ったか

    • 複数AIの回答差が小さくなったか

    なども確認してみたいと考えています。

    AI同士が受け渡しやすいように、出力をテンプレート化する

    AIの回答は、毎回同じ形式になるとは限りません。

    あるAIは非常に詳しく説明します。

    別のAIは結論だけを簡潔に返します。

    内容が正しくても、形式がばらばらだと、次のAIや人間が読みづらくなります。

    そこで、成果物ごとにテンプレートを用意しています。

    例えばGitHub Issueでは、

    • 概要

    • 背景

    • 確認済みの事実

    • ユーザーの希望

    • AIによる推測

    • 対象範囲

    • 対象外

    • 調査項目

    • 受け入れ条件

    • 未確定事項

    などを分けます。

    ここで意識しているのは、事実と推測を混ぜないことです。

    AIは、情報が足りない部分を自然に補完して、もっともらしい文章を作ることがあります。

    それ自体は便利ですが、開発では、確認済みの事実と推測を区別しなければ危険です。

    調査結果にもテンプレートがあります。

    • 結論

    • 確認したファイル

    • 判明した事実

    • 未確認事項

    • 実装が必要か

    • 次に必要な人間の判断

    設計書では、

    • 目的

    • 前提条件

    • 処理の流れ

    • データ構造

    • エラー時の動作

    • セキュリティ

    • テスト

    • 運用方法

    • 対象外

    などを整理します。

    Pull Requestでも、変更内容、変更理由、影響範囲、テスト結果、確認方法を同じ形式で記載します。

    このテンプレートは、人間が読みやすくするためだけではありません。

    ChatGPTが作ったIssueをCursorが読みます。

    Cursorが作った設計書をGeminiがレビューします。

    Cursorが実装したコードをCodeRabbitが確認します。

    このAI同士の受け渡しを安定させる共通言語として、テンプレートが役立っています。

    開発の中心はGitHub Issue

    これらの仕組みを用意したうえで、現在の開発はGitHub Issueを中心に進めています。

    Issueとは、バグ、機能追加、調査、設計など、開発上の作業を登録する場所です。

    私の現在の基本的な開発フローは、次のようになっています。

    1.要望や問題を相談する

    最初は曖昧な状態でも構いません。

    例えば、

    「一部のページが表示できない」

    「画面に表示される数値がおかしい」

    「新しいシーズンのデータ取得へ対応したい」

    「URLを検索エンジンに分かりやすい形へ変更したい」

    といった内容です。

    まずChatGPTと会話しながら、何が問題なのか、どうなれば解決なのかを整理します。

    2.GitHub Issueへ登録する

    整理した内容をGitHub Issueへ登録します。

    この時点で分かっていないことは、無理に確定しません。

    確認できていない内容は未確定事項として残します。

    推測である場合は、推測と明記します。

    以前は、Issueを単なる作業メモのように使っていました。

    現在は、そのIssueを読めば、別のAIでも作業を開始できることを目標にしています。

    3.読み取りだけの調査を行う

    CursorへIssue番号を渡し、まず調査を依頼します。

    この段階では、コードやドキュメントを変更しません。

    現在の処理、関連ファイル、過去のIssueやPull Request、既存の設計を確認します。

    これにより、AIが誤った前提のまま修正を始めることを防ぎます。

    調査結果を見て、私が想定していた問題と実際の原因が違うこともあります。

    先に調査だけを行うことで、不要な実装を減らせます。

    4.設計が必要か判断する

    小さな文章修正や、影響範囲が限定された表示修正であれば、そのまま実装へ進むこともあります。

    一方で、

    • データ構造を変更する

    • URLの形式を変更する

    • クラウド環境の構成を変更する

    • 複数の機能へ影響する

    • 障害時にデータ破損の可能性がある

    といった作業では、先に設計書を作ります。

    この設計段階を省略すると、実装中に判断が増え、AIがその場で仕様を作ってしまいます。

    重要な判断をコードの中へ埋め込まないためにも、先に文章で設計を固めます。

    5.設計を別のAIでレビューする

    重要な設計書は、実装を担当するAI以外にも確認してもらいます。

    正常に処理できる場合だけでなく、

    • 同時に2つの処理が動いたらどうなるか

    • 古い処理結果が後から届いたらどうなるか

    • 途中で失敗した場合に再実行できるか

    • APIの利用上限を超えないか

    • 権限が不足していた場合に安全に止まるか

    などを確認します。

    実装前に問題を見つけられれば、コードを書き直すよりも修正コストは低くなります。

    6.Issueと設計書に沿って実装する

    設計が固まった後に、Cursorへ実装を依頼します。

    ここでは、Issueに書かれていない改善を勝手に行わないこともルールにしています。

    AIは、周辺コードを見て、

    「ここも一緒に直した方がきれいです」

    と判断することがあります。

    しかし、その変更が別の機能へ影響する可能性もあります。

    良い改善に見えても、今回のIssueの対象外であれば、原則として変更しません。

    新しい問題を見つけた場合は、別Issueの候補として報告してもらいます。

    7.自動テストを実行する

    実装後は、変更内容に応じたテストを実行します。

    私のプロジェクトでは、

    • 小さな処理単位を確認するユニットテスト

    • 実際のブラウザ操作を確認するE2Eテスト

    • JSONデータの構造を確認する契約テスト

    • 画面の見た目の変化を画像で比較するVisual Regression

    • コードの書き方を確認するLint

    • TypeScriptと生成されたJavaScriptのずれを確認するテスト

    などがあります。

    さらに、Pull Requestを作ると、GitHub Actionsで自動的にテストが実行されます。

    AIが「テストしました」と報告するだけではなく、GitHub上でも実行結果を確認できます。

    8.Pull RequestでAIレビューを行う

    実装内容をPull Requestへまとめ、CodeRabbitなどでレビューします。

    ここでは、コード自体が正しいかだけでなく、

    • Issueで求めた内容を満たしているか

    • 指示していない変更が混ざっていないか

    • 必要なドキュメントが更新されているか

    • テストが追加されているか

    • 将来の保守が難しくならないか

    も確認します。

    レビューで問題が見つかれば修正し、再度テストを実行します。

    9.開発環境で確認する

    自動テストがすべて成功しても、実際の環境でなければ分からないことがあります。

    そのため、まず開発環境へ反映します。

    画面表示、データ、ログ、クラウド上の処理、エラーの有無などを確認します。

    特にデータ取得処理では、コードが動くだけでなく、期待した場所へ正しいデータが保存されているかまで確認します。

    10.本番へ反映し、Issueを閉じる

    開発環境で問題がなければ、本番へ反映します。

    本番反映後も、必要に応じて画面やログ、データの更新状況を確認します。

    受け入れ条件をすべて満たしたことが確認できれば、Issueを閉じます。

    この一連の流れが、現在の私のIssue駆動開発です。

    ここまで整えた結果、何が変わったか

    最も大きく変わったのは、AIが一度に書くコードの量ではありません。

    開発の再現性が上がりました。

    以前は、同じAIへ同じような依頼をしても、チャットの流れやプロンプトの書き方によって、回答の品質が変わることがありました。

    現在は、別のチャットや別のAIでも、Issueと正本ドキュメントを読めば、同じ前提から作業を始められます。

    指示していないファイルを変更することも減りました。

    調査、設計、実装を分けたことで、誤った理解のまま大量のコードを変更するケースも減りました。

    また、開発の判断がGitHubへ残るようになりました。

    • なぜこの機能を作るのか

    • 何が確認済みなのか

    • なぜこの設計を選んだのか

    • 何を対象外にしたのか

    • どのテストを実行したのか

    • 何を確認して完了としたのか

    これらがIssue、設計書、Pull Requestへ記録されます。

    数か月後に見返したときも、過去のチャットを探し回る必要がありません。

    さらに、特定のAIへ依存しにくくなりました。

    現在はCursorを中心に実装していますが、将来ほかのコーディングAIへ変更する可能性もあります。

    その場合でも、ルールや設計、作業手順がリポジトリに残っていれば、すべてを一から説明し直す必要はありません。

    AIを交換可能な担当者として扱える状態へ、少しずつ近づいています。

    開発よりも、開発環境を作っていた時期

    ここまでの仕組みを整えるには、少し時間がかかりました。

    READMEを更新する。

    ドキュメントを分類する。

    重複した資料を整理する。

    正本を決める。

    コーディング規約を作る。

    AIごとのルールを作る。

    Issueや設計書のテンプレートを作る。

    テストを追加する。

    GitHub Actionsを整える。

    一時期は、新しい機能を作る時間よりも、AIが開発しやすい環境を作っている時間の方が長かったと思います。

    サイトを作っているのか、開発手順書を作っているのか分からなくなることもありました。

    ここまでやりましたが、結局これは本当に必要なのかと自分でも思います。

    小さなサイトや、1回だけの作業であれば、長いプロンプトを書いて直接実装してもらった方が早いでしょう。

    しかし、同じプロジェクトで何十回、何百回とAIへ依頼する場合は、状況が変わります。

    毎回10分かけて同じ注意事項を書くより、ルールを正本へ1度だけ書く。

    毎回「この資料を読んでください」と指定するより、AIインデックスからたどれるようにする。

    毎回「テストしてください」と頼むより、Pull Requestで自動実行する。

    毎回「関係ない場所は変更しないでください」と書くより、Issueの対象範囲とルールで制限する。

    人間が忙しいとき、疲れているとき、少し感情的になっているときでも、同じルールが適用されるようにする。

    過去の失敗を、その場だけの注意で終わらせず、次回から自動的に防げる仕組みにする。

    この積み重ねによって、プロンプトが少しずつ短くなりました。

    プロンプトの情報を削ったのではなく、置き場所を変えた

    ここで誤解されそうなのですが、短いプロンプトそのものが優れているわけではありません。

    何の準備もしていない状態で、

    Issueを見て対応してください。

    とだけ依頼しても、AIは正しく動けないと思います。

    短い指示で動けるようになったのは、その前に大量の情報整理や仕組み作りをしているからです。

    プロンプトに書いていた情報を削除したわけではありません。

    情報の置き場所を、毎回のチャットからプロジェクトの中へ移しました。

    毎回書いていた注意事項は、AI用のルールへ移します。

    仕様は設計書へ移します。

    作業範囲と完了条件はIssueへ移します。

    ファイル同士の関係はマニフェストへ移します。

    出力形式はテンプレートへ移します。

    確認作業は自動テストやCIへ移します。

    判断の経緯はPull Requestやドキュメントへ残します。

    その結果、最後に人間が入力する文章だけが短くなりました。

    つまり、

    「プロンプトが1行になった」

    というより、

    「プロンプトに書かなくてもよい環境になった」

    という方が正確です。

    AI駆動開発で人間が行う仕事

    前回の記事では、人間の役割は、AIが最高のパフォーマンスを発揮できる環境を設計することへ移っていくのではないかと書きました。

    実際に環境整備を進めてみて、その考えはさらに強くなりました。

    現在、私が開発で行っていることの多くは、コードを書くことではありません。

    • 何を作るべきか決める

    • 何を今回は作らないか決める

    • 事実と推測を分ける

    • どの情報を正本にするか決める

    • AIの役割を分ける

    • 作業の完了条件を決める

    • AIの回答を別のAIへレビューさせる

    • AIが迷った箇所をアンケートで確認する

    • 最終的な判断を行う

    といった仕事です。

    AIがコードを書く速度に、人間が正面から対抗する必要はありません。

    人間は、AIがどこへ向かうべきかを決め、迷わない環境を作り、間違えた場合に止められる仕組みを用意する。

    そして最後に、その結果を採用するか判断する。

    少なくとも、現在の私の個人開発では、そのような役割分担になっています。

    結論:短い指示で動ける環境を作る

    AI駆動開発で本当に重要なのは、魔法のようなプロンプトを見つけることではないと思っています。

    AIが必要な情報を自分で見つけられること。

    正式な情報がどれか決まっていること。

    作業の対象範囲が明確であること。

    完了条件が決まっていること。

    間違えた場合に、テストやレビューで止められること。

    別のAIや未来の自分へ、作業を引き継げること。

    人間側の感情や余裕にかかわらず、同じルールが適用されること。

    そのような環境があれば、人間が毎回すべてを説明しなくても、AIは比較的一貫して作業できます。

    以前の私は、AIの回答精度を上げるために、プロンプトを長くしていました。

    現在は、プロンプトを長くする代わりに、AIが参照できる環境を整えています。

    かなり遠回りをしました。

    個人開発としては、少しやりすぎている部分もあると思います。

    それでも、Issue番号を渡すだけで、AIがREADMEとインデックスを読み、関連資料を探し、既存コードを調査し、決められた形式で結果を報告する姿を見ると、この遠回りにも意味があったと感じます。

    AI駆動開発を拗らせた結果、プロンプトは1行になりました。

    細かい指示を毎回書いていた頃よりも、現在の方がAIは正確に仕事をしてくれています。

    AIへ詳しく命令することから、AIが迷わず働ける環境を作ることへ。

    前回の記事で書いた「マインドチェンジ」は、現在このようなIssue駆動開発の形になりつつあります。

    まだ完成ではありません。

    実際に運用する中で、AIが間違えれば原因を確認し、ルールやテストを追加しています。

    さらに、AI自身へアンケートを行い、資料の見つけにくさやルールの曖昧さも確認し始めています。

    おそらく、これからも開発環境は少しずつ変わっていきます。

    ただ、AIが間違えるたびにプロンプトを長くする段階から、同じ失敗が起きないようにプロジェクト側を改善する段階へ進めたことは、大きな変化でした。

    AIを使って開発するのではなく、AIと人間が同じIssueとドキュメントを見ながら開発する。

    現在の私が考えるAI駆動開発は、そのような形です。

    これは、2026年8月時点で私がたどり着いた、自分なりに最適化した現在の仕組みです。

    もちろん、これが唯一の正解とは限りません。開発するものや使用するツールによって、適した進め方も変わると思います。それでも、以前と比べて手戻りや認識違いが確実に減っていることは事実です。

    今の開発フローはMCPによってAIがGitHubや各種ツールの情報へ直接アクセスできるようになったことで、この方法はかなり現実的に回るようになりました。

    一方で、まだ人間がAI同士の回答をコピーして別のツールへ貼り付ける作業も多く、この部分は今後さらに改善されていくはずです。

    AIや関連技術の進化、開発する内容の変化に合わせて、これからも日々やり方を見直しながら、手探りで進めていきたいと思います。

    ただし、すべてをAIへ任せきるのではなく、重要な判断や本番反映など、要所要所で人間が確認する仕組みは、今後も必要だと考えています。

     
     
    AIの力を借りてサッカーのスタッツをサイトを作っています。最近ゲームも作り始めました。 完全自己流で一人で進めています。 noteにはサイトの機能リリース、発見や試行錯誤を残します。 日々勉強です。

    あなたへのおすすめ