AI駆動開発の極意～AIは〇〇と思え～

AI開発の極意～AIは〇〇と思え～

こんにちは、@mossan_hoshiです。この記事はTRIAL＆RetailAI Advent Calendar 2025の8日目の記事です。

昨日の記事は @10long さんの「【圏論×AI×認知科学】村上春樹「ノルウェーの森」をLLMで形式化してみた #自由エネルギー原理」でした。 個人的には、FEPもノル森（映画）も好きだったんですが、正直理解が浅かったんですよね。でもこの記事を読んで、「FEPって認知バイアス最小化原理なのか！」とか「あのキャラの行動にはこういう理由があったのね」みたいに腹落ちして、めちゃくちゃ面白く読めました！おススメです！

はじめに：動画での解説について

本日は、私がAIコーディングを始めてちょうど一年ぐらい（昨年末にGitHub Copilot→6月ぐらいからClaude Code→10月ぐらいからCodex CLI）経つので、この1年AIコーディングをガッツリやって身につけた 「極意」 (もといメンタルモデル)を共有したいと思います。

正直なところ、記事よりも↑の動画を見ていただきたい です！ 動画の方が内容的に分かりやすいし、時間と気合をかけて作っていますし、そもそもこの記事自体は動画と資料を基にほぼAIで作成したものですｗ

とはいえ、動画を見る時間がない方向けに、以下でテキストでも解説していきますね。
（さらに時間のない人は以下のインフォグラフィックス＋スライドでもよいかと思います（どちらもNotebookLM作成）)

一般的な誤解：「AI ＝ 新人」という認識

AIコーディングを始めるとき、一般的に広まっていると思われるメンタルモデルがあります。

「AIコーディング ＝ 新人の代わり」

実際、2023年のGPT-4が出た当初は私もそう思っていましたし、ドヤ顔で「知識はあるけど言われたことしかやらない部下だと思え」なんて言及してました。 世間的にも「新人採用の代わりにAIを」みたいなニュースが話題になったのも記憶に新しいかと思いますし、この「AI=新人」のメンタルモデルを主張しても大きく非難されることはないかと思います。

でも、この1年ガッツリやってみて気づいたんです。
この「新人（ジュニア）」というメンタルモデルは、実は不完全だと。

人間とAIの決定的な違い

決定的な違いは**「成長の有無」**です。 人間の新人は、最初は何も知らなくても、業務を通じて経験を積み、記憶し、脳内で学習して成長していきます。 一方で、現在のAIエージェントは厳密にはコーディング中に学習しません。 会話・作業のログ（コンテキスト）が溜まるだけで、モデル自体のパラメータが更新されて賢くなるわけではないんです。

コンテキストを変えたり、新しいチャットを立ち上げたりすれば、彼らはまた「記憶ゼロ」の状態に戻ります。
これを「新人」だと思って接していると、いつまで経っても成長しない部下にイライラすることになりかねません。

提案するメンタルモデル：「AI ＝ 初見のスポットバイト」

そこで私が提案したい、より実践的なメンタルモデルがこれです。

「AIコーディング ＝ 初見のタイミー（スポットバイト）さん」

しかも、ただのスポットバイトじゃありません。
「一発言ごとに交代して帰ってしまう、超・短期スポットバイト」
だと思ってください。

実際の開発シミュレーション：新人とAIの違い

じゃあ実際に開発の現場でどう違うのか、ターンごとの挙動をシミュレーションしてみましょう。
これがわかると、AIに対する接し方がガラッと変わるはずです。

開発開始（ジョイン時）

まずは開発開始のタイミング。
ここでは新人くんもAIエージェントも同じで、リポジトリについては何も知らない「クリーン」な状態です。

【第一ターン】環境理解と修正案

私：「まず環境理解して。〇〇という問題あるから修正案考えて」

• 新人くんの場合
  1. 環境理解（ドキュメント読む、コード読む）
  2. メモを取る＆脳内で学習（理解）する
  3. 修正案を提出して、待機（自走できるなら別の作業へ）
