Claude Codeで実務コードを書かせてわかった「得意・不得意」全記録｜プロンプト付き

# 効果的なリファクタリングプロンプト例
「src/utils/validation.js の全関数をリファクタしてください。

条件:
- 各関数は単一責任の原則に従う（1関数1責任）
- 共通ロジックは切り出してヘルパー関数にする
- 関数名は「動詞 + 対象」の命名規則に統一する
- JSDocコメントを全関数に追加する
- 既存のテスト（validation.test.js）が全て通ること

変更したファイルと変更内容の概要を最後に教えてください。」

// Claude Code が生成したリファクタリング結果の例
// Before: 複雑な条件が1関数に混在
function validate(data) {
  if (!data.email || !data.email.includes('@')) return false;
  if (!data.password || data.password.length < 8) return false;
  if (!data.name || data.name.trim() === '') return false;
  return true;
}

// After: Claude Code によるリファクタ結果
/**
 * メールアドレスの形式を検証する
 * @param {string} email - 検証対象のメールアドレス
 * @returns {boolean} 有効なメールアドレス形式かどうか
 */
const isValidEmail = (email) => {
  if (!email) return false;
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
};

/**
 * パスワードの強度を検証する
 * @param {string} password - 検証対象のパスワード
 * @returns {boolean} パスワードが要件を満たすかどうか
 */
const isValidPassword = (password) => {
  if (!password) return false;
  return password.length >= 8;
};

/**
 * ユーザー名の有効性を検証する
 * @param {string} name - 検証対象のユーザー名
 * @returns {boolean} 有効なユーザー名かどうか
 */
const isValidName = (name) => {
  if (!name) return false;
  return name.trim().length > 0;
};

/**
 * ユーザー登録フォームのバリデーション
 * @param {Object} data - 検証対象のデータ
 * @returns {boolean} 全フィールドが有効かどうか
 */
const validateUserRegistration = (data) => {
  return isValidEmail(data.email) &&
         isValidPassword(data.password) &&
         isValidName(data.name);
};

# テスト生成プロンプト例
「src/utils/date.ts のユニットテストを書いてください。

使用フレームワーク: Jest + TypeScript
対象ファイル: src/utils/date.ts（既に存在します）

テストの方針:
- 正常系・異常系・境界値をカバーする
- describe でカテゴリを分ける
- 各テストケースに日本語のコメントで何をテストしているか書く
- モックが必要な場合は jest.mock() を使う

出力先: src/utils/date.test.ts」

// Claude Code が生成したテストの例
import { formatDate, parseDate, isValidDate, getDaysBetween } from './date';

describe('formatDate', () => {
  test('Dateオブジェクトを YYYY-MM-DD 形式にフォーマットする', () => {
    const date = new Date('2026-07-10T00:00:00Z');
    expect(formatDate(date)).toBe('2026-07-10');
  });

  test('月・日が1桁の場合に0埋めされる', () => {
    const date = new Date('2026-01-05T00:00:00Z');
    expect(formatDate(date)).toBe('2026-01-05');
  });

  test('null を渡した場合は空文字を返す', () => {
    expect(formatDate(null)).toBe('');
  });
});

describe('isValidDate', () => {
  test('有効な日付文字列でtrueを返す', () => {
    expect(isValidDate('2026-07-10')).toBe(true);
  });

  test('存在しない日付（2月30日）でfalseを返す', () => {
    expect(isValidDate('2026-02-30')).toBe(false);
  });

  test('空文字でfalseを返す', () => {
    expect(isValidDate('')).toBe(false);
  });
});

describe('getDaysBetween', () => {
  test('2日間の差を正しく計算する', () => {
    const from = new Date('2026-07-01');
    const to = new Date('2026-07-03');
    expect(getDaysBetween(from, to)).toBe(2);
  });

  test('同じ日付の差は0を返す', () => {
    const date = new Date('2026-07-10');
    expect(getDaysBetween(date, date)).toBe(0);
  });
});

# 型定義追加プロンプト例
「src/api/users.js の TypeScript 化を行ってください。

手順:
1. .js を .ts にリネーム
2. 全関数の引数・戻り値に型を付ける
3. any は使わない
4. API レスポンスの型は src/types/api.ts に定義する（新規作成）
5. 既存のインポートを壊さない

特に注意: getUserById の戻り値は User | null 型にすること」

# JSDoc 生成プロンプト例
「src/services/ ディレクトリ内の全ファイルに
 JSDocコメントを追加してください。

追加するコメントの要件:
- @param: 各引数の型・説明
- @returns: 戻り値の型・説明
- @throws: エラーをスローする条件
- @example: 使用例（各関数に1つ以上）

既存のコメントは上書きせずに補完する形で追加してください。」

