なぜAIは我々のソースコードを理解してくれないのか / Why AI Misunderstands Our Code

2025年7月19日,20日開催「PRODUCT HISTORY CONFERENCE 2025」で登壇した際の発表資料です。
https://lp-prohis.youtrust.jp/

Transcript

1. なぜAIは我々のソースコードを 理解してくれないのか 2025.09.19 | PRODUCT HISTORY CONFERENCE 2025 © kaonavi, inc.
2. 鈴木 僚太 株式会社カオナビ CTO室 エキスパート（フロントエンド） 自己紹介 © kaonavi, inc. 2
3. 今回のテーマ : コーディング AIエージェント © kaonavi, inc. 3 コーディング AIは否が応でも発展を続けており、 開発効率向上 を考える上で避けられなくなった。 しかし、誰でもいつでも高品質なコードを ポンと出せる状況には至っていない。
4. 今回のテーマ : コーディング AIエージェント © kaonavi, inc. 4 カオナビではコーディング AIエージェント の導入が 進んでいる。 それに伴い、成功だけでなく失敗の体験も蓄積して きた。 AIエージェントをより使いこなすための礎として、 AIがうまく動いてくれなかった事例 を紹介します。
5. カオナビでの AIエージェントの活用状況 © kaonavi, inc. 5
6. カオナビの AI組織 © kaonavi, inc. 6 カオナビではAI推進室を立ち上げ、さまざまな面から AIの活用をサポート。 その中にはコーディングエージェ ントの導入促進も含まれる。 公式noteの記事もどうぞ →
7. コーディングエージェント © kaonavi, inc. 7 GitHub CopilotとClaude Codeの活用が盛ん。 - テストコードの開発速度向上 - QAエンジニアもテストコード書く - 分野越境 - 新卒メンバーの圧倒的成長 - ディレクターがPoC作る など多数の事例！
8. しかし…… © kaonavi, inc. 8 実際のプロダクトコードの開発に目を向けると、 うまくいった事例ばかりではない。 大規模な開発は言わずもがな、ちょっとした修正でも うまく動かない ケースが多い！
9. This Talk © kaonavi, inc. 9 実際にAIエージェントを活用しているエンジニアたちにヒアリ ングして、 うまくいかなかった事例 を集めました。
10. うまくいかなった事例集 © kaonavi, inc. 10
11. 事例① 謎の関数に AIが気を取られる © kaonavi, inc. 11 カオナビのバックエンドはLaravelで、多言語化のために trans() 関数を使う。 フロントエンドでも、同じtrans()関数を使える仕組みが導入さ れていた。 これは一般的なReactアプリではあまり見られない。
12. 事例① 謎の関数に AIが気を取られる © kaonavi, inc. 12 AIにフロントエンドのバグ調査を依頼すると…… - AIがtrans()を不審に思い、transの定義を探しに行く （本題のバグ調査をしてくれない） - transの定義がないことがバグの原因とか言ってくる （機能開発時にも使いこなせないことがある）
13. 事例① 謎の関数に AIが気を取られる © kaonavi, inc. 13 対策: フロントエンドにおけるtrans()の使い方を ドキュメント化する （未実践。CLAUDE.mdに入れるとかよりも、 必要に応じてAIが探し出せることが重要か？）
14. 事例② オートフォーマットに翻弄される © kaonavi, inc. 14 Claude Codeのhooks機能で自動フォーマットを設定 していたケース。 未使用のimportが削除されるようにした結果……
15. 事例② オートフォーマットに翻弄される © kaonavi, inc. 15 Claude Codeさん「 まず、XXのために〇〇をimportします ... importが削除されています。再度import文を追加します ... ファイルが自動フォーマットされたため、再度編集を行います ... ファイルが自動でフォーマットされてしまうため、必要なコードを作成して から再度組み込みます
16. 事例② オートフォーマットに翻弄される © kaonavi, inc. 16 順番に作業した結果、前の作業が消されてしまい ループにはまった。（自分で気づいて抜け出した） 人間はすぐ気付けるが、AIは気づくのに時間がかかり コンテキストも消費してしまう。
17. 事例② オートフォーマットに翻弄される © kaonavi, inc. 17 対策: 状況に応じてフォーマッターの設定を細かく制御す る？（未実施）
18. 事例③ 空気を読まない © kaonavi, inc. 18 ORM (Eloquent) の便利機能がいろいろあるが、 既存ソースコードではあまり使用していなかった。 ソースコードの統一性の観点から新規コードでも 便利機能は使わない風潮となっていた。 しかしAIは空気を読まずに便利機能を使ってくる。 レビューで弾かれる！
19. 事例④ 空気を読んじゃう © kaonavi, inc. 19 APIのテストにSpectatorを最近使い始めたが、 古い既存のテストコード（使ってない）に引っ張られて AIがSpectatorを使わずにテストを書いてしまう。
20. 事例③ 空気を読まない / ④ 空気を読んじゃう © kaonavi, inc. 20 対策: 最新のコーディングルールを明文化することか。 ただ、量が多くなると精度が悪くなりそうなのが悩み。 AIがすでに持っている「常識」に反しないことも 重要になってきそう。
21. 事例⑤ useEffectで何でも解消しようとする © kaonavi, inc. 21 ReactのuseEffectは誤った使われ方をすることが多い。 AIさんも適当なuseEffectの使い方をしてくる事例多数！ - プロジェクト内のuseEffectの使い方の影響？ - 世間の平均的なuseEffect力を学習している？
22. 事例⑤ useEffectで何でも解消しようとする © kaonavi, inc. 22 対策: useEffectの正しい使い方をプロンプトに含めると、マシに なったという報告あり。 useEffectのレビュー観点を加えてAIにレビューさせる 取り組みも。
23. 事例⑥ 架空のAPIを使う © kaonavi, inc. 23 ReactでuseGetRequestという自前のフックがあった。 GETリクエストをするとき用。 それから類推して、usePostRequestという架空のフックを使い 始めた。 （実際にはPOSTリクエスト用のフックはない）
24. 事例⑥ 架空のAPIを使う © kaonavi, inc. 24 対策: おそらく、AIの想像を裏切らない理にかなったAPI 設計をすることが重要。 （ただ、GETとPOSTではReactでの取り扱いがかなり異なることを 理解するのは、一般的なコーディングの実力としてできてほしい。 そこはAIの単純な実力不足）
25. 事例⑦ 変数の命名で混乱する © kaonavi, inc. 25 「平均年齢」を取り扱う機能で、変数の命名が average_age ではなく age となっていた。 AIに対して「平均年齢」に関する指示をしても、 AIはどこを編集すればいいか理解できなかった。
26. 事例⑦ 変数の命名で混乱する © kaonavi, inc. 26 対策: 命名をちゃんとする。（それはそう） AIはコードを必要最小限だけ読んで理解しようとする。 変数の命名がちゃんとしていることは、効率の良いコード理解の ために非常に重要。 やはり、AIの“常識”を裏切らないことが大事。
27. 事例⑧ ディレクトリ構成のルールを守らない © kaonavi, inc. 27 古いディレクトリ構成と今どきなディレクトリ構成 （featureベースのやつ）があり、最近のコードは新しい ディレクトリ構成で作られているが、 AIが古いディレクトリ構成でコードを書いてしまった。 新しいディレクトリ構成に沿った既存ファイルもあるのに、AIはそち らに合わせなかった。
28. 事例⑧ ディレクトリ構成のルールを守らない © kaonavi, inc. 28 新旧のディレクトリ構成が両方CLAUDE.mdで紹介されて いたので、旧を尊重してしまった？ 対策: 全ての情報をAIに伝えるのではなく、最新の情報に比重を 寄せるべきかも？　（ただし古いコードに直面して混乱する恐れはある）
29. なぜAIは我々のソースコードを 理解してくれないのか © kaonavi, inc. 29
30. なぜ理解してくれないのか © kaonavi, inc. 30 もちろん理由は1つではない。 しかし、事例を集めることで傾向が見えてきた。
31. なぜ理解してくれないのか © kaonavi, inc. 31 Q. なぜAIは我々のソースコードを理解してくれないのか A. 新旧のプラクティスが混在しているから 従来取られがちだった「全部一気に移行するのは大変 だから、できるところからやろう」的な戦略は AI時代にはどうやら裏目に出るようだ。つらい。
32. 考察 © kaonavi, inc. 32 新旧プラクティスが混在していると人間の新規メンバーにも つらいが、人間は歴史的経緯を理解し適応する能力がある。 AIは常に新しくオンボーディングしてきた新人であり、プラク ティスの混在は悪影響が大きい。 （歴史的経緯を全部ドキュメント化する？　コンテキストの無駄遣いすぎ る）
33. やり切ることが重要 © kaonavi, inc. 33 新しいプラクティスを導入するときは、 移行しきることが重要になりそう。 幸い、大量の移行をやり切ることは、 AIによって以前よりも現実的になった。 いわゆるVibe Codingなども、 移行用のスクリプトを作ることに活用できる。 自分も最近、画面数200以上のアプリで Reactのバージョンアップをやり切りました。
34. 余談: AIの常識レベルを見極める © kaonavi, inc. 34 AIが持つ“常識”を裏切らないことが、AIのポテンシャルを発 揮する近道になる。 一方で、求められるレベルがAIの実力よりも高いこともある。 そこはプロンプトによる補正が必要だが、補正量を少なくして 最適化を図りたい。 AIの実力の向上にも敏感になろう。
35. まとめ © kaonavi, inc. 35
36. まとめ © kaonavi, inc. 36 弊社のエンジニアから収集したAIコーディングの事例 を考察し、AIによるコーディングがうまくいかない原因が「新 旧のプラクティスが混在しているから 」である ケースが多いことが分かった。 AIコーディングの時代、移行するならやり切る姿勢が 重要になるかも？
37. We are hiring! https://corp.kaonavi.jp/recruit/list/ 選考を希望する方 https://hrmos.co/pages/kaonavi/jobs/casual21 まずは話を聞いてみたいという方 37 © kaonavi, inc.