🏗️ AIが書いたコードをレビューするスキルを考えよう【第三回・最終回】設計・アーキテクチャの視点

1. 👋 はじめに

前回まで「動作・ロジック・可読性・パフォーマンス・セキュリティ」の視点を学びました。

最終回は一番奥深いテーマです。

設計・アーキテクチャの視点：
「今動く」だけでなく「半年後・1年後も無理なく変更・拡張できるか」

AIが最も苦手とする領域です。なぜなら設計の良し悪しは、プロジェクトの文脈・チームの状況・将来の方向性を知らないと判断できないからです。

---

2. 🤔 なぜ設計はAIが苦手なのか

良い設計には、AIが持っていない「文脈」が必要です。

必要なもの	具体的な内容
📋 プロジェクトの文脈	ビジネス要件・非機能要件（速度・可用性など）
👥 チームの状況	メンバーのスキル・人数・開発の慣習
🔮 将来の方向性	拡張予定・変更が多い部分・長期ロードマップ
⚖️ トレードオフの判断	速さ vs 安全・シンプル vs 柔軟・コスト vs 品質

AIはコードを「書く」のは得意ですが、
これらの文脈を持っていないため
「その場では動くが、将来困る設計」を生成することがあります。

---

3. 🧩 視点⑥：責任の分離

1つのものが1つのことをする

責任の分離（Separation of Concerns）とは？
「それぞれのコードが1つのことだけを担当する」という考え方です。
料理で例えると「調理・盛り付け・片付け」を別々の人が担当するイメージです。

📖 専門用語では「単一責任の原則（Single Responsibility Principle）」と呼びます。
これはソフトウェア設計の重要な指針をまとめた「SOLID原則」の1つ目にあたります。
中級者を目指す人はぜひ調べてみてください！
下記の記事も参考までにご覧ください。

AIは「とりあえず動く」ことを優先するため、1つの関数・クラスに複数の責任を持たせてしまうことがあります。

責任が混在しているコード	何が問題か
データ取得・加工・表示を1つの関数でやっている	修正するとき影響範囲が大きい
ビジネスロジックとデータベース操作が混在	テストが書きにくい
UIの処理とAPIの呼び出しが同じファイル	再利用しにくい

❌ AIがやりがちなコード（責任が混在）

// ユーザー情報を取得・加工・メール送信を1つの関数でやっている
async function processUser(userId: string) {
  const user = await db.user.findUnique({ where: { id: userId } });
  const formattedName = user?.name.toUpperCase() ?? "名前なし";
  await sendEmail(user?.email, `こんにちは、${formattedName}さん`);
  await db.user.update({
    where: { id: userId },
    data: { lastContactedAt: new Date() }
  });
  return { success: true };
}

✅ 人間がレビューして修正したコード（責任を分離）

// 責任①：データ取得だけを担当する関数
async function getUser(userId: string) {
  return await db.user.findUnique({ where: { id: userId } });
}

// 責任②：データの加工（フォーマット）だけを担当する関数
// → DBやメールとは無関係。純粋に文字列の変換だけ
function formatUserName(name: string | null | undefined): string {
  return name?.toUpperCase() ?? "名前なし";
}

// 責任③：メール送信だけを担当する関数
// → ユーザーの取得やDB更新は知らない
async function sendWelcomeEmail(email: string, name: string) {
  await sendEmail(email, `こんにちは、${name}さん`);
}

// 責任④：DB更新だけを担当する関数
// → メール送信や名前のフォーマットは知らない
async function updateLastContacted(userId: string) {
  await db.user.update({
    where: { id: userId },
    data: { lastContactedAt: new Date() }
  });
}

// 責任⑤：全体の流れを制御するだけの関数
// → 細かい処理は各関数に任せ、「何をどの順番でやるか」だけを知っている
async function processUser(userId: string) {
  const user = await getUser(userId);           // ①データ取得
  if (!user) throw new Error("ユーザーが見つかりません");
  const name = formatUserName(user.name);       // ②名前をフォーマット
  await sendWelcomeEmail(user.email, name);     // ③メール送信
  await updateLastContacted(userId);            // ④最終連絡日を更新
  return { success: true };
}

チェックのポイント：
関数やクラスの説明を「〜して、〜して、〜する」と複数の動詞で説明しなければならないなら、分割を検討しましょう。
1つの関数は「〜する」の1動詞で説明できるのが理想です。

---

4. 🔗 視点⑦：依存関係

依存関係を意識する

依存関係（dependency）とは？
「AはBがないと動かない」という関係のことです。
依存関係が複雑になると、1か所を変更しただけで別の場所が壊れることがあります。

