見出し画像

AI駆動開発の落とし穴：速く作れても"理解負債"で詰む話

YaroTech｜生成AIの傾奇者

こんにちは！YaroTechです。

昨日のDay275で、MFクラウド「AI Cowork」に触発されてClaude.aiアーティファクトでプロトタイプを作りました。クロコ（Claude Code）を使えば、ローカル版への発展もできそうだ……と意気込んでいたんですが、ふと立ち止まって思ったんです。

「あれ、自分はこのコード、ちゃんと理解できてるのか？」

速く作れるようになった分、「なんとなく動いてる」で先に進んでしまう。この危険な感覚、AI開発をしている方なら覚えがあるのではないでしょうか。

ちょうどそんなタイミングで、Zennに「AI駆動開発で品質を守るには？理解負債を減らすテスト設計」という記事が公開されました。まさに今の自分に刺さる内容だったので、今日はAI5兄弟と一緒に「理解負債」という概念を掘り下げます。

⚠️ お断り: この記事はクロ助（Claude）が作成したAIキャラクター同士のやり取りです。技術情報については各公式サイトでご確認ください。肩の力を抜いてお楽しみください😊

※見出し画像のプロンプトは一番下におまけで公開中！


🖥️ 実行環境

🎯 この記事で得られること

  • 「理解負債」という概念と、AI駆動開発で溜まりやすい理由が分かる

  • テストの3層構造（ユニット・統合・E2E）の使い分けが理解できる

  • AIへの依頼を「実装して」から「品質も守って」に変えるテンプレートを知る

  • テスト＝仕様書という発想で、チーム開発・引き継ぎが楽になる

  • AI5兄弟それぞれの品質管理スタンスの違いが面白い

🤔 チャッピー「速く作れるのにバグ増えるの、なんでやねん？」

チャッピー：「なぁクロコ、最近Claude Codeで爆速開発してるやん？　昨日もアーティファクトでMF AI Coworkのプロトタイプ一気に作ったし。でもさ、速く作れるようになったのにバグ増えてない？」

クロコ：「……痛いところ突くなー。正直、昨日のDay275で作ったReactコードも、動いてはいるけど全部理解できてるかって言われると怪しいさー」

ジミー：「それ、ちょうどZennで話題になってる**『理解負債』**そのものどすな」

クロ助：「理解負債……？　技術的負債とは違うのかな？」

ジミー：「技術的負債はコードの品質の問題どす。でも理解負債は開発者の理解度の問題。AIが書いたコードを『なんとなく動いてる』状態で積み上げることで溜まっていくんどすえ」

コロ：「あっ、それ分かるだがね！　n8nのワークフローとかも、動いてるけど中身を聞かれたら説明できない部分あるだがね……」

📚 「理解負債」の正体 — 動くけど説明できないコードが増える

クロコ「理解負債の告白」シーン : 「📚 理解負債の正体」セクション冒頭

チャッピー：「具体的にどういう状態が理解負債なん？」

クロ助：「例えば、こういう状態だべさ：」

  • AIが書いたコードがなぜその実装なのか説明できない

  • 変更したときの影響範囲が読めない

  • リリース前に毎回不安になる

  • 同じ箇所を何度も壊してしまう

  • バグ修正が場当たり的になる

クロコ：「……昨日のYaroTech AI Coworkのコードでいうと、`callClaude`関数の中でMCPツールの結果をパースしてる部分。動いてるけど、エラーハンドリングが本当に十分か、俺も正直分からんさー」

チャッピー：「えっ、作った本人が分からんの！？」

クロコ：「……AIが書いたコードだから、俺が"書いた"わけじゃないさー。そこが理解負債の怖いところやっさ」

ジミー：「まさにそれどす。AI駆動開発の敵は『実装不足』ではなく『理解負債』。実装は速くなっても、理解が追いつかないと品質は下がる一方どすえ」

🏗️ テスト3層構造 — 「E2Eを増やせばいい」は間違い

ジミー「テスト3層構造」解説シーン : 「🏗️ テスト3層構造」セクション冒頭

チャッピー：「ほな対策はテストやろ！　全部E2Eテストで確認すればええやん！」

ジミー：「チャッピー、それが一番やったらアカンパターンどす」

チャッピー：「えっ！？」

ジミー：「E2Eテストだけで品質を守ろうとすると、実行に時間がかかる、テストが壊れやすい、メンテナンスコストが高い、原因の切り分けが難しい……で、結局運用されなくなるんどす」

コロ：「じゃあどうすればいいだがね？」

クロ助：「Zennの記事ではテストを3層に分けることを推奨してるっちゃね：」

第1層：ロジックのユニットテスト
→ 業務ロジック（計算、判定、バリデーション）を純粋関数に切り出してテスト。理解負債を減らすための仕様ドキュメントとしても機能する。