# バグ修正プロンプト例
「以下のエラーが本番で発生しています。修正してください。

エラーメッセージ:
TypeError: Cannot read properties of undefined (reading 'name')
    at UserCard (/src/components/UserCard.tsx:23:30)
    at renderWithHooks
    ...

発生条件: ユーザーがログアウト後にダッシュボードにアクセスしたとき

確認済みのこと: user オブジェクトがログアウト後に undefined になる

修正の方針: オプショナルチェーン（?.）でガードするか、
user が undefined の場合に早期returnするかで判断してください。」

# 曖昧なプロンプト（非推奨）
「ダッシュボードをもっとよくして」
→ 何をどう変えるか不明のため、当たり障りのない修正しか得られない

# 具体的なプロンプト（推奨）
「ダッシュボードの以下を修正してください:
1. KPIカードを横並び3列に変更（現在は縦積み）
2. 各カードに前月比の変化率（%）を追加
3. 変化率がマイナスの場合は赤字、プラスの場合は緑字
4. レスポンシブ: 768px以下では1列に変更
使用スタックは既存の Tailwind CSS を使ってください。」

# 外部API実装時の推奨プロンプトパターン
「以下のAPIドキュメントを参考に実装してください。
ドキュメントの内容を最優先にし、学習データより新しい場合は
ドキュメントの仕様に従ってください。

--- APIドキュメント ---
POST /v2/payment_intents

Request body:
  amount: integer (required) - Amount in smallest currency unit
  currency: string (required) - Three-letter ISO currency code
  payment_method_types: array - ['card', 'bank_transfer']
  metadata: object - Set of key-value pairs

Response:
  id: string
  status: 'requires_payment_method' | 'succeeded' | 'canceled'
---

実装タスク: カード決済の intent を作成し、
3D Secure が必要な場合のハンドリングも追加してください。」

# テンプレート
「[対象ファイル/ディレクトリ] の [処理内容] を行ってください。

条件:
- 条件1
- 条件2
- 条件3

完了条件:
- 既存のテストが全て通ること
- 変更したファイルの一覧を報告すること
- [追加の確認事項]」

# 実際の使用例
「src/hooks/ 内の全カスタムフックをリファクタしてください。

条件:
- TypeScript の型を全て明示する（any禁止）
- useEffect の依存配列を正確に記述する
- 各フックに JSDoc コメントを追加する

完了条件:
- yarn test が全てパスすること
- 変更したファイルと変更内容の要約を最後に教えること」

# 禁止事項を明示したプロンプト例
「src/components/Modal.tsx に アニメーションを追加してください。

追加するアニメーション:
- 開くとき: 下からフェードイン（0.3秒）
- 閉じるとき: 上にフェードアウト（0.2秒）

禁止事項:
- framer-motion や他のアニメーションライブラリを追加しない
- CSS Modules は使わない（Tailwind CSS のみ使用）
- Modal.test.tsx は変更しない
- Modal.tsx 以外のファイルは変更しない」

# 段階的確認プロンプトの例
「データベースのマイグレーションを行います。
まずファイルの変更点だけを教えてください（まだ変更しないでください）。

変更内容:
- users テーブルに profile_image_url カラム（VARCHAR(500)）を追加
- posts テーブルに view_count カラム（INT DEFAULT 0）を追加
- マイグレーションファイルを migrations/ に作成

確認できたら「実行してください」と言います。」

# 続けて確認後に実行
「わかりました。実行してください。
ただし、マイグレーションの実行はしないでください。
ファイルを作成するだけで止めてください。」

# ロール指定プロンプト例
「セキュリティエンジニアとして、以下のAPIエンドポイントを
 セキュリティ観点でレビューしてください。

特に以下の観点でチェックしてください:
- SQLインジェクション
- XSSの可能性
- 認証・認可の抜け穴
- レート制限の欠如
- センシティブな情報の露出

```javascript
app.post('/api/login', async (req, res) => {
  const { email, password } = req.body;
  const user = await db.query(
    `SELECT * FROM users WHERE email = '${email}'`
  );
  if (user && user.password === password) {
    res.json({ token: generateToken(user.id) });
  }
});
```

問題点を指摘し、修正コードも提示してください。」

# CLAUDE.md の推奨記載内容
# プロジェクト概要
Reactを使ったECサイトのフロントエンド。

# 技術スタック
- React 19 + TypeScript
- Tailwind CSS（CSS Modulesは使わない）
- React Query（SWRは使わない）
- Zod（yupは使わない）
- Vitest（Jestは使わない）

# コーディング規約
- 関数コンポーネントのみ（クラスコンポーネント禁止）
- any型禁止
- console.logをコミットに含めない
- コメントは日本語で書く

