はじめに

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

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

AIツールを実案件に適用する際に事前に知っておくべき実践的なTipsのシリーズ第3回目。今回のテーマは「【AI駆動開発】Cursor@ファイル指定でハードコーディングの定数化リファクタリング」です。

※本記事の内容は「AI駆動開発実践コース」での知見をもとにしています

前回までの振り返りと課題

前回までで、AIツールのAgentモードで実装したコードには、7つの特徴があることが分かりました。そのうち、以下の表の④～⑦のような、改善すべき点があることも分かりました。

一方で、実際にAIツールに対してどのような指示を出せば意図したとおりの修正を行わせることができるのかが不明確でした。

今回からは、実案件で使用したAIへの指示プロンプトと、AIが生成したコードの実例を元に、AIに意図したとおりの修正を行わせるうえでのポイントを押さえていきます。

今回は、エラー処理を題材に、AIにコードのリファクタリングを実施させるうえでのポイントを押さえていきます。

補足： 本記事で紹介するプロンプトとコードは、実案件で実際に適用したタスクと同一の内容ですが、機密保持の観点から実際のプロンプトやコードを模した形で再構成しています（※）。ただし、AIツールへの指示方法や修正アプローチの本質的な部分は実案件での実体験に基づいています。
※技術スタックは、React（TypeScript）、Express（TypeScript）、Drizzle ORM、PostgreSQLを使用。

AIが実装したエラー処理の問題点

まず、AIが実装したエラー処理にはいくつかの問題があります。実際のコードを見ながら確認していきましょう。

問題点1：エラーコードのハードコーディング

// 複数ファイルでエラーコードを直接記述
if (error.message === "SERVER_ERROR") {
  // 処理
}

if (error.message === "NOTFOUND_ERROR") {
  // 処理
}

なぜ問題なのか：

エラーコードの表記ミスが発生しやすい
エラーコードを変更する際に、変更箇所が複数に分散する
どのようなエラーコードが存在するのか把握しづらい

問題点2：エラー処理の重複

// 各コンポーネントで以下のエラー処理が重複
if (error instanceof Error) {
  if (error.message === "NOTFOUND_ERROR") {
    description = "対象のタスクが見つかりません。一覧を更新して最新情報をご確認ください。";
  } else if (error.message === "SERVER_ERROR") {
    description = "サーバーエラーが発生しました。しばらく経ってから再試行してください。";
  } else {
    description = "タスクの削除に失敗しました。ネットワーク接続を確認して再試行してください。";
  }
}

なぜ問題なのか：

コードの重複が発生している
新しいエラーコードへの対応を追加する際に修正漏れのリスクがある
エラーメッセージの変更が必要な場合、複数箇所の修正が必要になる

AIツールへの効果的な指示方法

この例において、AIツールに対してどのような指示を出せば、意図した通りの修正を行わせることができるのでしょうか？

ポイントは大きく2つあります：

タスクを細分化すること
ファイル名を指定して明確な指示を出すこと

①タスクの細分化

今回の例でいうと：

大きなタスク： エラー処理改善
- サブタスク1： エラーコードの定数化
- サブタスク2： エラー処理の共通化

このように分割することで：

AIのアウトプットを確認する単位が小さくなり、コードレビューの負担が軽減される
AIのアウトプットをこまめに確認することで手戻りが減る
各タスクの目的と範囲が明確になり、AIの正確な理解と実装が期待できる

②ファイル名を指定した明確な指示

サブタスク1：エラーコードの定数化

多くのAIツールでは@マークを使ったファイル指定機能が利用でき、修正対象のファイル名を指定して明確な修正指示を出すことができます。

指示例：

@client/src/lib/api.ts
@client/src/components/task-list.tsx
@client/src/components/task-dialog.tsx
@client/src/components/task-card.tsx

これらのファイルでハードコーディングされているエラーコード（NOTFOUND_ERROR, SERVER_ERROR, OTHER_ERROR）を定数化してください。
定数オブジェクトは@client/src/lib/error-utils.tsに作成し、各ファイルからそれを参照するよう修正してください。

ポイント：
@マークによるファイル指定は既存ファイルの参照と新規ファイルの作成の両方に使用できます。この指示では：

既存4ファイル： ハードコーディングされたエラーコードの抽出元として参照
新規ファイル（error-utils.ts）： 定数定義の作成先として指定

修正結果：

// 修正前
if (error.message === "SERVER_ERROR") { // ハードコーディング

// 修正後  
import { ERROR_CODES } from "@/lib/error-utils";
if (error.message === ERROR_CODES.SERVER_ERROR) { // 定数化

効果：

エラーコードが一箇所で管理されるようになり、変更が容易になった
タイプミスによるバグの可能性が減少した
TypeScriptの型システムによる補完やエラーチェックが効くようになった

サブタスク2：エラー処理の共通化

先ほどと同様に、具体的なファイル名を指定して指示します。

指示例：

@client/src/components/task-list.tsx
@client/src/components/task-dialog.tsx
@client/src/components/task-card.tsx

これらのファイルのエラー処理ロジック（エラーコードに応じたメッセージ設定）を@client/src/lib/error-utils.tsに共通関数化し、
各ファイルから共通関数を呼び出すよう修正してください。

修正結果：

// 修正前
} catch (error) {
  let title = "エラーが発生しました";
  let description: string;
  
  if (error instanceof Error) { // 重複したエラー処理
    if (error.message === ERROR_CODES.NOTFOUND_ERROR) {
      description = "対象のタスクが見つかりません。一覧を更新して最新情報をご確認ください。";
    } else if (error.message === ERROR_CODES.SERVER_ERROR) {
      description = "サーバーエラーが発生しました。しばらく経ってから再試行してください。";
    } else {
      description = "タスクの保存に失敗しました。ネットワーク接続を確認して再試行してください。";
    }
  }
  // ...
}

// 修正後
} catch (error) {
  const { title, description } = getErrorMessage(error, "タスクの保存"); // 共通関数化
  // ...
}

効果：

コードの重複が削減され、メンテナンス性が向上
エラーメッセージの変更やエラーコードの追加が1箇所で済むように
各コンポーネントのコードがシンプルになり、可読性が向上

課題と今後の展開

残された課題

AIツールへの指示のポイントと実際のコードは分かりましたが、今回はリファクタリングの事例のみを扱いました。

実際にAIツールを実務で活用する際には、バグ修正にも頻繁に使用します。その場合、具体的にどのように指示すれば良いのでしょうか？今回紹介した手法で意図した通りの修正を行わせることは可能なのでしょうか？

手法の汎用性について、さらなる検証が必要です。

次回予告

次回は、今回の手法がバグ修正においても有効なのかを実際のコード例とともに検証します。

まとめ

今回は以下の2つのポイントを中心に、AIツールへの効果的な指示方法をご紹介しました：

タスクの細分化 - 大きなタスクを小さな単位に分割することで、AIの理解精度と実装品質が向上
ファイル名指定 - @マークを活用した明確な修正対象の指定により、意図した修正が実現

これらの手法により、AIツールをより実践的に活用できるようになります。エラー処理の共通化という具体的なリファクタリング事例を通じて、AIツールへの効果的な指示方法を実践的に学ぶことができました。

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