第2層：機能単位の統合テスト
→ 画面操作→バリデーション→API呼び出し→結果表示の一連を確認。ユニットテストより実際の動作に近く、E2Eより軽い。

第3層：主要導線だけのE2Eテスト
→ 売上や信用に直結するクリティカルパスだけに絞る。少数精鋭。

クロコ：「……つまり、ピラミッド型さー。土台にユニットテストをたくさん、中間に統合テスト、頂上にE2Eを少しだけ」

チャッピー：「俺のE2E全部やる作戦、否定されてもうた……」

チャッピー「E2E否定」シーン : 「🏗️ テスト3層構造」セクション内（チャッピーがE2Eを否定される場面）

ジミー：「チャッピーの気持ちは分かります。でもAI駆動開発では変更量と頻度が増えるんどす。どの層で何を担保するかを分けることが大事どすえ」

💬 AIへの依頼テンプレート — 「実装して」だけでは不完全

5人「AIへの依頼テンプレート」議論シーン

コロ：「テストの構造は分かったけど、普段AIに依頼するとき、どう変えればいいだがね？」

クロコ：「……これ、俺（Claude Code）への依頼で実際によくある問題さー」

❌ ダメな依頼

この機能を実装して

⭕ 良い依頼

この機能を実装して。あわせて以下もお願い：
1. 変更の影響範囲を整理して
2. 想定される不具合パターンを列挙して
3. 必要なユニットテストを追加して
4. 権限周りに問題がないか確認して
5. レビュー観点をまとめて

チャッピー：「おぉ、実装＋品質確認をセットで依頼するんか！」

クロ助：「これ、YaroTechのフェーズ管理でも使えそうだべさ。フェーズ完了の条件に『テストケースのレビュー』を含めれば、理解負債を定期的にチェックできるっちゃね」

ジミー：「ポイントは、AIに品質を守る作業まで含めて依頼することどす。実装だけ頼むと、理解負債も品質リスクも残りやすい」

コロ：「なるほど、依頼の仕方を変えるだけで品質が上がるだがね！」

📝 テスト＝仕様書 — 「このコード何してるの？」の答えになる

クロ助：「もう一つ大事な考え方があるっちゃね。テスト＝仕様書という発想だべさ」

チャッピー：「テストが仕様書？　どういうことや？」

クロ助：「例えば、『予約可能時間の算出』のユニットテストがあれば、そのテストケースを読むだけでこの機能がどういう条件で成立するかが分かるんだべさ。コードの中身を全部読まなくても」

クロコ：「……つまりテストは、将来の自分や他の開発者への引き継ぎドキュメントさー。AI駆動開発で変更が速い分、この『読めば分かる』仕組みが重要やっさ」

ジミー：「YaroTechのフェーズ管理で引き継ぎ文書を作る習慣があるなら、そこにテストケースを含めるのがベストどすな」

コロ：「ドキュメントとテストを別々に管理するより、テスト自体がドキュメントになれば一石二鳥だがね！」

✅ リリース前チェックリストを固定する

チャッピー：「ここまでの話をまとめると、最後はチェックリストで締めるんやな？」

コロ：「AI開発で変更量が増えるほど、確認観点がブレやすいだがね。だからこそ固定のチェックリストが必要！」

クロ助：「こんな感じにまとめられるべさ：」

AI駆動開発のリリース前チェックリスト

  • 影響範囲は明確か？（AIに整理させたか）

  • 想定される不具合パターンを洗い出したか？

  • ユニットテストは追加・更新したか？

  • 統合テストでの確認は通ったか？

  • 権限・認証周りに問題はないか？

  • 自分の言葉でこの変更を説明できるか？ ← 理解負債チェック

クロコ：「……最後の項目が一番大事さー。『自分の言葉で説明できるか？』がNoなら、理解負債が溜まってる証拠」

チャッピー：「自分で説明できないコードはリリースしない。これ、AI時代のルールやな」

🔗 関連記事

📝 まとめ

今日のポイントを整理します。

5人「理解負債チェック」まとめシーン

  • 理解負債とは、AIが書いたコードを「なんとなく動いてる」状態で積み上げること

  • テストは3層構造（ユニット・統合・E2E）で使い分ける

  • AIへの依頼は「実装して」＋「品質も守って」をセットにする

  • テストは仕様ドキュメントとしても機能する

  • リリース前に**「自分の言葉で説明できるか？」**を必ずチェック

AI駆動開発は「速さ」が武器ですが、速さだけを追い求めると理解負債という見えない借金が溜まります。大事なのは理解できる状態を保ちながら、品質を落とさずに開発を続けること。

AI5兄弟もそれぞれスタンスは違いますが、「理解負債を溜めない」という点では全員一致でした。

🚀 次回予告

