大規模PJでAI駆動開発。Cursor Agentの品質とは？

はじめに

こんにちは。エンジニア 兼 講師のShotaです。

普段はエンジニアとしてAIツールを実案件に適用しながら開発を行い、同時に講師として得られた知見を体系化して受講生の方にお伝えする活動をしています。

AIツールを実案件に適用する際に事前に知っておくべき実践的なTipsのシリーズ第2回目。今回のテーマは「Agentモードの品質とは？」です。

前回解説した、新規開発に利用するAIツールのAgentモード。「〇〇アプリ作ってみた」という紹介記事は数多くありますが、実際に出力されるコードの品質を詳しく分析した事例はまだ少ないのが現状です。

AIツールは個人開発や小規模PJでの利用に加えて、大企業における全社導入や大規模PJへの適用も徐々に進み始めています。

そこで気になるのが品質です。Agentモードで実装させたコードを詳しく分析してみると、いくつかの特徴が見えてきました。

これらを「Agent実装コードの7つの特徴」として整理し、以下の技術スタックでAgentに実装させた実際のコードを基に解説していきます。

技術スタック：

フロントエンド：React (TypeScript)

バックエンド：Express (TypeScript)

ORM：Drizzle ORM

Agent実装コード7つの特徴

7つの特徴は以下の表の通りです。それぞれ見ていきましょう。

特徴	評価
① 一貫性のある実装パターン	🟢 良好
② 共通処理のコンポーネント化	🟢 良好
③ 型チェックの積極的活用	🟢 良好
④ 少ないコメント	🟡 要改善
⑤ 一部の一貫性のない実装パターン / 冗長処理	🟡 要改善
⑥ 簡略化されたエラー処理	🟡 要改善
⑦ 未使用コンポーネントの先行実装	🟡 要判断

🟢 活かすべきポイント

① 一貫性のある実装パターン

APIの実装で統一されたパターンを採用しています。

具体例：

• APIの命名規則：全てのエンドポイントで /api/tasks という統一されたパスを使用

• データベース操作の書き方：全てのエンドポイントで db.select().from(tasks) や db.update(tasks).set(...) など、Drizzle ORMの機能を使って同じルールで実装

// Create操作
app.post("/api/tasks", async (req, res) => {
  // db.insert(tasks).values(...) というDrizzle ORMのパターン
  const newTask = await db.insert(tasks).values({
    title: req.body.title,
    description: req.body.description,
    status: req.body.status
  }).returning();
});

// Update操作  
app.put("/api/tasks/:id", async (req, res) => {
  // db.update(tasks).set(...) というDrizzle ORMのパターン
  const updatedTask = await db.update(tasks)
    .set({ title: req.body.title })
    .where(eq(tasks.id, parseInt(req.params.id)))
    .returning();
});

活かすべき理由： 同じパターンの繰り返しにより、新しいメンバーがコードを理解しやすく、メンテナンス時の作業効率が向上するため。

② 共通処理のコンポーネント化

アプリ全体で一貫したUIを提供する共通コンポーネントが適切に実装されています。

具体例：通知処理の共通化 use-toast.tsx に定義された toast 関数が、タスク作成、タスク削除など複数の機能で同じように使われています。

// タスク作成時の通知
const onSubmit = async (values: FormValues) => {
  try {
    if (mode === "create") {
      await createTask(values);
      toast({
        title: "タスクを作成しました",
      });
    }
  } catch (error) {
    toast({
      title: "エラーが発生しました",
      description: "タスクの保存に失敗しました",
      variant: "destructive",
    });
  }
};

// タスク削除時も同じtoast関数を使用
const handleDelete = async () => {
  try {
    await deleteTask(task.id);
    toast({
      title: "タスクを削除しました",
    });
  } catch (error) {
    toast({
      title: "エラーが発生しました",
      description: "タスクの削除に失敗しました",
      variant: "destructive",
    });
  }
};

活かすべき理由： 同じ機能を何度も実装する必要がなく、UIの一貫性も保たれることで開発効率と品質の両方が向上するため。

③ 型チェックの積極的活用

TypeScriptの型定義を活用して、実行時の予期せぬ動作を未然に防いでいます。

interface TaskDialogProps {
  open: boolean;  // trueまたはfalseのみ
  onOpenChange: (open: boolean) => void;  // booleanを引数に取る関数のみ
  mode: "create" | "edit";  // "create"または"edit"の文字列のみ
  task?: SelectTask;  // 省略可能なタスクオブジェクト
}

活かすべき理由： コードを書く時点で誤った値の設定を防ぐことができ、バグの早期発見とコード品質の向上に直結するため。

これらの実践は、それぞれ以下の効果をもたらします：

• ①一貫性のある実装パターン → 保守性向上
• ②共通処理のコンポーネント化 → 生産性向上
• ③型チェックの積極的活用 → 品質確保

🟡 改善を検討すべきポイント

④ 少ないコメント

コードの理解しにくさによる保守性低下のリスクがあります。

具体例：コメントが不足している実装

interface TaskDialogProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  mode: "create" | "edit";
  task?: SelectTask;
}

改善例：適切なコメント追加

interface TaskDialogProps {
  /** ダイアログの表示状態 */
  open: boolean;
  /** 表示状態変更時の処理 */
  onOpenChange: (open: boolean) => void;
  /** ダイアログのモード（作成または編集） */
  mode: "create" | "edit";
  /** 編集時に渡されるタスクオブジェクト */
  task?: SelectTask;
}

