Claude CodeとAI支援開発ワークフロー

6ヶ月前、私はClaude Codeを主要な開発ツールとして使い始めました。ボイラープレートのために時々開くおもちゃとしてではなく、私が取り組むすべてのプロジェクトでコードの記述、デバッグ、リファクタリングを行うためのデフォルトのインターフェースとしてです。この移行は一瞬ではありませんでした — 習慣を調整し、何を委任し、何を手動で維持するかを学び、遅くなるのではなく実際にスピードアップするワークフローを構築するのに数週間かかりました。

この記事は、そのワークフローが日常の実践でどのように見えるか、どのパターンが最良の結果を生み出すか、そしてAI支援開発がまだ不十分な点を実践的に説明するものです。

環境設定

Claude Codeはターミナルで動作します。ファイルシステムに直接アクセスでき、ファイルの読み書き、シェルコマンドの実行、Gitとの対話が可能です。これは、貼り付けたコードスニペットで動作するチャットベースのAIとは根本的に異なります — Claude Codeはプロジェクト全体を把握し、ディレクトリ構造を理解し、単一の操作で複数のファイルにわたる変更を行うことができます。

これを生産的にする設定は次のとおりです。

CLAUDE.mdファイルは、あなたが書く最も重要な設定です。これらはClaude Codeが自動的に読み取る指示ファイルです — すべてのプロジェクトに適用される標準のための~/.claude/CLAUDE.mdにあるグローバルなものと、プロジェクト固有の規約のためのリポジトリルートにあるプロジェクトごとのものです。

私のグローバルCLAUDE.mdはコーディング標準を確立します：最大ファイルサイズ（〜300行）、コンポーネント抽出ルール、テスト要件、コミット規約。プロジェクトレベルのファイルは、技術スタック、アーキテクチャパターン、命名規約、およびドメイン固有のルールを指定します。これはオプションではありません — これらのファイルがなければ、Claude Codeは動作するコードを生成しますが、プロジェクトのスタイルや規約には一致しません。

MCPサーバーは、Claude Codeがアクセスできる範囲を拡張します。私はデータベースサーバー（Claudeが開発データベースに直接クエリできるように）、ファイル検索サーバー、および分析データなどのプロジェクト固有のサーバーを接続します。MCP設定はプロジェクトルートの.mcp.jsonにあります。各サーバーは、Claude CodeがModel Context Protocolを通じて通信する個別のプロセスです。

Git連携は組み込まれていますが、ガードレールが必要です。私はClaude Codeが強制プッシュをしない、要求されない限りコミットを修正しない、プリコミットフックをスキップしないように設定しています。これらは、自分でやれば簡単に元に戻せる破壊的なアクションですが、AIが気づかないうちに実行すると壊滅的です。

日常のワークフロー統合

朝のパターン

私は各コーディングセッションを、プロジェクトディレクトリでClaude Codeを開き、今日何に取り組むかについてコンテキストを与えることから始めます。詳細な仕様ではなく、取り組む機能、バグ、またはリファクタリングについて1、2文です。

「ユーザー設定ページにメール通知設定を追加しています。ユーザーは、新しいメッセージ、プロジェクトの更新、週次サマリーの通知を切り替えられるようにする必要があります。設定はデータベースに永続化され、メールサービスと同期されるべきです。」

これにより意図が確立されます。Claude Codeは、セッション内のその後のすべてのリクエストに対して、ファイルの場所、命名、アーキテクチャについてより良い決定を下すためのコンテキストを持つことになります。

コード生成パターン

最も効果的なコード生成リクエストは、何を行うかについては具体的であり、どのように行うかについては柔軟です。良いリクエストは、動作、制約、統合ポイントを記述します。悪いリクエストは、実装をステップバイステップで記述します — その時点では、自分でコードをタイプするのと変わりません。

良いリクエスト：「ユーザー設定ルーターに、通知設定を含むJSONボディを受け入れるPATCHエンドポイントを追加してください。各設定キーが許可されたタイプの一つであることを検証してください。user_settingsテーブルに永続化してください。更新された設定を返してください。」

悪いリクエスト：「reqとresを受け取り、body.preferencesを分解し、それらをループし、それぞれに対してdb.updateを呼び出し、200を返すupdateNotificationPrefsという関数を作成してください。」

最初の要求は、Claude Codeにベストプラクティスを適用する余地を与えます — プロジェクトがすでに使用している検証ライブラリを使用し、他のルートで確立されたエラー処理パターンに従い、既存のエンドポイントの応答形式に合わせます。2番目の要求は、記述された内容が理想的でなくても、記述されたとおりに正確に生成します。

マルチファイル操作

