はじめに
Claude Codeを実務でガッツリ使い始めてから3ヶ月ほど経ちました。
使う中で「こうした方が効率的に実装できたのでは」と痛感したことをまとめます。
その内容をClaude.aiに実際にぶつけてみた反応も記載します。
前提
- チーム開発
- 画面数20程度のWebアプリ作成時の気づき
- 本番リリース前
実務で気づいた5つのこと
1. ログファイルの置き場を初めから指定する
Claude Codeはセッションが変わるとやり取りの中身を忘れてしまうため、各自でdocs/logsなどディレクトリを作成し、ローカルでログを保存するようになっていきました。
.gitignoreでログを置くディレクトリを指定し、リモートリポジトリへ混ぜないようになりました。
そのため、初めからログファイルの置き場所を指定しておけば、ローカルを綺麗に保てたと感じました。
Claudeの感想
チーム全体でdocs/logsのようなログ配置場所を事前に統一しておく運用は効率的だと考えます。
各メンバーが独自のディレクトリ構造を作らず、プロジェクト構造が統一されます。
.gitignore設定も最初から共有でき、リポジトリ汚染リスクが減ります。
新規参加メンバーが迷わず、オンボーディングコストが下がります。チーム内でログ参照が必要な場合、場所の確認が不要です。
ただし実効性はチーム文化次第です。
全員がClaude Codeを使うなら標準化の価値は高いですが、一部メンバーのみなら過剰な取り決めになるかもしれません。
また、ログを個人メモとして扱うか、チーム資産として扱うかで、配置ルールの重要度も変わりそうです。
結論として、初期にREADMEでローカルログはdocs/logs推奨と書いておく程度の軽い標準化は有効だと思います。
2. 詳細設計を実装に落とし込める形まで実施する
顧客（非エンジニア）に同意を取りたい部分を顧客が理解できる形に落とし込んだ基本設計はClaude Codeを使い、モックまで完成させました。しかし、詳細設計はAIを使う以前と同じ粒度で実施していました。
そのため、同じ処理をする関数が整合性なく複数作られていたりしました。
この処理ではこのサービスを使う、この画面ではこのコンポーネントを使い回す、など人間が作成するときは気にする点をAIは事前に示しておかないと非効率的にコードを量産してしまうことに気づきました。
そのため、実装前の段階での設計の重大性が増したと感じました。
Claudeの感想
この気づきは重要です。
AI支援開発では設計フェーズの役割が変化しています。
従来の開発では、実装中にエンジニアが「あ、この処理は共通化できる」と気づいて修正できました。
しかしClaude Codeは各タスクを独立して処理するため、明示的な設計指針がないと、同じロジックを別々に実装してしまいます。
事前設計の充実は確実に効率化につながると考えます。
共通関数、サービス層、コンポーネント設計を先に定義すれば、重複実装を防げます。
この処理は○○サービスを使うとルール化すれば、整合性が保たれます。
後からリファクタリングするより、最初から正しく作る方が速いです。
おそらくAIに渡す設計書のフォーマットが新たなスキルになります。
アーキテクチャ方針、命名規則、責務分担を明文化する能力が、AI時代のエンジニアにより求められるでしょう。
3. 同じ機能はまとめて実装
アイテムAの登録画面とアイテムBの登録画面の2つの画面があるとします。
構造的にはほぼ同じです。
人間が実装する場合、アイテムAの画面を作成した後、アイテムAの画面で使えるところは共通化し、Bも同じように作成しようとする心理が働くと思います。
しかし、Claude Codeは前のセッション内容を覚えておらず、「AのようにBを作って」と言ってもコピペするならまだしも、微妙に違う構成で実装してきたりします。
バグの温床です。
そのため、ほぼ同じ構造のものは一度の指示で実装させてみたところ、関数を共通化し、意図した通りの実装をしてくれました。
一度のセッションですべてを実装するのが難しい場合、実装計画をファイルに残しておき、必要なタイミングで読み込ませるのがいいのではと思っています。
Claudeの感想
この気づきは、AI支援開発のコンテキスト管理の本質を突いています。
人間はAを作ったからBも同様にという暗黙の一貫性を保てますが、Claude Codeはセッション間で文脈を失うため、同じ指示でも実装のブレが生じます。
これは確実にバグの温床になります。
一度の指示で類似機能をまとめて実装させるアプローチは非常に効率的です。
AIが自然に共通化を判断し、整合性が保たれます。
後からBの実装がAと違うと気づいて修正する手戻りがありません。
レビュー時の認知負荷も減ります。実装計画ファイル（IMPLEMENTATION_PLAN.mdなど）の活用は、おそらくAI時代の新しい設計成果物になります。
どの機能をどの順序で、どのセッションで実装するかを明文化することで、セッション分断によるブレを防げます。
4. 人間がしんどいと思うことは避ける
テーブル → 行展開 → さらに中にUI、、のような深いネストを人間が実装する前提ならば、全力回避しようとすると思います。
AIを使って実装する前提でUIを考えた時、ユーザーがなんとなく使いやすそうだから、ネスト深そうだけど、なんとかなるっしょと進めたところ、一つ実装するたびに動作確認に時間もかかり、よくわからないバグが発生、、という地獄のような状況に陥り、遅延を招く原因となってしまいました。
AIを使ったとしてもしんどい実装はしんどいし、うまくいかなかった場合の原因を探すのに人力ではとてもじゃないけど時間がかかりすぎる、なんてことになります。
人間が理解できる範囲の設計にすることがプロジェクトを円滑に進めるために必要だと感じました。
Claudeの感想
この気づきは、AI支援開発の重大な落とし穴を示しています。
AIが書くから複雑でもいいという思考は危険です。
深いネスト構造は、AIが一見それらしいコードを生成しても、デバッグ困難性は変わりません。
むしろ、AIが生成したコードは人間が全行を理解していないため、バグ箇所の特定により時間がかかります。
複雑な設計は確実に非効率です。
動作確認の時間増加、バグ発生時の原因特定コストの爆増、AI再生成を繰り返しても根本解決しないといった問題が発生します。
人間がこれは面倒だと感じる設計は、AIでも面倒です。
おそらく、AI時代の設計原則はAIが書けるかではなく人間がレビュー・デバッグできるかが基準になります。
シンプルな設計への回帰が起きるかもしれません。
5. 人間にもある程度の知識は必要
フロントエンドのバグ修正中、Claude Codeが時間をかけても全然解決しないことがありました。
ずっとClaude Codeはフロントエンドをこねくり回していました。
原因を紐解いていったところ、バックエンドに原因があり、数行付け足すだけで解決することに人間が気づき、指示をしたところすぐに解決しました。
これはある程度の開発経験があったから気づけたことだと思います。
細かいコードの書き方は覚えていく必要はなくなるのかもしれませんが、ここでこの動きをしている、とか、この言語のベストプラクティスはこうだ、などの知識は浅くてもいいからまだ必要なんだと感じました。
Claudeの感想
この気づきは、AI支援開発における人間の役割の核心を突いています。
Claude Codeは与えられた文脈（フロントエンド）で解決しようと努力しますが、問題の所在を誤認すると延々と無駄な試行を続けます。
バックエンドが原因と気づけたのは、システム全体を俯瞰する経験があったからです。
経験による問題切り分け能力は圧倒的に効率を左右します。
AIに任せきりだと数時間無駄にしますが、正しい診断と指示で数分で解決できます。
この差は、プロジェクト全体では膨大な時間差になります。
おそらく今後求められるのは広く浅い技術理解と問題の所在を特定する直感です。構文の細部は覚えなくていいですが、データフローのどこで問題が起きうるか、この症状ならどこを疑うべきかという経験則は不可欠です。
まとめ
結論:Claude Codeはこう使うのがいい
Claude Codeを使ってみて分かったのは、「AIに丸投げすれば楽」じゃなくて「設計と判断は人間、実装はAI」という役割分担が大事ってことでした。
効率的に使うための3原則:
- 事前設計を手厚くする - 共通化方針、コンポーネント設計、アーキテクチャをAIに渡す前に明文化しておく
- 人間が理解できる範囲に留める - 複雑な実装はAIでも人間でもしんどい。デバッグできる設計を優先する
- AIの得意・不得意を把握する - セッション間の文脈喪失、問題の切り分けの弱さを理解して、人間が舵取りする
AIは実装速度を劇的に上げてくれますが、システム全体を俯瞰する力、問題の所在を見抜く経験、適切な粒度で指示を出す設計力は、むしろ以前より重要になったと感じています。
Claude Codeは「コードを書く時間」を減らしてくれますが、「考える時間」は減らしてくれません。
おわりに
これらの気づきを活かし、今関わっているプロジェクトが無事に完了することを祈りつつ、新年を迎えようと思います！