実案件で初めてClaude Codeを使って開発する機会がありました。私が担当したのは、Webアプリの新機能におけるAPIと画面の実装です。
これまでChatGPTなどの「チャット型AI」にコードを書かせたことはありましたが、Claude Codeのように直接ファイルシステムのコードを読み書きする「エージェント型AI」を使うのは初めてでした。
今回、業務のスケジュールと品質要求が存在する中で、本格的にAIコーディングを経験しました。
なお、Claudeの料金プランは Max（5倍）プラン を利用しました。当初は Pro プランで始めたのですが、トークン（使用量）がすぐに枯渇してしまい、業務で使い続けるのは難しいと判断したためです。
1日中コーディングの相棒としてフル活用するのであれば、Max プラン以上が現実的だと感じています。
※2026年3月頃に利用した時点の状況です。また、現在は社内ではTeamプランを通常利用しております。
AIによるコーディングに関する記事はすでに多く出回っていますが、個人開発や検証と本格的な開発では事情がだいぶ違います。
この記事では、『既存コードの書き方に合わせる』『チーム内でのコードレビューに耐える品質を保つ』『複数のAPI・画面で一貫性を持たせる』——そうした本格的な開発ならではの制約の中でAIとどう付き合うかについての知見を中心にまとめます。
「これからAIコーディングを業務に取り入れたい」という方の参考になれば幸いです。
今回私が担当した作業の規模は以下の通りです。
APIはいずれも既存のDBテーブルや他のAPIとの整合性が求められる内容でした。
規模としては中程度ですが、画面とAPIの連携や既存システムとの整合性を取る必要があったため、純粋な新規開発よりは考慮事項が多めでした。
AIを使う開発では、人間の役割が大きく変わりました。最初の数日は「何をしていいのか分からない」と戸惑うほどで、これまでの開発フローとは別物だと感じました。
今回私がやったのは以下の作業です。
.md にまとめたりと、AIへの「前提資料」を用意する役割コードを直接書く時間よりも、「AIに何をどう指示するかを考える」「出てきたコードが正しいか確認する」時間のほうが圧倒的に長かったです。
自分の仕事が「書く」から「素材準備・指示・レビュー」にシフトした、という実感がありました。
具体的にAIに任せた（または支援してもらった）のは以下の内容です。
このあたりの「型が決まっていて、それなりに手数がかかる作業」はAIが非常に得意です。
手を動かす時間を大幅に削れたので、人間は「何を作るか」「本当に正しいか」に集中できるようになりました。
AIに実装を任せるうえで最も大事だと感じたのは、AIに渡す「素材」をどう整えるかです。
設計書自体は人間（私を含むチーム）が作成しました。
.md ファイルに記載これらをすべて1つのフォルダにまとめ、「このフォルダを読んで」と指示するだけで、AIが必要な情報を拾ってくれるようにしました。
design-docs/
├── api/
│ ├── api-list.csv
│ └── api-spec.csv
├── db/
│ └── table-definition.csv
├── screens/
│ ├── screen-1.png
│ ├── screen-2.png
│ └── screen-overview.md
└── README.md
ExcelではなくCSVで渡したのは、ExcelをそのままAIに渡したところ、裏でPythonスクリプトを実行して解析しようとしたためです。
動くこともあると思いますが、CSVならそのままテキストとして読めるので、確実で高速です。
AIコーディングを業務で使ってみて苦労したことのひとつが、コンテキスト（AIが覚えている文脈）の管理です。
Claude Codeは会話が長くなると、途中でセッションが更新され、過去に私が伝えた仕様や前提をAIが忘れてしまうことがありました。「さっき言ったのに…」という状況です。
この問題への対処として有効だったのが、先ほどの 設計書フォルダの整備 でした。セッションが切れても、新しいセッションで「このフォルダを読んで」と一言伝えるだけで、AIがすぐに前提をキャッチアップできる状態にしておくのです。これによって「説明のやり直し」のコストをかなり下げられました。
会話の流れにだけ頼らず、ファイルとして仕様を外出しするのがポイントです。
CLAUDE.md についてClaude Codeには、プロジェクト直下に CLAUDE.md を置いておくとセッション開始時に自動で読み込んでくれる仕組みがあります。
コーディング規約や命名ルールを書いておけば、AIが毎回自動でそれに従ってくれる、便利な機能です。
また、プロジェクトには .claude/ というフォルダを作ることもでき、設定ファイルやカスタムコマンドなどを格納できます。今回の案件では、ここにコーディング規約などの詳細ファイルも整備されていました。
Claude Codeに関係するファイルだろうとは感じていたものの、指示しなくてもAIが自動で読んでいるとは知りませんでした。そのため、素材フォルダを別途手作業で用意して毎回読み込ませる、というやり方に落ち着きました。
今思えば、CLAUDE.md を整備して .claude/ 配下のファイルと連携させておけば、手作業の一部は省けたはずです。
「設定ファイルを置けばAIが勝手に全部使ってくれる」と思いがちですが、実際はAIに読ませたい情報を、AIの読み込みルールに合わせて構造化する必要がある、というのが後から得た学びです。
APIの実装は、AIが最も得意とする領域のひとつでした。
テストコードを先に（あるいはセットで）書かせるのは、AIに対しても非常に有効です。
実際、実装後に「テストが失敗 → APIコードを修正」という流れになるケースがたまにあり、テストが仕様の強力なチェック機構として機能していました。
指示の出し方で特に重要だったコツは、表記の統一です。
これはコードだけでなく、コメントやプロンプト内の日本語も含みます。
get_user_info なのか getUserInfo なのかfromDate なのか from_date なのかこうした表記揺れがCSV（設計）・プロンプト・既存コードの間にあると、AIが迷ってしまいます。
結果として、こちらの意図とは微妙に違う実装になることがありました。
対策として、API名やパラメータ名は絶対に省略せず、すべての箇所で完全に同じ表記で統一するようにしたところ、AIの出力精度が大きく改善しました。
私が担当したのは画面全体の新規作成ではなく、既存画面の一部をデザイン通りに修正する作業でした。
APIに比べると修正量は少なかったですが、難易度は少し上がりました。
デザイン画像を渡して「この通りに作って」と指示しましたが、画像だけではAIが正確な値を読み取れず、余白やフォントサイズが微妙にデザインと違う実装になることがありました。
参照できる同じデザインの要素が他にない場合、AIには判断材料がありません。
画像から「だいたいこのくらい」で作ってしまうため、デザインとの微妙なズレが生じます。
この問題への対策として有効だったのが、Figma等で測った具体的な数値をテキストで渡すことでした。
【プロンプトの例】
この画像の通りに実装してください。ただし、以下のスタイルを適用してください。
- 要素間の余白：16px
- 見出しのフォントサイズ：18px、カラー：#333
- ボタンの高さ：40px、背景色：#007bff
画像で全体のレイアウトを伝え、細部はデザインから測った数値で指定する。
この組み合わせで、デザイン通りの実装ができるようになりました。
AIが作った画面を確認して細かいズレを直す段階では、実装結果のスクショを渡してピンポイントで指摘するのも有効でした。
「このボタンの上端とテキストの距離は 8px にしてください」と、画像と数値をセットにして指示を出すことで、AIも修正箇所と正解の値を正確に把握してくれます。
フロントエンドからAPIを呼び出し、データを受け渡しする連携部分の指示には、いくつか気を付けるべきポイントがありました。
よくあるのが、「APIから受け取る値」と「フロント側だけで制御する値」の境界があいまいになる問題です。
何も指示しないと、AIが勝手に推測して「本来APIから取ってくるべき値」をフロント側で固定値として持ってしまうことがあります。
これを防ぐために、プロンプトやAIに読み込ませる仕様書に、以下を明確に書くようにしました。
「このデータはどこから来るのか」という境界を言語化してあげるだけで、AIの迷いや意図しないハードコードが大きく減ります。
もうひとつ便利だったのが、モックデータ（ダミーデータ）の活用です。
APIがまだできていない段階でも、画面の動作確認は進めたいものです。そんなときは、AIにまず「モックデータを表示する形で実装して」と指示します。
Claude Codeはそれっぽいモックデータを一瞬で作ってくれるので、ローカルでUIの確認がすぐにできて非常に助かりました。
// 開発初期はこういう形で仮実装
const mockUserData = {
userName: 'テスト太郎',
itemCount: 42,
score: 85.5,
// ...
}
APIができあがったら、モックを実際のAPI呼び出しに置き換えます。
このとき注意が必要なのが、置き換え漏れです。
AIに「モックデータをAPIの値に置き換えて」と指示しても、一部が置き換わらずに残ってしまうことがよくありました。
console.log が残っていないかこうした不要なコードの消し忘れは、AIに任せきりにすると起きやすいと感じました。
差分を眺めるだけでは気づきにくいので、以下の方法を組み合わせて、残っていないかを確認するようにしました。
mock、TODO、console.log などのキーワードで検索をかけるこれはAIコーディングを業務で使って、一番強く感じたことです。
エージェント型のAIツールは、自律的に動いてくれるのが大きな強みです。
しかしその裏返しとして、仕様に不明点があっても質問してこず、勝手に推測して実装を進めてしまうという弱点があると感じました。
「ここの仕様がわからないのですが」と自己申告してくれることは、まずなかったです。
初めてAIコーディングを経験した身としては、この「自信満々さ」に最初は気づきにくく、出力されたコードをそのまま信じてしまいそうになることが何度かありました。
AIにエラーなく動くコードを書かせても、中身が実務レベルの品質に達していないことがありました。
実際に以下のようなケースに遭遇しました。
この問題への対策は、シンプルですが以下の徹底に尽きます。
上記のいずれもそうですが、「AIが書いてくれたから大丈夫だろう」と思い込まず、最終的な出力と実際の差分が合っているかを人間が必ずチェックする習慣をつけることが、AIと上手く付き合う上で非常に重要だと感じました。
本格的な開発でAIを活用するために大事だったことを振り返ると、大きく3つに集約されます。
1. AIに渡す「素材」の整備
設計書をAIが読み取りやすい形式に変換し、必要な情報にAIがたどり着けるようにしておくことが重要でした。AIが正確に動くかどうかは、人間がどれだけ「前提資料」を整えられるかにかかっています。CLAUDE.md のような仕組みも含め、AIに情報をどう渡すかを設計すること自体が、新しい重要な作業だと感じました。
2. 正確で一貫した指示
API名やパラメータ名、コメントの日本語まで表記を完全に統一し、データの出処（APIから取得するのか、フロント側で定義するのか）も明示しました。
曖昧さを残すとAIが勝手に推測して進めてしまうので、指示の精度がそのまま出力の精度に直結します。
3. 人間によるレビュー
AIは不明点があっても質問せず、自信満々に間違えます。冗長なコード、修正漏れ、PRの文章ズレなど、動くけれど品質が足りないケースが多くありました。
最終的な品質を担保するのは人間のレビューであり、そのためには確かなプログラミング能力が不可欠です。「AIが書いてくれるからプログラミング能力はいらない」ということはなく、むしろレビューや指示の精度を上げるためにこそ必要だと強く感じました。
自分の仕事が「コードを書く」ことから「素材準備・指示・レビュー」にシフトしたことで、求められるスキルも変わりました。
AIとのやり取りは経験を積むほど上達する領域だと感じています。
今回は素材フォルダを手作業で整備するやり方でしたが、CLAUDE.md や .claude/ の仕組みをもっと理解して活用すれば、AIへの情報の渡し方自体をさらに効率化できるはずです。
今後はそうしたツールの理解を深めつつ、コードレビューをAIに補助させるなど、AIに任せられる範囲をさらに広げていきたいと考えています。
初めてのAIコーディング体験でしたが、これからの開発の進め方を深く考えさせられる、非常に良い経験でした。