# ディレクトリ構成
src/
  components/  # 再利用可能なコンポーネント
  pages/       # ページコンポーネント
  hooks/       # カスタムフック
  types/       # 型定義

# テスト通過を担保するプロンプト例
「src/utils/price.ts に税込価格計算関数を追加してください。

関数仕様:
- 関数名: calcPriceWithTax
- 引数: price: number (税抜価格), taxRate: number (税率、例: 0.1)
- 戻り値: number（小数点以下は切り捨て）

完了条件:
- yarn test で全テストがパスすること
- 追加した関数の単体テストも src/utils/price.test.ts に追加すること
- console.log は残さないこと」

# パッケージ追加を防ぐプロンプト
「日付のフォーマット関数を実装してください。

仕様: Date → "YYYY年MM月DD日" 形式の文字列に変換

制約:
- 新しいnpmパッケージは追加しない
- ネイティブのDateオブジェクトAPIのみ使用する
- date-fns, moment, dayjs 等のライブラリは使わない」

# 大規模タスクの分割例
# 一度に全部依頼（避けるべき）
「プロジェクト全体を TypeScript に移行して」

# 分割して依頼（推奨）
# ステップ1
「まず src/utils/ 配下の .js を .ts にして型付けして」
# 完了確認後

# ステップ2
「次に src/hooks/ 配下を TypeScript 化して」
# 完了確認後

# ステップ3
「src/components/ 配下を TypeScript 化して」

# CLAUDE.md の効果的な構成テンプレート
# このプロジェクトについて
[プロジェクトの概要を2〜3行で]

# 技術スタック（バージョン含む）
- [フレームワーク＋バージョン]
- [状態管理ライブラリ]
- [テストフレームワーク]

# コーディング規約
- [命名規則]
- [禁止事項]
- [コメントの言語]

# よく使うコマンド
- テスト実行: [コマンド]
- ビルド: [コマンド]
- リント: [コマンド]

# 重要な注意事項
- [触ってほしくないファイル/ディレクトリ]
- [APIキー等の取り扱い]

# .claudeignore の推奨設定
# ビルド成果物
dist/
build/
.next/
out/

# 依存パッケージ（大量のファイルがありノイズになる）
node_modules/

# 圧縮・マップファイル
*.min.js
*.min.css
*.map

# ログ・一時ファイル
*.log
.DS_Store
coverage/

# 大きなアセット
*.png
*.jpg
*.mp4
*.zip

# 会話をコンパクト化する
/compact

# コンパクト化後の推奨メッセージ
「ここまでの作業: src/middleware/auth.js に JWT 認証を追加しました。
次のタスク: src/routes/admin.js にロールベースのアクセス制御を追加してください。
ロール: admin, editor, viewer の3種類。
admin のみ DELETE メソッドを許可。」

# プロンプト例
「src/hooks/useLocalStorage.ts を新規作成してください。

仕様:
- ローカルストレージを React state のように扱えるフック
- 型パラメータで保存する値の型を指定できる（ジェネリクス）
- 初期値を引数で受け取る
- JSON.stringify / JSON.parse でシリアライズ
- ストレージが利用できない場合はメモリ上のみで動作（SSR対応）
- Vitest でのユニットテストも src/hooks/useLocalStorage.test.ts に作成

TypeScript の型は厳格に。any 禁止。」

// Claude Code が生成した useLocalStorage.ts
import { useState, useEffect, useCallback } from 'react';

type SetValue<T> = (value: T | ((prev: T) => T)) => void;

function useLocalStorage<T>(key: string, initialValue: T): [T, SetValue<T>] {
  const [storedValue, setStoredValue] = useState<T>(() => {
    if (typeof window === 'undefined') {
      return initialValue;
    }
    try {
      const item = window.localStorage.getItem(key);
      return item ? (JSON.parse(item) as T) : initialValue;
    } catch (error) {
      console.warn(`useLocalStorage: key "${key}" の読み込みに失敗`, error);
      return initialValue;
    }
  });

  const setValue: SetValue<T> = useCallback(
    (value) => {
      try {
        const valueToStore =
          value instanceof Function ? value(storedValue) : value;
        setStoredValue(valueToStore);
        if (typeof window !== 'undefined') {
          window.localStorage.setItem(key, JSON.stringify(valueToStore));
        }
      } catch (error) {
        console.warn(`useLocalStorage: key "${key}" の書き込みに失敗`, error);
      }
    },
    [key, storedValue]
  );

  useEffect(() => {
    const handleStorageChange = (e: StorageEvent) => {
      if (e.key === key && e.newValue !== null) {
        setStoredValue(JSON.parse(e.newValue) as T);
      }
    };
    window.addEventListener('storage', handleStorageChange);
    return () => window.removeEventListener('storage', handleStorageChange);
  }, [key]);

  return [storedValue, setValue];
}

