【ITニュース解説】A week with Claude Code: lessons, surprises and smarter workflows

システムエンジニアを目指す皆さんにとって、日々の開発作業を効率化するAIアシスタントツールは非常に興味深い存在だろう。今回の記事では、「Claude Code（クロード・コード）」という新しいAIコーディングアシスタントが、実際の開発現場でどのように役立ち、どのような課題があるのかを深掘りして解説する。これまでよく使われてきた「GitHub Copilot（ギットハブ・コパイロット）」や「Cursor（カーソル）」といったツールとの比較も交えながら、その特徴を見ていこう。

まず、既存のAIコーディングアシスタントについて簡単に触れておく。GitHub Copilotは、主に統合開発環境（IDE）でコードを記述している最中に、次の行やコードの一部を自動で補完してくれるのが得意なツールだ。まるで隣にいるベテランプログラマーがヒントをくれるような感覚で、手早く小さなコードスニペットを書く際に非常に便利である。しかし、プロジェクト全体の大きな文脈を深く理解して提案することは苦手な場合がある。一方、Cursorは、プロジェクト全体のリポジトリ（ソースコードなどの管理単位）をローカルで分析し、その文脈を理解した上でコードの編集や生成を行う。これにより、ファイルを超えた大規模なリファクタリング（コードの改善）にも対応できる強力なツールであり、リポジトリ全体を分析するため、AIに情報を送る際の「トークン」というコストもかからないのが特徴だ。

そして今回注目するClaude Codeは、これらのツールとは少し異なるアプローチを取る。グラフィカルユーザーインターフェース（GUI）に頼らず、コマンドラインインターフェース（CLI）やスクリプトを通じて、開発者のワークフローに統合されることを目指している。つまり、シェルコマンドや独自のスクリプトと連携することで、複雑な開発環境でも機能するように設計されているのだ。筆者は当初、あまり期待していなかったが、実際に使ってみると、その印象は大きく変わっていったという。

使い始めの数日間は、指示が不明確だったり、曖昧な要求をしたりすると、Claude Codeは期待通りの結果を出せなかった。例えば、必要以上に複雑なモック（テスト用のダミーコード）を作成したり、誤ったフォルダに編集を提案したりすることもあった。しかし、週の中盤になると、その挙動が劇的に改善される。筆者がファイルパス、入力、出力、そして具体的な制約条件などを明確に伝えると、Claude Codeはクリーンなコードを生成し、分かりやすい説明を加え、リポジトリの構造に合った適切な足がかり（初期設定やテンプレート）を提供してくれるようになったのだ。この経験を通じて、筆者はClaude Codeを単なるコード生成ツールではなく、プロジェクトの複雑な状況を理解してくれる「チームメイト」のように感じ始めたという。

Claude Codeが真価を発揮するのは、まさにこの「明確な指示」がある場合だ。指示が具体的であればあるほど、クリーンで的確なコードと説明を生み出す。しかし、指示が漠然としていると、必要のない詳細を追加したり、チームのガイドラインに反する提案をしたりすることもある。例えば、デザインシステム（アプリケーションのデザイン要素を定義した一貫性のあるルールやツール群）において、ファイルの削減を提案したが、これは「関心の分離」という、各機能が独立して責任を持つべきだという原則に反するものだった。また、古いバージョンのフレームワークやツールを使っているレガシーリポジトリ（過去に作られた、古い技術で構築されたシステム）では、最新の情報を前提とした提案をしてしまい、修正が必要な場合もあった。だが、プルリクエスト（PR: 共同開発でコードを本流にマージする提案）のドラフト作成やコミットメッセージ（変更内容を示すメッセージ）の生成など、定型的な作業においては、一貫性のある作業を迅速に行うのに大いに役立つことがわかった。

