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