これは、Claude Codeが従来のコーディングを真に凌駕する点です。機能が複数のファイル — データベースマイグレーション、サービスレイヤー、ルートハンドラー、Reactコンポーネント、テスト — にまたがる場合、Claude Codeはそれらすべてを単一の操作で作成または変更し、それらすべてにわたる一貫性を維持できます。

「usersテーブルにnotification_preferences JSONBカラムを追加し、そのためのマイグレーションを作成し、検証付きで設定を更新するサービスメソッドを追加し、APIルーターを通じて公開し、エンドポイントを呼び出す設定ページのReactコンポーネントを作成してください。」

Claude Codeはこれらすべてのファイルを生成し、適切なモジュールをインポートし、マイグレーション、サービス、APIレイヤー全体で正しいテーブル名とカラム名を使用し、API契約に一致するフロントエンドコンポーネントを作成します。これを手動で行うことは、常にファイルを切り替え、名前を相互参照することを意味します。それがアトミックに発生することは、大幅な時間節約になります。

対話型洗練

最良の結果は、単一のリクエストではなく、反復的な会話から生まれます。私は最初の実装を生成し、レビューし、そして洗練します。

「通知設定コンポーネントは良さそうですが、楽観的更新を使用すべきです — UIをすぐに更新し、API呼び出しが失敗した場合は元に戻してください。また、最初のフェッチのためにローディング状態を追加してください。」

これは、Claude Codeが生成したばかりのものの完全なコンテキストを持っているため機能します。それは正確なコンポーネントを変更し、プロジェクトが使用する状態管理アプローチを使用して楽観的更新パターンを追加し、作成した他のすべてを保持します。

AIによるデバッグ

デバッグは、Claude Codeが最も劇的な生産性向上をもたらす分野です。従来のデバッグループは、エラーを読み、仮説を立て、ログを追加し、再現し、ログを読み、仮説を調整し、繰り返すというものです。Claude Codeはこれを圧縮します。

エラー診断

エラーが発生したとき、私はスタックトレースまたはエラーメッセージを貼り付け、「週次サマリーオプションを切り替えた後、通知設定を保存しようとするとこのエラーが発生します」と伝えます。Claude Codeは次のことができます。

1. 関連するソースファイルを読み取り、コードパスを理解する
2. スタックトレースと記述されたトリガーに基づいて潜在的な原因を特定する
3. 型ミスマッチ、nullチェックの欠落、競合状態などの一般的な問題を確認する
4. なぜそれが機能するのかの説明とともに修正を提案する

単純なバグ — awaitの欠落、間違ったプロパティ名、オフバイワンエラー — の場合、Claude Codeは私が手動で関連する行を見つけるよりも速く問題を特定し修正します。状態管理、非同期タイミング、または複数のシステム間の相互作用を含む複雑なバグの場合、正確な修正を生成しない場合でも、検索スペースを大幅に絞り込みます。

ログ分析

「これがサーバーログの最後の50行です。/api/settingsエンドポイントでAPIが断続的に500エラーを返しています。何が問題なのでしょうか？」

Claude Codeはログを読み取り、パターンを特定し（リクエストボディが特定のサイズを超えたとき、または2つのリクエストが同じリソースに同時にヒットしたときに常にエラーが発生する）、診断を提案します。その後、ボディパーサーの制限を調整したり、ミューテックスを追加したり、競合状態を修正したりして、直接修正を行うことができます。

テスト駆動デバッグ

ブラウザで簡単に再現できないバグに遭遇した場合、私はClaude Codeに、正確なシナリオを捉える失敗するテストを作成するように依頼します。

「空のオブジェクトで通知設定を保存し、次に有効な設定で再度保存するテストを書いてください。2回目の保存は最初のものを上書きするはずですが、マージされているようです。」

テストは合格するか（私の仮説を否定する）、または失敗するか（バグを確認し、再現可能なケースを提供する）のいずれかです。いずれにせよ、私は保持できるテストを持っています。

リファクタリング戦略

リファクタリングは、機械的には複雑ですが概念的には単純であるため、AI支援に最適なユースケースです。リファクタリング後にコードがどうあるべきかはわかっています — 課題は、何も壊さずにすべての変更を一貫して行うことです。

コンポーネントの抽出

「このDashboardコンポーネントは450行あります。統計パネル、アクティビティフィード、クイックアクションセクションを別々のコンポーネントに抽出してください。同じディレクトリに保持してください。すべてのpropsと状態管理を維持してください。」

Claude Codeはコンポーネントを読み取り、論理的な境界を特定し、各セクションを適切なpropsインターフェースを持つ独自のファイルに抽出し、Dashboardを更新して新しいコンポーネントを構成します。インポート、型定義、およびリフトアップまたは渡す必要がある状態を処理します。