Claude Codeを使う上で無視できないのが、「トークン」の制約とそれに伴うコストだ。AIモデルが処理できる情報の量を「トークン」という単位で表すが、大きなファイルをAIに読み込ませるほど、このトークン消費が激しくなり、利用料金も高くなる傾向がある。Cursorがリポジトリ全体をローカルでインデックス化し、トークン消費なしでプロジェクトの文脈を把握できるのに対し、Claude Codeでは常に「どれだけの文脈をAIに与えるか」と「コスト」のバランスを考えなければならない。

このトークンの制約を乗り越え、Claude Codeを最大限に活用するための「秘密兵器」が、「CLAUDE.md」というファイルだ。これは単なるREADMEファイル（プロジェクトの概要を説明するファイル）ではなく、Claude Codeが安全かつ正確に動作するために必要な、構造化された完全な知識ベースである。このファイルがなければ、AIはフォルダ構造、パッケージの境界、チームの責任範囲、ワークフロー、命名規則、レガシーパターンといった重要な詳細を見落としてしまう。しかし、CLAUDE.mdをきちんと整備すれば、Claude Codeはまるで本当のチームメンバーのように振る舞うようになる。Cursorがリポジトリ全体を自動で「把握」するのに対し、Claude CodeはCLAUDE.mdを通じて手動で文脈を与える必要があるのだ。

CLAUDE.mdには、次のような具体的なセクションを含めることで、Claude Codeの能力を飛躍的に向上させられる。 一つ目は、「クイックコマンドリファレンス」だ。これには、よく使うコマンドやワークフローを簡潔に定義しておく。例えば、「claude story」と入力すれば、チケット（課題管理システム上のタスク）に関するストーリー（ユーザー視点での要件）を自動生成したり、「claude commit」と入力すれば、チームの命名規則に沿ったコミットメッセージを生成し、プリコミットチェック（コミット前に自動でコードの品質を確認するテスト。リンティングやテスト実行など）を実行したりできる。これにより、毎回同じ説明をする手間が省け、作業が劇的に効率化される。具体的な例として、「claude commit」がブランチ名からチケット番号を抽出し、変更内容を分析して、チームのルールに沿ったコミットメッセージを生成する様子が紹介されている。また、「claude story」は、指定されたテンプレートと受け入れ基準（要求が満たされたか判断する条件）に沿って、ユーザーが望む機能のストーリーを生成し、さらには技術的な要件や完了の定義まで含めることができる。

二つ目は、「リポジトリとフォルダの概要」である。これは、プロジェクトの全体的な構造、例えばどのフォルダにフロントエンド（ユーザーが直接触れる部分）のコードがあり、どこにバックエンド（裏側の処理）のAPIがあるのか、共有パッケージはどこにあるのかなどを明確にするものだ。これにより、Claude Codeはコードの境界を理解し、共有されているコードを誤って壊してしまうようなリスクを避けて、安全な変更を提案できる。

三つ目は、「テクノロジースタックの認識」だ。使用しているプログラミング言語、フレームワーク、データベース、テストツールなどのリストを記載する。これにより、Claude Codeはプロジェクトの技術環境に合った、正確で最新のコードを生成できる。

四つ目は、「チームとプロジェクトのコンテキスト」である。どのチームがどの機能を担当しているか、Jira（課題管理ツール）などのチケット接頭辞、チーム間の依存関係などを記述する。これにより、Claude Codeはプルリクエストを適切なチームにリンクさせたり、変更内容を正確に要約したりできる。

五つ目は、「開発ワークフローとベストプラクティス」だ。ブランチの命名規則、プリコミットフック、テスト（単体テスト、結合テスト、E2Eテストなど）、継続的インテグレーション/継続的デリバリー（CI/CD: コードの変更を自動でテスト・デプロイする仕組み）のルールなどを記述する。Claude Codeはこれに基づいて、一貫性のある作業を支援し、テストの生成やデプロイ手順のリマインダーも行える。

六つ目は、「ストーリー作成と受け入れ基準」で、どのような形式でストーリーと受け入れ基準を作成するかを定義する。これにより、QA（品質保証）担当者にとっても分かりやすく、一貫性のあるストーリーを生成できる。