• AIエージェントの場合
  1. 環境理解（ファイル読み込み）
  2. コンテキストを更新（メモリ消費：5%） ※モデル自体は学習しない
  3. 修正案を提出して、即帰宅。

AIはこの時点でもう帰っちゃいます。「へい、お疲れしたー！」って感じです。

【第二ターン】修正への指摘

私：「これだと△△が問題では？」

• 新人くんの場合
  1. 指摘に対して調査。
  2. 前のターンの記憶（学習内容）があるので、それを踏まえて考える。
  3. さらに学習して回答を提出。待機。
• AIエージェントの場合
  1. 「はじめまして！」（新しいエージェントが来る）
  2. 前任者が残したコンテキスト（ログ）とリポジトリを最初から全部読み直して現状を把握。
  3. 回答を提出して、コンテキスト更新（メモリ消費：10%）。
  4. 即帰宅。

ここが重要です。AIエージェントはチャットが続いているように見えて、毎回別人が来て、毎回最初からログを読み直して状況把握しているんです。
だから常に**「誤読」のリスク**がつきまといます。

～～なんやかんやあって～～

【第nターン】長期化した開発

私：「XXXX（なんかの指示）XXXX？」

• 新人くんの場合
  1. これまでの経験でリポジトリに詳しくなっている（完全に学習済み）。
  2. サクサク対応。成長を感じる。
• AIエージェントの場合
  1. 「はじめまして！」
  2. ログを読もうとするが…「あ、コンテキスト溢れました」
  3. 強制リセット（メモリ消費：100% → 0%）。
  4. 記憶喪失状態で対応。

これです。これがAIコーディングの最大の恐怖。
チャットが長くなると、必ずコンテキストウィンドウ（Geminiならかなり長いですが、Cursorとかだとすぐです）が溢れます。
溢れた瞬間、彼らはこれまでの経緯を全て忘れます。

【第n+1ターン】リセット後の悲劇

私：「さっきの件だけど…」

• 新人くん：「あ、はいはい例の件ですね」
• AIエージェント：「**え？何のことですか？はじめまして！**とりあえず今あるファイル全部読んで推測してそれっぽいこと言いますね！」

ここで**特大の認識違い（幻覚・バグ）**が生まれるわけです。
新人は成長しますが、AIは「コンテキスト」という頼りない糸だけで繋がっている「一言一会の他人」の集まりなんです。

AIコーディングを成功させるための対策

「毎回初見の人が来る」
「一言喋るごとに担当者が変わる」
「突然記憶喪失になる」
こんな過酷な環境（他人数開発みたいなもんですね）で、まともに開発を進めるにはどうすればいいでしょうか？

答えはシンプルです。
「初見の人が来ても、絶対に勘違いしようがないリポジトリにしておく」
これに尽きます。
具体的には、以下のような「チーム開発のベストプラクティス」を徹底することです。

1. 紛らわしい要素を徹底排除する

初見殺しのリポジトリはAIにとっても地獄です。

• 紛らわしい名前：一般的な使われ方と違う意味の単語を使わない。
• 意味不明な変数名：var t1 とか絶対ダメ。説明がない変数は初見さんには解読不能です。
• 複雑怪奇なディレクトリ構成：モノレポで階層が深すぎたり、どこを見ればいいか分からない構成はNG。
• 重複した役割：似たようなファイルや関数が複数あると、「こっちを修正すればいいのかな？」とAIが誤爆します。

人間が見ても「これどっち触ればいいの？」と迷うようなコードは、AI（初見さん）も当然迷います。そして間違えます。
誰が見ても一発で意味がわかる、「独属性」の低いクリーンなコードを保つことが、AIに働いてもらうための第一歩です。

2. 仕様駆動開発によるドキュメントの整備

私が特におすすめしたいのが**「仕様駆動開発」的なアプローチです。
とにかくドキュメントこそが正義**です。