名前変更と再構築

「プロジェクト全体でuserモジュールをaccountに名前変更してください。これには、ディレクトリ名、すべてのファイル名、すべてのインポートパス、コードベース内のすべての参照、およびクエリレイヤーのデータベーステーブルエイリアスが含まれます。」

これは退屈でエラーが発生しやすい手作業です。Claude Codeはこれを一度に実行し、見落としがちな参照を捕捉し、その後テストスイートを実行して何も壊れていないことを確認できます。

パターン移行

「古いエラー処理パターン（すべてのルートハンドラーでのtry/catch）から、集中型エラーミドルウェアパターンに移行しています。これが新しいパターンの例です。/api/settingsディレクトリ内のすべてのルートハンドラーに適用してください。」

Claude Codeは例を読み取り、パターンを理解し、すべてのファイルに一貫して適用します。複数のtry/catchブロックを持つルート、残しておく必要があるクリーンアップロジックを持つルート、特定のタイプのエラーをキャッチするルートなど、エッジケースを処理します。

大規模プロジェクトでのコンテキスト維持

AI支援開発における最大の課題はコンテキストです。Claude Codeにはコンテキストウィンドウがあり、一度に考慮できる情報量に制限があります。小さなプロジェクトではすべてを読み取ることができますが、大規模なモノレポではできません。

CLAUDE.mdをアーキテクチャドキュメントとして使用する

CLAUDE.mdファイルはコーディング標準のためだけではありません。プロジェクトのアーキテクチャを高いレベルで記述するために使用してください。

## Architecture
- API routes are in /src/routes, one file per resource
- Business logic is in /src/services, called by route handlers
- Database access uses Drizzle ORM, schemas in /src/db/schema
- Frontend components are in /src/components, organized by feature
- Shared UI components are in /src/components/ui
- State management uses Zustand, stores in /src/stores

これにより、Claude Codeはすべてのファイルを読み取っていなくても、プロジェクトをインテリジェントにナビゲートできます。データベーススキーマを探す場所、新しいコンポーネントを配置する場所、レイヤーがどのように接続されているかを知っています。

戦略的なファイル読み取り

Claude Codeに「プロジェクト全体を読み取って」と依頼しないでください。代わりに、関連する部分を指示してください。

「ユーザー設定サービス、設定APIルート、および通知設定コンポーネントを読み取ってください。設定更新エンドポイントにレート制限を追加したいです。」

これにより、Claude Codeは不要なファイルにコンテキストウィンドウを浪費することなく、必要なコンテキストを正確に得ることができます。必要であれば追加のファイルを要求できますが、焦点を絞って始める方が良いです。

セッションの継続性

長いコーディングセッションでは、会話を通じて自然にコンテキストが蓄積されます。しかし、新しいセッションを開始すると、そのコンテキストは失われます。私はこれを次のように処理します。

1. 最近のアーキテクチャ上の決定でCLAUDE.mdを更新し続ける
2. 各セッションを、取り組んでいることに関する簡単なコンテキストステートメントで始める
3. Claude Codeが最近の変更を理解できるように、Gitコミットメッセージを使用する

Gitログは過小評価されているコンテキストソースです。Claude Codeが最後の10個のコミットメッセージを読み取ると、最近何が変更されたかを理解し、進行中の作業との競合を避けることができます。

うまくいくこととうまくいかないこと

AI支援が優れている点

**ボイラープレートとCRUD操作。**検証、エラー処理、テストを含む新しいAPIエンドポイントの作成は、80%が機械的な作業です。Claude Codeは、私がタイプするよりも速く、より一貫してこれを生成します。

**複数ファイル間の一貫性。**変更が8つのファイル（型定義、スキーマ、マイグレーション、サービス、ルート、コンポーネント、テスト、ドキュメント）に影響を与える必要がある場合、Claude Codeはそれらすべてにわたる一貫性を維持します。私は必然的に1つ更新を忘れてしまいます。

**テスト生成。**テストしたい動作を記述し、Claude Codeにテストを作成させることは、手動で書くよりも速く、私が思いつかないようなエッジケースも捕捉します。「通知設定サービスのためのテストを書いてください。有効な入力、空の入力、無効な設定キー、データベースエラー、および同時更新をカバーしてください。」

コードレビューと分析。「このファイルに潜在的な競合状態はありますか？」または「この関数がnullユーザーで呼び出された場合、何が起こりますか？」Claude Codeはコードを分析し、手動レビューでは見落としがちな問題を特定します。