AIは「今動く」コードを書くため、依存関係を整理せずに実装することがあります。

問題のある依存関係	リスク
具体的な実装に直接依存している	実装を変えると全体が壊れる
循環依存（AがBに依存・BがAに依存）	どちらかを変えると無限ループになる
外部サービスに直接依存している	テストが難しくなる

❌ AIがやりがちなコード（具体的な実装に直接依存）

// メール送信の実装を直接使っている
import { sendgrid } from "@sendgrid/mail";

async function notifyUser(email: string, message: string) {
  await sendgrid.send({ to: email, subject: "通知", text: message });
  // SendGridを別のサービスに変えたいとき、この関数も変える必要がある
}

✅ 人間がレビューして修正したコード（インターフェースに依存）

// メール送信の「インターフェース（約束事）」を定義
interface EmailSender {
  send(to: string, subject: string, body: string): Promise<void>;
}

// 実装はどんなサービスでも差し替えられる
async function notifyUser(
  emailSender: EmailSender,  // 具体的な実装ではなく約束事に依存
  email: string,
  message: string
) {
  await emailSender.send(email, "通知", message);
}

こうしてインターフェース（約束事）に依存させておくと、実務で大きなメリットが生まれます。

• 本番環境： SendGridEmailSender を渡してメールを実際に送信
• ローカル・テスト環境： ConsoleEmailSender（コンソールにログを出すだけのダミー）に1行で差し替え

Supabaseのような外部サービスも同様で、
インターフェースを挟んでおくと「本番はSupabase・テストはモック（偽物）」という切り替えが驚くほど簡単になります。
テストのたびに実際のDBにアクセスしなくて済むため、開発速度も上がります。

「このコードの一部を別の実装に変えたくなったら、どれだけ修正が必要か？」
この問いかけが依存関係の問題を発見するヒントになります。

---

5. 📐 視点⑧：拡張性

変更に強いコードを作る

拡張性（extensibility）とは？
「新しい機能を追加するとき、既存のコードをあまり変えなくてよい」という性質です。
拡張性が低いコードは「1か所変えると別の場所が壊れる」ことが多いです。

AIは「今の要件」に合わせたコードを書きますが、「将来の変更」を考慮しないことが多いです。

拡張性の問題	具体例	何が起きるか
条件分岐が増え続ける	決済方法が増えるたびに if/else が増える	コードが複雑になり修正が怖くなる
ハードコードされた設定	消費税率が 0.1 と直書きされている	税率変更のたびに全ファイルを修正
同じコードが複数の場所にある	バリデーションが各所にコピペされている	修正漏れが起きやすい

❌ AIがやりがちなコード（条件分岐が増え続ける）

// 決済方法が増えるたびにif/elseが増える
async function processPayment(method: string, amount: number) {
  if (method === "credit_card") {
    await processCreditCard(amount);
  } else if (method === "paypal") {
    await processPaypal(amount);
  } else if (method === "apple_pay") {
    await processApplePay(amount);
  }
  // 新しい決済方法が増えるたびにここに追加しなければいけない
}

✅ 人間がレビューして修正したコード（新しい決済方法を追加しやすい）

// 決済処理の「約束事」を定義
interface PaymentProcessor {
  process(amount: number): Promise<void>;
}

// 各決済方法を独立して実装
class CreditCardProcessor implements PaymentProcessor {
  async process(amount: number) { /* ... */ }
}

class PaypalProcessor implements PaymentProcessor {
  async process(amount: number) { /* ... */ }
}

// 新しい決済方法はクラスを追加するだけ・既存コードを変えなくてよい
async function processPayment(
  processor: PaymentProcessor,
  amount: number
) {
  await processor.process(amount);
}

「新しい〇〇が追加されたとき、何か所修正が必要か？」
この問いかけで拡張性の問題を発見できます。
理想は 「新しいクラスを1つ追加するだけ」 です。

📖 これは「オープン・クローズドの原則（Open-Closed Principle）」という設計の基本形です。
「拡張に対して開いており（新しいものを追加しやすい）、修正に対して閉じている（既存コードを変えなくてよい）」という意味で、SOLID原則の2つ目にあたります。
Before/Afterのコードで、まさにこの原則が体現されています！
下記の記事も是非ご覧ください。

---

6. 🤝 視点⑨：AIと協働するレビュー

AIをレビューの相棒にする

設計の問題を発見するために、AIに逆質問するのも効果的です。
以下はそのままCursor・ChatGPT・Claudeにコピペして使える「魔法のプロンプト」です 🪄

---

🔍 責任の混在を発見するプロンプト