export default useLocalStorage;

# プロンプト例
「src/routes/api.ts の全 POST/PUT エンドポイントに
 zod を使ったリクエストバリデーションを追加してください。

バリデーション失敗時: 400 を返し、{ errors: ZodError[] } 形式で詳細を返す
共通ミドルウェアとして切り出す（各ルートに直接書かない）
zod は既にインストール済み（package.json 参照）
既存テストが全て通ること（yarn test で確認）」

// 生成されたバリデーションミドルウェア
import { Request, Response, NextFunction } from 'express';
import { ZodSchema, ZodError } from 'zod';

export function validate<T>(schema: ZodSchema<T>) {
  return (req: Request, res: Response, next: NextFunction): void => {
    const result = schema.safeParse(req.body);
    if (!result.success) {
      res.status(400).json({
        errors: result.error.errors.map((e) => ({
          field: e.path.join('.'),
          message: e.message,
          code: e.code,
        })),
      });
      return;
    }
    req.body = result.data;
    next();
  };
}

// 各ルートへの適用例（Claude Code が自動で追加）
const createUserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  password: z.string().min(8),
});

router.post('/users', validate(createUserSchema), createUserHandler);

# プロンプト例
「scripts/process_data.py をリファクタしてください。

現状の問題:
- 1つの main() 関数に全処理が詰め込まれている（300行）
- グローバル変数を多用している
- エラーハンドリングがない
- ログ出力がない

修正方針:
- 責任ごとに関数に分割する
- グローバル変数を排除し、関数の引数/戻り値で渡す
- try/except でエラーハンドリングを追加する
- logging モジュールで INFO/ERROR レベルのログを追加する
- 型アノテーションを追加する（Python 3.10+）

既存の出力結果（output.csv）が変わらないこと。」

# プロンプト例
「以下のSQLクエリが遅いです（実行時間: 約3秒）。
EXPLAINの結果と合わせて最適化してください。

-- 現在のクエリ
SELECT u.name, COUNT(p.id) AS post_count, MAX(p.created_at) AS last_post
FROM users u
LEFT JOIN posts p ON p.user_id = u.id
WHERE u.created_at >= '2025-01-01'
GROUP BY u.id, u.name
HAVING COUNT(p.id) > 0
ORDER BY last_post DESC
LIMIT 50;

-- EXPLAIN 結果（抜粋）
type: ALL (full table scan on users)
rows: 84,201
Extra: Using filesort

最適化の方針:
1. 適切なインデックスを提案する（ALTER TABLE 文で）
2. クエリ自体の書き換えが有効なら修正する
3. 期待される改善効果を説明する」

-- Claude Code の最適化提案

-- 1. インデックスの追加
ALTER TABLE users ADD INDEX idx_users_created_at (created_at);
ALTER TABLE posts ADD INDEX idx_posts_user_created (user_id, created_at);

-- 2. クエリの最適化（サブクエリで絞り込み先行）
SELECT u.name, p.post_count, p.last_post
FROM users u
INNER JOIN (
  SELECT user_id,
         COUNT(id) AS post_count,
         MAX(created_at) AS last_post
  FROM posts
  GROUP BY user_id
  HAVING COUNT(id) > 0
) p ON p.user_id = u.id
WHERE u.created_at >= '2025-01-01'
ORDER BY p.last_post DESC
LIMIT 50;

-- 期待効果: full scan → range scan
-- EXPLAIN type: ALL → range (created_at インデックス利用)
-- 実行時間目安: 3秒 → 0.1〜0.3秒

# ~/.zshrc や ~/.bashrc に追加するエイリアス例
alias cc='claude'
alias ccr='claude "$(cat << EOF
以下のタスクを実行してください。
このプロジェクトは React + TypeScript + Tailwind CSS です。
any 型は使わない。テストは Vitest を使う。

EOF
)"'

# 特定プロジェクトへのクイック移動
alias myapp='cd ~/projects/myapp && claude'

# よく使うタスクのショートカット
alias cc-test='claude "既存のテストが全て通ることを確認して"'
alias cc-lint='claude "ESLint と TypeScript エラーを全て修正して"'

# git diff をClaude Codeに渡してレビューさせる
git diff main...HEAD > /tmp/my_diff.txt
claude "$(cat << EOF
以下のコード差分をレビューしてください。

観点:
1. バグ・ロジックエラーがないか
2. セキュリティ上の問題（XSS, SQLインジェクション等）がないか
3. パフォーマンス上の問題がないか
4. 可読性・保守性の改善点はないか
5. テストが必要なのにないケースはないか

--- 差分 ---
$(cat /tmp/my_diff.txt)
---

問題点があれば修正コードも提示してください。
EOF
)"