AI駆動開発のベストプラクティス｜コードの前に「誰が・何で・どのデータ」を決め、修正の沼を避ける

「AIに頼めばアプリができる」と聞いて、Claude Codeなどで社内の業務アプリを作り始める会社が増えています。エンジニアでなくても、日本語で頼めば動く画面が出てくるのは本当です。

ただ、SalesDockが支援先の業務アプリをAIで作って本番で運用してきて、時間を取られたのはコードを書く工程ではありませんでした。作ったあとの「ここも直して」が別の修正を呼び、終わらなくなるのです。この記事では、そうならないために守っている進め方を書きます。

AI駆動開発そのものの意味や、業務の聞き取りから運用までの全体の流れはAI駆動開発とは？業務から始める進め方にまとめています。この記事は、その中で「実際に作るとき何を守るか」に絞った続きです。

AI駆動開発のベストプラクティスは「決める→質問させる→小さく頼む→確かめる」の順番です

AIは、指示の足りない部分を推測で埋めて、とにかく動くものを作ります。これは長所でもあり、業務アプリでは落とし穴にもなります。推測が外れた場所が画面の色なら一瞬で直せますが、データの持ち方だと、画面・集計・Excelへの出力までまとめて直すことになるからです。

そこで、作る前・作っている間・作ったあと・チームで使うときの4つの場面ごとに、守ることを決めています。

コードを書かせる前に、誰が・何で・どのデータとつながるかを決める

AIにコードを書かせる前に、業務を知っている人が決めるべきことは3つです。誰が使うか（役割ごとに見てよい項目・直してよい項目）、何を使って入力・確認するか（スマホ・パソコン・Excelのどれを正とするか）、どのデータとつながるか（ER図）です。どれも外れると、画面・集計・出力までまとめて直すことになります。画面の組み方やコードの書き方はAIに任せてかまいませんが、この3つは業務を知っている人にしか決められません。

勤怠アプリで考えると

スタッフがスマホで休みや交代を申請し、事務が承認し、経営者がExcelで一覧を見る勤怠アプリを例にします。

承認の状態をアプリの画面からもExcelからも変えられる作りにすると、「保留にしたはずの申請が、あとで承認へ戻る」といった食い違いが起きやすくなります。片方で変えた値を、もう片方の古い値が上書きしてしまうからです。どちらを正とするかを作る前に決めていれば、「Excelは読むだけ」と最初から作り分けられます。「誰といつ交代したかを本人のページで見たい」という要望も同じです。交代の記録を申請した側にしか持たせていないと、相手として名指しされた分をあとから探し出す処理を足すことになります。交代には必ず相手のスタッフがいる、という線を最初に引いていれば要らない手間です。

どちらも、コードを1行ずつたどっても書き間違いは見つかりません。原因は、作る前に決めていなかったことにあります。

ER図は紙に箱と線を描けば足ります

ER図というと専門的に聞こえますが、業務アプリの最初の1本なら、紙に箱を3〜5個描いて線でつなぐだけで十分です。箱には「スタッフ」「申請」「日付」のような業務の言葉を使い、線の横に「1人が何件も出す」のように数の関係を書きます。書けたら写真に撮るか箇条書きに直して、AIに渡します。

書き出す前に、いまの業務で誰が何をしているかを洗い出しておくと、箱の漏れが減ります。手順は業務棚卸しのやり方、同じ値を2か所で直せる作りの危うさはマスタデータの持ち主を決める記事で詳しく書いています。

AIに質問させてから計画を出させ、人が確かめてから作らせる

1枚を渡したら、すぐに「作って」とは頼みません。先に「この1枚で分からないことを質問して」と頼みます。AIが聞いてくるのは、たいてい1枚に書き漏れた例外です。答えられない質問は、その場で推測せず現場に確認します。

質問が尽きたら、何をどの順で作るかの計画を出させます。Claude Codeを作っているAnthropicの公式ガイドも、いきなりコードを書かせると違う問題を解くコードができることがあるとして、調べる・計画する・書くを分けるよう勧めています。大きめの機能では、AIに自分へ質問させ、答えを仕様書にまとめさせてから実装に入る方法も紹介されています。

計画はコードが読めなくても確かめられます

計画は、コードが読めなくても確かめられます。見るのは、1枚に書いた役割・入力の場所・箱と線が、計画のどこかに出てきているかどうかです。出てこないものがあれば、その時点で指摘します。

1回の依頼は1つの変更にし、動作を確かめる手段を渡す

作り始めたら、1回の依頼は1つの変更にとどめます。「一覧に並び替えを付けて、ついでに色も変えて、Excel出力の列も足して」とまとめて頼むと、どの変更で何が壊れたかが分からなくなります。1つ終わるたびに画面で動かし、よければ次へ進みます。

AIが自分で確かめられる手段を渡すのも効きます。AnthropicのClaude Code公式ガイド（Best practices for Claude Code）は、テストやスクリーンショットのように、AIが自分で結果を読める確認手段を渡すことを最初の推奨に挙げています。非エンジニアなら、「申請して、承認して、Excelに出るまでを試して、結果を見せて」と、確かめる手順そのものを依頼に書き足すだけでも変わります。