改善すべき理由： 小規模チームでは問題なくても、チーム拡大時やメンバー変更時にコード理解コストが増大し、メンテナンス効率が低下するため。

⑤ 一部の一貫性のない実装パターン / 冗長処理

メンテナンス性の観点から改善の余地があります。

具体例1：API呼び出しの実装場所の不統一

• タスクの作成・更新・削除：api.tsに実装
• タスクの取得（Read処理）：task-list.tsxに実装

具体例2：冗長処理

app.use((err: any, _req: Request, res: Response, _next: NextFunction) => {
    res.status(status).json({ message });
    throw err; // この例外スローは不要（既にレスポンス済みなのに再スロー）
});

改善すべき理由： 実装場所がバラバラだと修正時に複数ファイルを確認する必要があり、冗長処理はアプリケーションの不安定化リスクがあるため。

⑥ 簡略化されたエラー処理

ユーザー体験価値低下と運用効率低下のリスクがあります。

具体例：簡略化されたエラーハンドリング

// api.ts - 問題：「!res.ok」だけの単純な判定
if (!res.ok) {
  throw new Error("Failed to create task"); 
}

// task-dialog.tsx - 問題：汎用的すぎるメッセージ
} catch (error) {
  toast({
    title: "エラーが発生しました",
    description: "タスクの保存に失敗しました", // 何が原因か分からない
    variant: "destructive",
  });
}

改善例：具体的なステータスコードに応じた分岐 !res.ok という単純な判定ではなく、ステータスコード（400、500など）に応じて具体的なエラー種別を判定し、それぞれに対応した分かりやすいエラーメッセージを表示する。例えば「入力内容に不備があります」「ネットワーク接続を確認してください」「サーバーエラーが発生しました」など、ユーザーが次に取るべきアクションが明確になるメッセージに改善する。

改善すべき理由： エラーの原因が分からないとユーザーが適切な対処ができず、運用時の問題特定も困難になるため。

⑦ 未使用コンポーネントの先行実装

現時点で使われていないUIコンポーネントが多数実装されています。

具体例：使用されていないUIコンポーネント

src/components/ui/
├── alert.tsx          # 現在未使用
├── avatar.tsx         # 現在未使用  
├── badge.tsx          # 現在未使用
├── card.tsx           # 現在未使用
├── checkbox.tsx       # 現在未使用
└── ...（他にも多数の未使用コンポーネント）

判断基準：

• 活かすべき： 「将来の機能拡張に備えた共通UIコンポーネント準備」という方針がチーム内で明確に共有されている場合
• 改善すべき： コード理解が複雑になり、保守性低下のリスクが高いと判断される場合

要判断の理由： チーム方針次第で評価が変わる項目で、将来の拡張性を重視するか、現在の保守性を重視するかによって判断が分かれるため。

課題

これまでAgent実装コードの7つの特徴について見てきましたが、ここで新たな課題が浮上します。改善すべき点は明確になったものの、実際にAIツールに対してどのような指示を出せば、意図したとおりの修正を行わせることができるのでしょうか。

現在、プロンプト集などのリソースは存在しますが、指示方法を体系化・パターン化して実務での適用場面に応じて使える方法論はまだ提唱されていないのが現状です。

次回予告

次回は「AI駆動開発7つのメソッドとは？」をテーマに、AI駆動開発を加速する方法論の概要と、一部詳細まで踏み込んでお話しします。

より詳しく学びたい方へ

今回の内容は「AI駆動開発実践コース」の一部を抜粋したものです。

今回のTipsはハンズオン形式の動画で詳しく解説しており、下記の赤枠部分の無料プレビュー動画でご覧いただけます。また、コースには今回紹介した以外にも多数の実践事例が含まれています：

無料プレビューでは今回のコードの品質分析を、有料版では以下のような実務で直面する具体的なケースでのコードレビュー手法と、AIを使ったコードレビュー効率化手法を学ぶことができます：

• GitHubリポジトリインポートと環境構築
• アーキテクチャとフォルダ・ファイル構成の確認
• Reactフロントエンドコードの確認
• Express + Drizzle ORMバックエンドコードの確認
• PostgreSQLデータベーステーブルと環境変数の確認
• Assistantの2つのモードと特徴
• コード理解を加速する効果的な質問方法

これらはすべて実案件で頻繁に遭遇する課題であり、AIツールを使った効率的な解決方法を実践的に習得できます。

現在、無料登録で10,000円OFFクーポンを配布中です

• 通常価格：39,800円 → 29,800円
• クーポン有効期限：8月31日（日）23:59まで

登録方法
コースページの「無料プレビュー」ボタンから無料登録が可能です。

クーポンメールについて
無料登録後、10,000円OFFクーポンが自動送信されます。現在登録者が急増しているため、配信に遅れが生じる場合があります。

• メールが届かない場合は数時間後から翌日に再確認してください
• 迷惑メールフォルダもご確認ください
• それでも届かない場合は、サポート窓口（[e-mail]）までお問い合わせください

コース詳細・無料登録はこちら

この記事が参考になりましたら、ぜひいいねをお願いします。このシリーズは不定期更新のため、最新情報をすぐに受け取りたい方はフォローしていただけると幸いです。