このコードの責任（役割）を日本語で説明してください。
もし「〜して、〜して、〜する」と複数の動詞が必要なら、分割の提案もしてください。

---

🧪 テストしにくい設計を発見するプロンプト

このコードに対してユニットテストを書いてください。
テストを書くのが難しい場合は、その理由と設計の改善案を教えてください。

---

📐 拡張性の問題を発見するプロンプト

新しく「〇〇（機能名）」を追加したい場合、このコードの何を・何か所修正する必要がありますか？
修正が多い場合は、より拡張しやすい設計を提案してください。

---

🔗 依存関係の問題を発見するプロンプト

このコードの依存関係を整理してください。
外部サービスや具体的な実装に直接依存している部分があれば、インターフェースを使った改善案を提案してください。

---

👴 保守性を確認するプロンプト

このコードを6ヶ月後に初めて読んだ開発者がいたとして、
「わかりにくい・なぜこう書いたかわからない」と感じる部分はどこですか？
改善案も合わせて提案してください。

---

AIは「書く」だけでなく「批評する」こともできます。
自分が書いたコード・AIが書いたコードを別のAIセッションで批評させるのも効果的です。

AIの限界を補う：文脈の記録

AIは毎回文脈をゼロから始めるため、設計の意思決定を記録しておくことが重要です（第二シリーズで触れましたね）。

記録すべき内容	残す場所
なぜこの設計を選んだか	ADR（Architecture Decision Records）
検討したが選ばなかった選択肢	ADR
このコードの制約・注意点	docstring・コメント
将来変更が予想される部分	コメントに TODO: として残す

---

7. 📋 レビューチェックリスト（第三回まとめ）

🧩 責任の分離

• 1つの関数・クラスが1つのことだけを担当している
• 「〜して、〜して、〜する」と複数のことをしていない
• データ取得・加工・表示が分離されている

🔗 依存関係

• 具体的な実装ではなく「約束事（インターフェース）」に依存している
• 循環依存（AがBに依存・BがAに依存）が発生していない
• 外部サービスへの依存が適切に抽象化されている

📐 拡張性

• 新しい機能を追加するとき、既存コードをほとんど変えなくていい
• 条件分岐が増え続ける設計になっていない
• 設定値がハードコードされていない（定数・環境変数を使っている）
• 同じコードが複数の場所にコピーされていない

🤝 AIとの協働

• 設計の意思決定をADRやコメントに記録した
• AIに逆質問して設計の問題を発見した
• 将来変更が予想される部分に TODO: コメントを残した

---

8. 🎯 シリーズ総まとめ

👁️ AIコードレビューの6つの視点

回	視点	一言で言うと
第一回	✅ 動作の正しさ	実際に動かして・極端なケースも試した？
第一回	🧠 ロジックの妥当性	要件通りに動いている？条件は正しい？
第一回	📖 可読性・保守性	半年後の自分が読んでも理解できる？
第二回	⚡ パフォーマンス	N+1・二重ループ・全件取得に気をつけた？
第二回	🔒 セキュリティ	入力検証・認可・シークレット管理は大丈夫？
第三回	🏗️ 設計・アーキテクチャ	長く使えるコードになっている？

---

9. 🌟 最後に：審美眼を磨き続けよう

AIはコードを「速く・大量に」生成できます。
でも「良いコード」かどうかを判断するのは、あなた自身です。

3回にわたって学んだレビューの視点は、一度に全部できなくても構いません。

まずは 第一回のチェックリスト から始めて、慣れてきたら パフォーマンス・セキュリティ の視点を加え、最終的に 設計・アーキテクチャ まで見られるようになる。

この積み重ねが「AIコードの審美眼」を育てます💪

ステップ	目標	時期の目安
🌱 はじめの一歩	動作確認・エッジケースを必ず試す	今日から
🌿 慣れてきたら	N+1・バリデーション・マジックナンバーを見る	1〜2週間後
🌳 さらに上を目指す	責任の分離・拡張性を意識した設計レビュー	1〜2ヶ月後

AIを使いこなすエンジニアとは、
AIの出力を正しく評価・修正・改善できる人のことです。

今日からレビューの習慣を始めてみましょう🌟

💬 質問や感想があれば、コメント欄でお気軽にどうぞ!
👍 役に立ったら、いいね&ストックをお願いします!
🎓 ここまで読んでくださって、本当にありがとうございました!

---

🔗 シリーズ記事

• 【第一回】動作・ロジック・可読性の視点
• 【第二回】パフォーマンス・セキュリティの視点
• 【第三回】設計・アーキテクチャの視点（この記事）