同じ不具合が2回直らなければ、会話をやり直す

同じ不具合を2回言い直しても直らないときは、会話を続けずに閉じます。Claude Codeの公式ガイドでも、同じ問題を2回直しても直らなければ、会話をリセットし（/clear）、分かったことを入れた具体的な依頼で始め直す方がよいとされています。失敗したやり方が会話に積もるほど、AIの答えはぶれていきます。

決めたことは短い指示書に残し、AIに毎回読ませる

「Excelは読むだけ」「スタッフには口座を見せない」のように決めたことは、会話の中に置いたままにせず、ファイルに書いて残します。Claude Codeでは、フォルダに置いたCLAUDE.mdという指示書を毎回読み込ませられます。

ただし、長く書くほど効くわけではありません。Claude Codeの公式ガイドは、1行ごとに「この行を消したらAIが間違えるか」を問い、そうでなければ削るよう勧めています。指示書がふくらむと、本当に守らせたい指示が読み飛ばされるからです。業務のルールは1枚の設計メモ、AIへの作業の約束は短い指示書、と分けておくと保ちやすくなります。

チームで使うときは、作業場所・担当・承認を分ける

チームでAI駆動開発をするときは、①作業ごとに作業場所（フォルダ）を分ける、②1つの作業の実装担当を1人か1つのAIに決め、ほかは確認役に回る、③変更は差分を人が確認してから本番に取り込む、の3つを決めます。1人で作るうちは起きない衝突が、複数の人やAIを同時に動かすと起き始めるからです。SalesDockでも社内の開発で複数のAIを併用しており、実際に次のような事故がありました。

8つのAIの作業を並行で走らせたとき、あるAIが作った集計用のファイルを、別のAIが同じ名前で上書きしました。その結果、他の作業の出力を自分の結果として読んでいたのです。元のファイルを作ったAIが、途中で自分の出力と違うことに気づいたため実害は出ませんでしたが、気づかなければ別のページの数字で判断していました。それ以来、次の3つを守っています。

• 作業ごとに作業場所（フォルダ）を分け、同じ場所で2つの作業を動かさない。
• 1つの作業の実装担当は1人（または1つのAI）に決め、別の人やAIは確認役に回る。
• 変更はいきなり本番へ反映せず、差分を人が確認してから取り込む。

業務アプリを社内の数人に使ってもらう段階になったら、権限・データの戻し方・引き継ぎも確認します。どこから本番扱いになるかはバイブコーディングで作ったツールの本番公開ライン、確認項目はAIで作った社内ツールの本番導入前チェックリストにまとめています。Claude Codeを業務で使うときの安全面の注意はClaude Codeで業務ツールを作るときの注意点で書きました。

修正の沼にはまるときに、よく見かける進め方

AI駆動開発で修正の沼にはまる進め方は、主に4つです。1行で「作って」と頼む、画面を見ながら思いついた順に直す、同じ不具合を何度も言い直す、複数の人やAIが同じフォルダで作業する。どれか1つを変えるだけでも、直しの回数は減ります。

効果は、作る速さでなく「作ったあとの直し」で測る

設計を先にやった効果は、最初の画面が出るまでの速さには表れません。むしろ最初は少し遅くなります。効果が見えるのは作ったあとです。次の4つを、1本目のアプリから記録しておきます。

• 作ったあとに来た修正依頼を、「使う人・入力の場所・データのつながりを変えないと直らないもの」と「見た目や文言の好み」に分けて数えます。
• AIへの依頼のうち、前の状態に戻した回数を数えます。戻す回数が減らないなら、依頼が大きすぎるか、設計メモが足りていません。
• 設計メモを書き直した回数と理由を1行ずつ残します。「使う人が増えた」が続くなら、権限の確認へ進む合図です。
• 2本目のアプリで、設計が原因の修正依頼と、それを直した時間が1本目より減ったかを比べます。

設計が原因の修正依頼が見た目の依頼より多いなら、次のアプリでは1枚に使う時間を増やします。見た目の依頼が中心なら、今の厚さで足りています。

来週試すなら、いま作りたいアプリで1枚を書くところから

いきなり新しいアプリを作る必要はありません。作りたいアプリ、あるいはすでに作りかけているアプリを1つ選び、誰が使うか・何を使って入力と確認をするか・どのデータとつながるかを、A4に書いてみてください。小さな業務アプリなら、30分ほどを目安にしてください。

書けたら、その1枚をAIに渡して「分からないことを質問して」と頼みます。AIの質問に答えられなかった項目が、そのまま現場に確認すべきことの一覧になります。作りかけのアプリなら、その一覧に、これまでの修正依頼のどれが当てはまるかを照らしてみると、沼の入口がどこにあったかが分かります。何から決めればよいか迷う場合は、要件定義を進める前に決めることも参考になります。

一次情報・公式情報

• Claude Code Docs「Best practices for Claude Code」（調べる・計画する・書くを分ける、AIに質問させる、確認手段を渡す、指示書を短く保つ）
• Claude Code Docs「How Claude remembers your project」（CLAUDE.mdの置き方）

AI駆動開発のベストプラクティスのよくある質問