新機能を一から実装するワークフロー

このワークフローが有効な場面

• Issueやチケットがあるが、どこから手をつけるか悩んでいるとき
• 設計から実装まで一気に進めたいとき
• 独力では設計に自信がないとき
• 新しいAPIやライブラリを使う機能で調べながら実装したいとき

※API: Application Programming Interface の略。外部サービスとプログラム間でデータをやりとりするための接続口。

ステップバイステップの手順

ステップ1: 要件をClaudeに整理させる

実装を始める前に、要件を整理します。

プロンプト例:

「以下の機能を実装したいです。実装前に要件を整理してください。

機能: ユーザーがメールアドレスを変更できる機能

要件として考えていること:
- 現在のメールアドレスを表示する
- 新しいメールアドレスを入力
- 確認メールを送信（変更前のアドレスに通知、新しいアドレスで確認）
- 確認リンクをクリックで変更完了

確認してほしいこと:
1. 要件の抜け漏れがないか
2. セキュリティ上の考慮事項
3. このプロジェクトの技術スタック（Next.js + Supabase）での実現方法」

ステップ2: 実装設計を作らせる

要件が固まったら、具体的な実装設計を作ります。

プロンプト例:

「要件が固まりました。実装設計を作ってください。

以下の形式で出力してください:
1. 作成・変更するファイルの一覧
2. データベースの変更（必要な場合）
3. APIエンドポイントの設計
4. コンポーネント設計
5. 実装の順序（何から始めるか）

コードはまだ書かなくていいです。設計だけ確認したい。」

ステップ3: 設計を確認・承認する

Claudeの設計案を人間がレビューします。

「設計を確認しました。以下の変更を加えてください:
- トークンの有効期限を24時間から72時間に変更
- メール送信はすでに `lib/email.ts` の `sendEmail()` 関数があるので使うこと
- UI は既存の `components/forms/` のスタイルに合わせること

この修正を反映した上で、実装を始めてください。
まずデータベースのマイグレーションから。」

ステップ4: 段階的に実装する

一度に全部を実装させるのではなく、レイヤーごとに進めます。

フェーズ1: データ層

「ではマイグレーションを作成してください。
email_change_requests テーブルを新規作成:
- id (uuid)
- user_id (外部キー)
- new_email
- token（確認用トークン）
- expires_at
- confirmed_at（null = 未確認）」

フェーズ2: APIロジック

「マイグレーション完了しました。
次は Server Actions を作成してください:
- requestEmailChange(newEmail: string)
- confirmEmailChange(token: string)
テストは後で書くので、今は実装だけ。」

フェーズ3: UI

「バックエンドの実装が完了しました。
次はUIを作成してください。
ファイル: app/(app)/settings/email/page.tsx
既存の設定画面のスタイル（settings/profile/page.tsx）に合わせてください。」

ステップ5: テストを書かせる

実装が完了したらテストを追加します。

プロンプト例:

「実装が完了しました。テストを書いてください。

対象:
1. requestEmailChange - 正常系・メール形式エラー・すでに使用中メール
2. confirmEmailChange - 正常系・無効トークン・期限切れトークン

使用するテストフレームワーク: Vitest
テストファイルの場所: __tests__/actions/email-change.test.ts」

ステップ6: ドキュメントとPRを作る

プロンプト例:

「実装とテストが完了しました。
GitHubのPRを作成するための説明文を書いてください。

含めてほしい内容:
- 変更内容のサマリー
- 動作確認の手順（レビュアーが試せるように）
- スクリーンショットの場所（UIの変更があるため）
- 影響範囲」

※マイグレーション: データベースのスキーマ（テーブル構造）を安全に変更するための手順書。※エンドポイント: APIにアクセスするためのURL。例: `/api/users` や `/api/posts/123` など。※プロンプト: AIへの指示文。Claude Codeへの指示の質がそのまま出力の質に影響する。※トークン: AIがテキストを処理する最小単位。日本語は1文字あたり約1〜2トークン。使用量に応じてAPIコストが変わる。

注意点・よくある失敗

失敗1: 最初から全部実装させようとする

「ユーザーのメールアドレス変更機能を全部実装して」という依頼は、多くの場合、コンテキストが足りなかったり、設計の方向性がずれたりします。ステップ1〜2の設計確認を必ず挟みましょう。

失敗2: 設計の確認をスキップする

ステップ2をスキップして実装に入ると、後から「テーブル設計を変えたい」となったときのやり直しが大きくなります。

失敗3: テストを「後回し」にして忘れる

「テストは後で」はほぼ必ず忘れます。実装ステップの中にテスト作成ステップを組み込んでください。

※コンテキスト: Claudeが一度に記憶・参照できる会話・コードの範囲。上限を超えると古い情報が失われる。

実際の作業例（短い会話例）

私: ユーザーがプロフィール画像をアップロードできる機能を実装したい。Cloudflare R2に保存する。要件の整理から始めて。

Claude: `要件を整理します。

現在確認できていること:

• 画像のアップロード先: Cloudflare R2
• 既存のユーザープロフィール画面があるか: 確認が必要

追加で確認したい点:

1. 画像サイズの制限はありますか？（推奨: 5MB以下）
2. 対応フォーマットは？（JPEG/PNG/WebPなど）
3. 古い画像は削除しますか？それとも履歴を残しますか？
4. 画像の表示サイズ（サムネイル生成が必要か）

確認事項に回答いただければ、実装設計に進みます。`

私: サイズ上限5MB、JPEG/PNG/WebP対応、古い画像は削除、サムネイルは不要。

Claude: 了解しました。実装設計を作成します。...（設計案を提示）

Tip

「要件整理 → 設計確認 → 段階的実装 → テスト」のサイクルを守るだけで、やり直しが大幅に減ります。特に「設計確認」を人間がしっかり行うことが品質のカギです。