Claude Codeとどう向き合うか - 1. 3つの現実と心構え
シリーズ記事: Claude Codeとどう向き合うか
← 前の記事: なぜ今、AIとの向き合い方を考えるのか
→ 次の記事: AIが変える開発プロセスと人間の新しい役割
はじめに
前回の記事では、AIエージェントとの協働において求められるマインドセットの転換について触れました。「手を動かそう」と締めくくりましたが、実際にClaude Codeを使い込んでいくと、理想と現実のギャップに直面することになります。
この記事では、約1ヶ月の使用を通じて見えてきた3つの現実的な問題と、それぞれに対する実践的な心構えを共有します。
Claude Codeの3つの現実
1. メモリの指示は守られない
Claude Codeに限らずAIエージェントの活用において、メモリ機能の使用が挙げられることが多いです。ユーザー単位、あるいはプロジェクト単位での共通した知識を特定のパスのファイルに記載しておくことで、プロンプト立ち上げ時に自動的にその内容を理解した状態で開始される、というものです。Claude Codeだとこれですね。
メモリ機能は非常に便利かつ重要で、AIとユーザ側とで認識の共通基盤として活用することができます。私も色々な指示を入れており、日々内容を改善しています。
一方で、メモリの指示は必ずしも守られません。メモリに書いてあることを守ろうとするのは確かですが、必ずしも守ってくれるわけではない、というのが現状です。指示の内容が規範的なあいまいなものであるほど、指示を守らなくなるように感じますが、具体的な指示でも常に守られるとは限りません。例えば、私は「Always respond in Japanese regardless of the language used by the user」という指示を ~/.claude/config/CLAUDE.md の先頭の方に書いていますが、プロンプト一発目の返答を英語で返してくることが頻繁にあります。人間であっても「〇〇の時は〇〇しよう」なのを人から言われて実践するのは簡単ではないですよね。
ある規則にもとづいたフックのような処理や、一連のワークフローをメモリに記述して利用しようとする記事などを見かけます。この手のものは大抵うまくいきません。フックやワークフローのような処理に限らず、「〇〇の時は〇〇する」あるいは「いつも〇〇しよう」みたいな指示は、守られないことも多く、プログラミングのif文の感覚で使うのは危険です。
2. 未完成のコードで完了報告する
よく知られた問題ではありますが、Claude Codeはしばしば保身のため？の嘘をつきます。私が経験したなかでは以下のようなことがありました。
- 実装完了しました！ → 関数の中身がTODOコメントのまま
- 実装にもとづいてドキュメントを書きました！→ 推測や意見を混ぜ込んで事実でない内容が書かれている
- テストが通りました！ → テストにスキップ処理を入れてテストが通ったことにしてる
また、Xで見かけたこの事例は印象的でした。Claude Codeかはわからないですが、TypeScriptとwasmのベンチマークの作成をAIに頼んだら、中身は平均2倍の差がでるプレースホルダのままUIの作成だけ進めており、依頼者はそれに気づかずに2倍の差があったという内容で公開したということがあったようです。現在は記事は削除されたようですが、今後この手の事例は増えていくでしょう。
また、AIが真摯に実装を行った場合でも、100点のコードは出てきません。実装力としてはジュニアレベルくらいと言われることが多いようです。個人的には、設計を丁寧に行い実装の方向性さえ共有できていれば、ジュニアレベルよりはしっかり実装を進めてくれるとは感じます。とはいえ、一発OKのクオリティであることは少なく、レビューでの修正はかかせません。
3. 非効率な方法を選んでしまう
Claude Codeは組み込みのToolやユーザが設定したMCPを用いて処理を進めます。そのためユーザーが従来IDEやCLIツールを使って効率的に行っていた処理でも、大幅に非効率なやり方で進めようとすることがあります。
例えば、現状ではClaude CodeではLSP（Language Server Protocol）を使ってくれません。そのため、リファクタリングなどで非効率な実装をすることがあります。例えば、LSPを使えば一瞬で完了するリネームのような単純なリファクタリングでも、mvとgrepで進めようとします。従来の開発環境でのメンタルモデルのままClaude Codeに依頼をすると、非効率な選択をしてしまう可能性があるため、Claude Codeに合わせたメンタルモデルにもとづいて依頼を行っていく必要があります。
この点については、開発環境のエコシステムは徐々にAIエージェント側に取り込まれていく流れにあるので、将来的には問題ではなくなるとは思います。
3つの現実への心構え
1. 指示の出し方を体系化する - スラッシュコマンドとスクリプトの活用
Claude Codeに一定の処理をさせたい場合には、メモリ機能のみではなく、スラッシュコマンドを活用することができます。スラッシュコマンドは以下のような決められたパスに.mdファイルを置いておくことにより、そのファイルの内容を /my-command というコマンドで一発でプロンプトとして渡すことができる、というものです。Claude Code側で補完もしてくれるため、少ないタイプ数で呼び出すことができます。
vim ~/.claude/commands/my-command.md
起動時に一度だけ読み込むメモリに対して、スラッシュコマンドはその指示を実行するタイミングでユーザー側が明示的に呼び出すことになります。ユーザー側の手間は増えますが、指示の意図とコンテクストが明確になるためか、複数ステップからなる複雑な指示でも、正確に遂行してくれることが多いです。スラッシュコマンドは、メモリの指示を補完するものとして非常に有用です。
Claude Codeをしばらく使い込んでいると、自分の作業の中で頻発するフローやよく使う指示が浮かび上がってくるので、何度か遭遇したらスラッシュコマンド化していくことで、Claude Codeとの協働でのワークフローが洗練されていきます。
私が実際に使っているスラッシュコマンドの例：
-
/remind- グローバルメモリの指示を再読み込みして遵守を促す -
/suspend- 現在の作業コンテキストを保存して中断 -
/resume- 中断した作業を再開する際のコンテキスト復元 -
/discuss- 実装なしでアイデアを深く議論する対話モード -
/critical-review- 第三者視点での批判的レビュー -
/fact-check- 技術文書の事実確認 -
/quick-chat- 率直なフィードバックに特化した会話モード -
/new-slash-command- スラッシュコマンドの新規作成
もしくは、処理として完全に定型的なものであれば、その処理をスクリプト化しておき、Claude Codeからはスクリプトを呼ぶだけにしておく方法も便利です。もちろんスラッシュコマンドとも併用できます。これは従来の開発環境でもよく行われている方法で、CLIツールやスクリプトを使って定型的な処理を自動化するのと全く同じです。スクリプト化することで、AIに任せることができる処理を増やすことができ、AIとの協働をより効率的に進めることができます。
必要なフローや共有したいコンテクストは、個人やチームによって異なるため、実際にClaude Codeを使い込んで見出していくことが重要です。
- Claude Codeを使い込む
- よく使うフローやコンテクストが見えてくる
- メモリ、スラッシュコマンド、スクリプト化
- Claude Codeとの協働フローが洗練される
というサイクルを回していくことが重要です。このサイクルを回すことで、自分なりのClaude Codeとの協働フローが確立され、効率的な開発が可能になります。
2. 品質チェックの仕組みを作る - 文書ファーストとAIレビュー
Claude Codeは人間を遥かに超える速度でコードを生成できますが、品質については一切の保証をしません。そのため、成果物の品質の保証は人間が行う必要があり、そのためのレビューが非常に重要です。Claude Codeとの協働が進んでくると、人間のレビューがボトルネックになってきます。効率的なレビュー体制を構築することが、Claude Codeとの効率的な協働において非常に重要です。
2.1 文書ファーストの開発プロセスの構築
何も準備せずにレビューを行う状況は避けるべきです。Claude Codeに実装を依頼する前に、実装の方向性や要件を明確にし文書化しておくことが重要です。文書化自体もClaude Codeとともに進めることで、従来よりも遥かに短時間で行うことが可能です。実装を開始してからも作業の内容を文書化するように適宜依頼します。これにより、レビュー時に必要な情報を事前に整備しておくことができ、レビューの効率と正確性を大幅に向上させることができます。
また、文書にもとづいた開発を進めることにより、Claude Codeが方向を見失っているような場合でも、文書を参照させることで、正しい方向に修正することが容易になります。文書ファーストの開発プロセスを構築することで、AIとの協働がよりスムーズになり、品質の高い成果物を得ることができます。
2.2 AIによる補助レビューの活用
最終的な保証のためのレビューは人間が行いますが、内容の正確性のチェックや、実装の方向性の確認などについては、AIによる補助レビューを活用することができます。チェックしたいポイントを明確にしAIにレビューを依頼することによって、特定の観点についてのレビューをAIに負担させることができます。よくあるレビュー依頼は上記の通りスラッシュコマンド化しておくと便利です。
また、私は「ホワイトボックスレビュー」と「ブラックボックスレビュー」の2つのレビュー手法を使い分けています。やっていることは単純で、実装を行ったプロンプトのままレビューを行うか、新たなプロンプトを立ち上げて実装のコンテキストを渡さずにレビューを行うかの違いです。上記で文書を適切に整備しておくことで、新たにプロンプトを立ち上げて、文書を渡しながらレビューを依頼することにより、実装のコンテキストを切り離したブラックボックスレビューを行うことができます。実装時の思い込みから離れて問題を発見しやすくなるため効果的です。嘘をついている箇所も見抜いてくれることが多いです。例えば、ブランチでの作業内容をレビューする場合は、以下のようなスラッシュコマンドを用意しておくと便利です。
# Black box Review
Review the changes in this branch referring to the document: $ARGUMENTS
3. 開発環境を最適化する - AIへの作業委託とツール整備
Claude Codeを使い始めると、思ったよりも多くの作業をAIに任せられることに気づくでしょう。楽しくなってあれもこれもやらせたくなりますが、実際にはAIに向いている作業とそうでない作業があります。それらを適切に分担することが、Claude Codeとの協働をスムーズに進めるために重要です。
とはいっても、人間があれこれやりすぎると、Claude Codeとの協働にむけたプロセス改善の試行錯誤が進まなくなります。Claude Codeに全て任せることを基本として、Claude Codeが上手く進められない部分を見出したら、そこを人間が補完するというスタンスがいいのではないかと思います。
事前に内容が決まらないようなタスクは、Claude Codeに依頼することによって適当なToDoに分解して進めてくれるため、Claude Codeに積極的に依頼していった方が良く、一方でAIが非効率にしか進められない作業はCLIツールやスクリプト化などでパッケージング可能なことが多いです。積極的にパッケージングして、AIに委託可能な作業を増やしていくことにより、AIに分担可能な領域を増やしていく、というスタンスが、Claude Codeとの協働をより効果的に進めるためのポイントであると考えています。
まとめ
Claude Codeの3つの現実に対して、それぞれ実践的な心構えがあります：
- 指示は守られない → スラッシュコマンドやスクリプトで確実性を高める
- 成果物は信頼できない → 文書ファーストとAIレビューで品質を保つ
- 非効率な処理をする → ツールの整備とAIへの作業委託を最大化する
これらは現時点での私の実践から得た知見です。Claude Code自体も急速に進化しているため、常に新しい方法を試していく姿勢が重要です。
次の記事では、AIとの協働によって開発プロセスがどのように変化し、その中で人間の役割がどう変わっていくのかを詳しく見ていきます。
Discussion