• 要件定義
• 完了条件
• 具体的な開発タスクの手順
• これまでの開発経緯や課題（知見）
• 開発ルール

これらを網羅した**「ここさえ読めば全部わかる」ドキュメントを用意しておきます。
（README.mdに書くか、専用のDocsを用意するかは規模によります）
そして、AIへの指示は毎回「まずこのドキュメントを読んでね」から始める。 あるいは、コンテキストが切れそうなタイミングで、次のAI（次のターンの自分）への「引き継ぎプロンプト」**を書かせる。

こうすることで、毎回担当者が入れ替わる「タイミー状態」でも、ドキュメントという「共通の地図」があるおかげで、迷わずにゴールまで辿り着けるようになります。

補足：ちなみにこの記事書いた後に一般的な仕様駆動開発のデファクトスタンダード的なツールSpec-kit使ってみたのですが、リポジトリをスクラッチから立ち上げる時はそちらの方がしっかりとしたプロダクト作れていいなと感じました。一方ですでにある程度開発が進んでるプロダクトではドキュメントの重複や運用方針がマッチせずに導入難しそうだなとも感じました（単純に私がSpec-kit使いこなせてないだけの可能性も高いですが)

3. 「魔法使いの呪文」を覚える

最後に補足ですが、コーディングプラクティス用語（DRY原則、KISSの原則、SOLID原則など）は、AI時代において**「魔法の呪文」**になります。

例えば「ここ、共通化しといて」と頼むより、「DRY原則に従ってリファクタリングして」と頼むほうが、AIには圧倒的に正確に伝わります。 これらの用語は、AIが膨大な学習データの中で関連付けられている「概念のパッケージ」なので、一言唱えるだけで複雑な意図を一発で伝えられるんです。

つよつよエンジニア（魔法使い級エンジニア）が使う専門用語は、AIを操るための呪文そのものです。

個人的には「プリンシプル オブ プログラミング 3年目までに身につけたい 一生役立つ101の原理原則」のような「深く理解したり自分で書けるようにはならないけど、名前や概要は把握できる状態になれる」書籍で語彙を蓄積するのがおすすめです(今であれば書籍の内容が物足りなくてもAIに質問できますしね）。

ちなみに、いい感じの書籍が無ければAI自体に作らせるというのも手です。かなり昔ではありますが私もデザインパターンとアーキテクチャパターンの本をAIに作らせてざっくり概要把握したりしました

ぜひ、基本的なプラクティス用語を覚えて、AIという召喚獣に唱えてみてください。

まとめ

結局のところ、AIコーディングの極意とは、
「人が参加しやすい（分かりやすい）リポジトリは、AIも参加しやすい」
という結論に帰着します。
「AIだから」と特別なことをするのではなく、古くからある「チーム開発の基礎」を徹底すること。
「毎回記憶をなくすけど、マニュアルさえあれば超優秀なスポットバイトさん」
このメンタルモデルを持って、彼らが迷わないように丁寧に道を整備してあげてください。
そうすれば、彼らは爆発的なパフォーマンスを発揮して、あなたの開発効率を10倍にしてくれるはずです！
詳しくはぜひ動画を見てみてくださいね！

さいごに

明日の記事は @tr-10k さんの記事です。エンジニア未経験との事でどういう切り口になるのか楽しみです！

Retail AI と TRIAL ではエンジニアを募集しています。

この記事を見て興味を持ったという方がいらっしゃいましたら、ぜひご連絡ください！（入社して一年半ぐらい経ちますが、会社の規模は大きいのに急成長を続けており（最近も西友を買収し東京へ進出しました）、それでいて出自がIT企業なのでベンチャー精神が強く実店舗と連携したPoCなどの敷居も低く（今現在もめちゃくちゃたくさんのPoC走ってます！）、リリースされれば大規模に展開され(トライアル・西友合わせて６００店舗越え！さらに外販も！）に展開できる、エンジニアにとっては結構理想的な環境だと感じています。ちなみに私は基本リモート（週1出社）です）