**新しいAPIとライブラリの学習。**不慣れなライブラリを使用する必要がある場合、Claude Codeはドキュメントと何千もの使用例を見ているため、正しい使用パターンを生成できます。これは、すべての関数シグネチャのドキュメントを読むよりも速いです。

AI支援が不十分な点

**複雑なビジネスロジック。**ロジックがビジネスドメインの深い理解を必要とする場合 — ルールが微妙で、エッジケースがドメイン固有で、要件が曖昧な場合 — AI生成コードは一見合理的ですが、重要な微妙な点を見落とすことがよくあります。私は常にコアビジネスロジックは自分で書き、その周りの足場にClaude Codeを使用します。

**パフォーマンスが重要なコード。**Claude Codeは正しいコードを生成しますが、必ずしも最適なコードではありません。ホットパス、タイトループ、またはメモリに敏感な操作の場合、私は実装を自分で書き、その周りのベンチマークとテストを生成するためにClaude Codeを使用します。

**アーキテクチャの決定。**Claude Codeは記述された任意のアーキテクチャを実装できますが、アーキテクチャをあなたのために選択すべきではありません。マイクロサービスとモノリス、SQLとNoSQL、サーバーサイドレンダリングとクライアントサイドレンダリングの間のトレードオフ — これらはあなたのチーム、規模、タイムライン、ユーザーを理解する必要があります。AIはそのコンテキストを持っていません。

**セキュリティが重要なコード。**認証フロー、暗号化、アクセス制御 — これらは手動で書き、人間によるレビューを受けます。Claude Codeは動作する認証コードを生成できますが、「動作する」と「安全である」は異なる基準です。

AI支援を使用しない場合

Claude Codeに頼ることが積極的に生産性を損なう状況があります。

**コードを深く理解する必要がある場合。**複雑な問題をデバッグしている場合や、システムがどのように機能するかを学習している場合、AIに修正を書かせると、問題が理解できません。時にはすべての行を手動で読む必要があります。修正ではなく、理解が重要です。

**タスクが30秒未満で完了する場合。**変数の名前変更、タイプミス修正、CSS値の調整 — ただ実行してください。Claude Codeに変更を記述するオーバーヘッドは、自分で変更する時間よりも長くなります。

**仕様が不明確な場合。**何を構築したいのかわからない場合、Claude Codeは自信を持って間違ったものを構築します。まず要件を明確にし、それから実装を委任してください。

**AI生成コードのレビューに、自分で書くよりも時間がかかる場合。**短く、重要な関数では、15行のコードを書く方が、AI生成コードの15行を読んでその正確性を検証し、潜在的な問題を修正するよりも時間がかかりません。損益分岐点は複雑さによって異なりますが、それは存在します。

実践的なヒント

数ヶ月間の日常使用の後、これらは常に最良の結果を生み出すパターンです。

規約について明示的にする。「既存のエラー処理パターンを使用してください」は何もないよりは良いですが、「asyncHandlerラッパーを使用し、適切なステータスコードでAppErrorをスローしてください」の方が優れています。どのように行うかについて具体的であればあるほど、後で修正する手間が省けます。

**すべての変更をレビューする。**Claude Codeは適用する前に差分を表示します。すべての差分を読んでください。流し読みではなく — 実際に読んでください。これが問題を発見するポイントです。「AIがたぶん正しくやっただろう」とレビューをスキップすると、バグが本番環境に到達します。

**段階的なリクエストを使用する。**1つのメッセージで機能全体を記述するのではなく、段階的に構築してください：まずデータベースレイヤー、次にサービスレイヤー、次にAPI、次にフロントエンド。次のレイヤーに進む前に各レイヤーをレビューしてください。これによりチェックポイントが与えられ、各生成が集中した状態に保たれます。

**CLAUDE.mdを最新の状態に保つ。**アーキテクチャ上の決定を下したら、CLAUDE.mdを更新してください。新しいパターンを採用したら、それを文書化してください。アプローチを非推奨にしたら、それをメモしてください。このファイルは、コード品質に影響を与えるための最も強力なレバーです。

**書き込む前に読ませる。**変更を加える前に、Claude Codeに関連ファイルを読み取るように明示的に依頼してください。「既存の設定ルートを読み取り、同じパターンに従う新しいルートを追加してください。」これにより、ゼロからの生成よりもはるかにプロジェクトに一致するコードが生成されます。

AI支援開発は、タイピングを減らすことではありません。それは、アーキテクチャ、ビジネスロジック、ユーザーエクスペリエンスなど、重要な決定に認知的な労力を費やし、それらの決定をコードに機械的に変換する作業を委任することです。Claude Codeは、その委任に最適なツールですが、それでもツールです。開発者の判断が、出力の質を決定します。