七つ目は、「プルリクエスト、コミット、変更セットのガイドライン」だ。コミットメッセージの書式や、プルリクエストに含めるべき情報（チケットリンク、ドキュメント、スクリーンショット、チェックリストなど）を定義する。これにより、チームの規約遵守が徹底され、見落としによるエラーが減少する。

八つ目は、「トラブルシューティングとエッジケース」だ。よく発生するビルド失敗やテスト失敗の原因、一般的な解決策などを記述する。これにより、Claude Codeは問題の診断と解決策の提案を、人間の助けなしで行えるようになる。

Claude Codeは、これらの情報を持つCLAUDE.mdを活用することで、特に複数のパッケージが一つにまとめられた「モノレポ」という複雑なリポジトリ構造において、その効果を最大限に発揮する。パッケージ間の編集、新しいサービスの足がかり作成、テストの記述、AWS CDK（クラウドインフラをコードで管理するツール）の構築といった作業が、より迅速かつエラー少なく行えるようになる。さらに、Claude Codeは開発者が見落としがちなエッジケースを指摘したり、ファイル整理後のセットアップ手順を思い出させたりする「小さな手助け」もしてくれるため、後々の混乱を防ぐことができる。

古い技術で構築された「レガシーリポジトリ」に対応する際は、「CLAUDE_LEGACY.md」のような専用のコンテキストファイルを用意することが強く推奨される。これには、使用されている技術スタックのバージョンマップ、実行およびデバッグ手順、既知のバグ、アップグレードに関する注意点などを記載する。筆者の経験では、数ヶ月間解決できなかったレガシーリポジトリの「レースコンディション」（複数の処理が同時に行われることで予期しない結果が生じる問題）を、Claude CodeがCLAUDE_LEGACY.mdの文脈を読み解き、適切なトランザクション（一連の処理をまとめて実行し、成功か失敗かを保証する仕組み）による修正とテストコードの提案を行うことで、短時間で解決できたという事例も紹介されている。

ただし、Claude Codeも完璧ではない。「短期的な記憶喪失」のような現象が起き、以前の指示を忘れたり、テンプレートに従うのを忘れたりすることがある。このため、人間による確認と修正は常に必要だ。しかし、これはAIの「可愛らしい」一面と捉え、最終的な判断は開発者が行うという意識を持つことが重要である。

最後に、GitHub Copilot、Cursor、そしてClaude Codeのそれぞれの得意分野をまとめておく。 GitHub Copilotは、IDE内でのインライン補完や定型的なコードの生成に優れており、手軽に利用できる。 Cursorは、リポジトリ全体を理解し、その文脈に沿った大規模なコード編集やリファクタリングをIDE内で効率的に行えるのが強みである。トークンコストを気にせず利用できるのも大きなメリットだ。 そしてClaude Codeは、CLAUDE.mdによって構造化されたリポジトリ、特にモノレポのような複雑な環境において、プルリクエストの作成、パッケージ間の編集、コードの足がかり作成、レガシーコードの修正といった、ワークフロー全体にわたる自動化と支援に優れている。まるで、プロジェクト全体の設計を事前に深く理解してから作業に入る、ベテランのシステムエンジニアのような働きをする。

これらのツールは、どれか一つを選べば良いというものではなく、それぞれの特性を理解し、場面に応じて使い分けることで、開発効率を最大限に高められる。Claude Codeは、開発者の思考、直感、判断といった人間特有の能力を置き換えるものではないが、それらの能力を増幅し、より効果的に発揮するための強力な「チームメイト」となる。CLAUDE.mdのようなコンテキストファイルを継続的に改善し、AIの提案を注意深く監視しながら、開発ワークフローに深く統合していくことで、開発者はより創造的な作業に集中できるようになり、エラーの削減と開発速度の向上に大きく貢献するだろう。AIは、システムエンジニアの仕事をより面白く、より効率的なものに変えていく可能性を秘めていると言える。