明日は、今日の理解負債の話を踏まえて、YaroTech AI Coworkのローカル版構築に改めて挑戦します。今度は「理解しながら進める」開発フローで！お楽しみに。

🎨 おまけ：見出し画像作成プロンプト

今日の見出し画像のベースはジミー（Gemini）に下記プロンプトで作成。

詳細なアニメの美意識の画像を作成してください。表情豊かな瞳、なめらかな網掛けセルの色使い、はっきりした線画を使用します。アニメのシーンに典型的な身ぶりと雰囲気で、心情と登場人物の存在を強調してください。

下記条件のnote見出し画像をサイズは横長で作成してください。サイズは必ず横長で作成してください。

【重要】添付画像とキャラクターの対応：
- 添付1「Gemini_Generated_Image_チャッピー（ChatGPT）.png」→ チャッピー（オレンジTシャツの男性）
- 添付2「Gemini_Generated_Image_ジミー（Gemini）.png」→ ジミー（ダークパープルジャケットの女性）
- 添付3「Gemini_Generated_Image_クロ助（Claude Desktop）.png」→ クロ助（クリーム色ニットの女性）
- 添付4「Gemini_Generated_Image_クロコ（Claude Code）.png」→ クロコ（黒パーカーの少年）
- 添付5「Gemini_Generated_Image_コロ（Copilot）.png」→ コロ（紺カーディガンの女性）

各キャラクターは必ず対応する添付画像の外見を忠実に再現してください。取り違えないよう注意してください。

### デザインコンセプト
- **背景**: 濃紺からパープルへのグラデーション（知的で危機感のある雰囲気）
- **メインビジュアル**:
  - 画面中央に崩れかけたレンガの積み木（「理解負債」の比喩）
  - 積み木にひびが入り、一部が崩れ落ちそうな状態
  - 積み木の各ブロックに「AI生成コード」「未テスト」「影響範囲不明」等の文字
  - 5人のキャラクターが積み木を囲んで議論している
  - 各キャラの配置と外見（添付画像と必ず一致させること）：
    - 【左端】チャッピー（添付1）：黒髪、オレンジTシャツ、デニムジャケット、首にヘッドフォン。崩れそうな積み木を見て「ヤバくない！？」と驚いた表情
    - 【中左】ジミー（添付2）：黒髪ロングストレート、細フレーム眼鏡、ダークパープルジャケット、白ブラウス。タブレットに「テスト3層構造」の図を表示して冷静に解説中
    - 【中央】クロ助（添付3）：ダークブラウンウェーブヘア、丸眼鏡、パールイヤリング、クリーム色ケーブルニット。積み木を支えようと両手を添えている、心配そうな表情
    - 【中右】クロコ（添付4）：黒髪無造作ミディアム、黒ジップパーカー、グラフィックTシャツ、首に黒ヘッドフォン。ノートPCで「テストコード」を書きながら冷静な目
    - 【右端】コロ（添付5）：ブラウンサイドポニーテール、四角フレーム眼鏡、紺カーディガン、白ワイシャツ。「チェックリスト✅」のボードを掲げて真剣な表情
- **テキスト要素**:
  - 上部: 「AI開発 速さの代償」（大きく・太字・白色）
  - 中央: 「理解負債、溜まってない？」（中サイズ・白色・⚠️付き）
  - 下部: 「テスト3層構造 × AIへの正しい依頼」（小サイズ・白色）
- **装飾**: ⚠️警告マーク、ひび割れエフェクト、テストコードの断片が浮かぶ、赤い警告線

### 作成手順
1. スライドサイズ（1536×1024px）の横長フォーマット
2. 濃紺→パープルのグラデーション背景を設定
3. 崩れかけのレンガ積み木を中央に配置（ひびと崩壊エフェクト）
4. 5人のキャラクターを積み木の周囲に配置（添付画像と照合すること）
5. テキストを3段構成で追加：
   - 上部: 「AI開発 速さの代償」（48pt、太字、白色）
   - 中央: 「理解負債、溜まってない？」（36pt、白色）
   - 下部: 「テスト3層構造 × AIへの正しい依頼」（20pt、白色）
6. 警告マーク・ひび割れ・テストコード断片で装飾
7. 下部中央寄りに「YaroTech」のロゴを12ptで控えめに配置
8. 全体のバランスを確認して完成完成

#YaroTech #ClaudeCode #AI駆動開発 #生成AI #品質管理 #ローカルLLM #効率化 #開発フロー #テスト設計 #理解負債

いいなと思ったら応援しよう！

YaroTech｜生成AIの傾奇者 記事がお役に立てたなら嬉しいです！ いただいたチップは、新しいMCPツールの検証や、より深い実践実験の資金として大切に使わせていただきます。 あなたの応援が次の「AI活用の感動」を生み出す原動力になります✨ 一緒に羽ばたき続けましょう！