Claude Codeを使ったアプリ開発 ― SIerが現場で実践するAI活用プロセス
はじめに
最近、Claude Codeがめちゃくちゃ流行っています。ChatGPTやGeminiを抜いて、もうClaude Code一強と言ってもいいくらいの勢いですよね。エージェントやスキルといった便利な機能が色々あって、チャットで適当に指示するだけでアプリができてしまう。いわゆる「バイブコーディング」を試したことがある方も多いのではないでしょうか。
バイブコーディングの落とし穴
このClaude Codeを使ったバイブコーディングはめちゃくちゃ便利なんですが、そのアプリ、大丈夫ですか？
バイブコーディングはチャットベースで開発を進めていきます。「こういう機能を作って」「やっぱりここを修正して」「この機能を追加して」――そんな感じで繰り返していくうちに、システム開発で大事なものがどんどん失われていきます。
具体的に何が失われるのか：
- 仕様 ― 最新の仕様がどこにもまとまっていない。チャットの中でパラパラと指示しているので、今どの処理がどういう仕様になっているのかすぐに確認できなくなる。
- 意思決定の理由 ― なぜこの技術を選んだのか、なぜこの設計にしたのか。チャットの流れで「じゃあそれで」と決めていったものの、後から理由を辿ることができない。
- 変更履歴 ― 誰がいつどのような修正をしたのか分からなくなる。
- テストの根拠 ― 仕様がまとまっていないと、何をテストすればいいのか、何を確認するのかもどこにも整理されない。
こういうものが失われた状態で何が起きるかというと、誰にもアプリについて説明できなくなるんです。
- クライアントに「ここの仕様ってどうなってましたっけ？」と聞かれてすぐに回答できない
- 半年後に自分が見返してもなぜこう作ったのか分からない
- 複数人で開発する場合、メンバー間で認識がずれて矛盾する実装が生まれる
- 新しく入った人に引き継ごうとしても、コードはあるけど実装の背景がゼロ
これがAI駆動コーディングの一番の落とし穴です。
SIerとしてのAI活用法
じゃあ、開発の現場ではどうすればいいのか。この記事では、SIerとして実際の開発現場でAIをどう活用しているのか、その方法を紹介します。
「SIerの話」と聞くと、クライアント向けに大規模で作る重たい開発の話でしょ、と思う方もいるかもしれません。確かにその側面はあります。ですが、SIerがどのようにAIを活用しているのかという話は、自社で社内アプリを作る方や、個人でアプリ開発をしている方にもすごく有益な情報だと思います。
今回は私が作ったアプリを題材にして、ステップごとに解説していきます。
題材：TubeLingo
今回題材として扱うのが私が自作した「TubeLingo」というアプリです。
TubeLingoはYouTubeの英語動画を使って英語学習ができるアプリです。使い方はシンプルで：
- トップ画面でYouTubeのURLを入力して「開始する」をクリック
- 上側にYouTubeの動画が表示され、下側に英語の字幕が表示される
- 字幕を選択して「翻訳」をクリックすると翻訳を見ることができる
- 選択して「AI質問」をクリックすると、AIにチャットで質問でき、翻訳結果と前後の文脈を踏まえた解説をしてくれる
こういうアプリをゼロから作ること自体は、AIを使えばすぐにできてしまうので難しいことではありません。ただ、この記事で伝えたいのは「どのように作ったか」になります。
仕様や意思決定の理由が失われる、クライアントにもチームにも説明できなくなる――そういう問題を、Claude Codeを使いながらどうやって解決したかがメインテーマです。
開発プロセスの全体像
今回の開発は以下のステップで進めました：
準備
- POC（技術検証）
- ドキュメント作成
- Claude Code設定
開発
4. API実装
5. 画面モック開発
6. 画面ロジック開発
テスト
7. E2E（エンドツーエンド）テスト
8. 非機能確認
9. 手動確認
この流れはスピード感や規模感こそ違いますが、イメージとしてはウォーターフォールに近い形です。ドキュメント作成で要件定義と設計を行い、開発で実装し、テストする。
「ウォーターフォールなんて昔ながらの遅い手法でしょ」と感じる人もいるかもしれません。ですが、これをあえてやる理由があります。各工程でちゃんと成果物を作って確認しながら次に進む構造にすることで、後から「あれ、仕様ってどうなってたっけ」「ここって合意してましたっけ」みたいな手戻りを減らすことができるんです。
これはクライアント向けの開発やチーム開発だけの話ではありません。自社で作る社内アプリでも、個人事業主として1人でアプリ開発をしている場合でも同じです。規模や体制が違っても、仕様や意思決定の理由が失われて誰にも説明できなくなるという問題は同じように起きます。
AIを使えば確かに開発は早くなります。でも、それをちゃんとコントロールできる構造にしておくことが、現場で使う時には大事になってくる。そのためこのようなウォーターフォール的なプロセスを取りました。
ステップ1：POC（技術検証）
今回のアプリで一番コアになる機能――YouTubeの字幕取得がちゃんとできるか。これを最初に検証しました。
ここでClaudeに頼んだのが、字幕取得の実装パターンの調査と検証です。YouTubeの字幕取得にはいろんなライブラリや実装方法があるので、それらの方法を洗い出してもらい、実際にコードを作って実行してもらい、その結果をMarkdownにまとめてもらう。このMarkdownを見て最終的にどの実装にするかを決定しました。
結果として、最初はJavaScriptのライブラリを使ってNext.jsで実装しようと思っていたのですが、うまくいかなかったのでPython + FastAPIを使うことにしました。
このPOCは、自分でライブラリを調べてコードを書いて試して…とやると結構時間がかかります。Claudeに任せることで、技術の調査・検証フェーズをかなり短縮することができました。
ステップ2：ドキュメント作成
要件定義書
アプリ概要として「YouTubeの英語動画を使って英語学習ができるWebアプリ」という概要を記載し、YouTubeのURLを入力して字幕取得ができる、翻訳ができる、AI解説ができる、といった機能を記載しました。
開発ガイド
ユーザーがいてフロントエンドがあってバックエンドがあって、YouTubeの字幕取得やClaude APIを叩く、といったアーキテクチャ概要を記載。ディレクトリ構成のイメージや使用するライブラリも記載しています。
設計書（3種類）
- 画面設計書 ― 画面名、ASCIIアートによるモックイメージ、画面イベントを記載
- API設計書 ― エンドポイント、リクエストパラメーター、レスポンス、処理フローを記載
- プロンプト設計書 ― プロンプトのテンプレートを定義し、パラメーターを埋め込む形で設計
なぜMarkdownで作るのか？
一番の理由は、ExcelやPowerPointのような資料よりもAIが正確に理解してくれるという点です。またMarkdownはGitでも管理しやすく、差分も見やすいというメリットもあり、実際のプロジェクトでもドキュメントはMarkdownで作成しています。
こうしたドキュメントは作るのに時間もかかるし面倒だと思うんですが、Claudeに開発をさせる時にドキュメントを参照させることで仕様からブレない開発をさせることができます。また、最新の仕様が分からなくなる問題や、クライアントに仕様を聞かれて説明できない問題にも対応できるようになります。
時間をかけてでもドキュメントを作っておくことで、後の工程が圧倒的に楽になります。
ステップ3：Claude Codeの設定
今回は以下の3つをセットアップしました。
CLAUDE.md
チャットで指示をした時に必ず読み込まれるファイルです。今回は各ドキュメントの参照先と、スキル一覧、Claudeへの行動指示を記載しました。こうすることで、チャットで指示した時に適切なドキュメントを見てもらったり、適切なスキルを使ってもらうことができます。
Skills（スキル）
今回は以下の4つのスキルを作成しました：
- 画面モック実装スキル
- 画面ロジック実装スキル
- API実装スキル
- Playwrightを使ったE2Eテスト実行スキル
Playwright MCPサーバー
MCPとはClaudeが外部のツールと連携するための仕組みで、Playwrightはブラウザをコードで操作できるツールです。これを使うことでClaudeがブラウザを操作して画面のキャプチャを撮ったり、テストを実行したりできるようになります。
※自作MCPサーバも含まれていますが、本記事には無関係になります。
開発準備のまとめ
整理すると、作成した要件定義・開発ガイド・設計書といったドキュメントがインプットとなり、CLAUDE.mdやSkillsで定義したClaudeの振る舞いによって実際にコードが作成される。このような構造になります。
この下準備があることで、クライアントと開発前のレビューができたり、チーム内で「こういう風に開発していこう」という共通認識が作れます。AIでアプリを作るだけだとこうした下準備が飛ばされてしまい、実際にアプリを作ってから「思ってたアプリと違うな」ということが起きてしまうんです。
ステップ4：API実装
API実装では、開発準備で作成したAPI開発スキルを利用します。
このスキルでは以下のステップを定義しています：
- 設計書を確認
- Pydanticモデル（リクエスト・レスポンスの型）を定義
- 実際の処理内容であるサービスを実装
- エンドポイントを定義するルーターを実装
- 動作確認（サーバーを起動してcurlでテスト）
スキルを作っておくと、APIを開発する時に「設計書を見る → モデル定義 → 処理作成 → エンドポイント定義 → テスト」という流れをClaudeが勝手にやってくれるようになります。
実際にClaudeにプランを作成してもらったところ、まだ何も修正していないAIが作った一発目の状態で、ちゃんと正しいディレクトリ構成になっていたり、設計書通りのリクエスト・レスポンスが定義されていたりと、非常に高い品質でプランを立てられていました。
しっかり設計書やスキルを作っておくと、AIの出力も安定させることができます。
ステップ5：画面モック開発
ここで使うのが画面モック実装スキルです。
- 設計書を確認
- モックコンポーネントを作成（実際のAPI呼び出しやロジックを含まない、画面を表示するだけの仮コンポーネント）
- ビルドしてアプリを立ち上げ
- PlaywrightのMCPを使ってキャプチャを取得
Playwrightを使わない場合は、自分でローカルでアプリを起動してUIを確認して「ここを修正して」と指示しなければなりません。でもPlaywrightがあることで勝手にキャプチャまで撮ってくれるので、キャプチャだけ見て「ここをもうちょっと修正してね」と伝えるだけで済む。UIの修正がめちゃくちゃ楽にできました。
ステップ6：画面ロジック開発
画面ロジックの実装スキルでは：
- 設計書を確認
- カスタムフックを作成（エラー管理、API呼び出し、バリデーション実行など）
- 実装したロジックをコンポーネントに組み込み
- ビルドして再度Playwrightでキャプチャ取得
今回は画面モックと画面ロジックの2ステップに分けてフロントエンドを実装しました。
開発フェーズの振り返り
ドキュメント（要件・設計書）とClaude Code設定（CLAUDE.md・Skills）のおかげで、かなり開発がスムーズに進みました。
- 設計書が仕様の土台を作り、SkillsやCLAUDE.mdが実装の手順とルールを統一してくれる
- Claudeに毎回ゼロから説明する必要がなく、実装もブレずに済んだ
- 設計書があると実装内容の確認も楽。「この画面ってどうなってたっけ」という時にドキュメントを見れば一発で分かる
ステップ7：E2E（エンドツーエンド）テスト
E2Eテストでは、フロントエンドとバックエンドを実際に起動して、Playwrightによるブラウザ操作でフロントとバックエンドを結合したテストを行います。
E2Eテストスキルの流れ：
- 画面設計書の「画面イベント」セクションを読み、テストケースを洗い出し
- ユーザーがテストケースをレビュー
- テストファイルを作成
- テストを実行
設計書に画面イベント（初期表示の処理、字幕取得時の処理など）を書いておくことで、Claudeがテストケースを正確に洗い出してくれます。
ステップ8：非機能確認
アプリがちゃんと動作するかではなく、コードの品質や性能面の確認です。
Claudeにソースコードをレビューしてもらい、可読性やパフォーマンス上の問題がないかチェック。必要なところは修正してもらい、修正後にE2Eテストを再度実行して壊れていないか確認する、という形で非機能面での改善を行いました。
ステップ9：手動確認
最後に手動で確認を行います。
手動確認で1つバグを発見しました。AIチャットモーダルで一度質問した後に、別の箇所で再度AI質問をすると、以前の質問のチャットモーダルが表示されてしまうというバグです。本来は選択したテキストが違う場合は新しいチャットモーダルが立ち上がるべきでした。
こういった細かい点を設計書でちゃんとAIに指示できていなかったことがバグの原因でした。
テストフェーズの振り返り
- 設計書を適切に作成していたおかげで、テストケースの作成がスムーズにできた
- Playwrightを使うことで自動テストも実行でき、かなり効率的にテストができた
- 反省点：AIチャットモーダルの仕様を設計書に適切に落とし込めていなかった
教訓：ドキュメントの品質が開発の品質やテストの品質に直結する。
振り返りと学び
1. Playwright MCPがめちゃくちゃ便利
これまでAIを使ってアプリ実装する時、自分のローカルでアプリを立ち上げて画面を見て「ここのUIがちょっと違うんだよね」と文章でチャットで伝えていました。なかなかAIに伝わらなかったり、修正してもらってもうまく直っていなかったりで、結構ストレスが多かったんです。
PlaywrightのMCPを使うことで、開発からキャプチャ取得までClaudeに自動でやってもらえる。ローカルで画面操作をせず、キャプチャだけ見て「ここをこう修正して」とAIと会話できるので、かなりスムーズに修正ができました。
2. インプットは必要なものだけに絞る
実際のクライアント向けプロジェクトで起こった失敗談ですが、何百もある開発ルールやコーディング規約、設計書を全部インプットさせてコードを出力させるようにしていました。大量のインプットを詰め込んでしまうと全部が理解されるわけではないし、時間がかかった割には品質が悪いコードができてしまう。
CLAUDE.mdにナビゲーションを書いて必要なドキュメントだけ参照してもらうとか、コーディング規約はガイドを読ませるんじゃなくて既存のコードから慣習を読み取らせる方がいい。規模が大きくなったらドキュメントを細かく分割して、必要なところだけAIに見てもらうようにするのがおすすめです。
3. スキル/プロンプトの品質＝アウトプットの品質
実際のプロジェクトであった失敗ですが、フロントエンドの開発プロンプトに誤った指示があったため、機能的には問題ないけど性能がすごく悪いコードを生成してしまっていました。一応画面は動くけどすごくカクカクする画面が大量にできてしまった。
表面的な動作だけ確認して「OK」としてしまった結果、後から横展開で修正が発生して手戻りが大変でした。
開発に入る前にSkillsやプロンプトの作成にちゃんとリソースを割くこと、動作確認もしっかり時間をかけてレビューすることが大事です。 早く開発を進めたくなりますが、最初にスキルやインプットに問題がないかを確認するのが、結局一番の近道です。
まとめ
今回はClaude Codeを使ったアプリ開発、SIerとして実際の現場で使っている開発プロセスについて紹介しました。
バイブコーディングでも確かにアプリを作ることはできます。ですが、今回のようにドキュメントを整備して、CLAUDE.mdやSkillsでAIの動作を定義してやることもめちゃくちゃ大事です。
アプリのソースコードだけじゃなく、こういった周辺も整備しておくことで：
- クライアントに仕様を聞かれても「設計書通りに実装しているので、この設計書の記載通りです」と答えられる
- 新しいメンバーが来ても開発プロセスを説明して、後のメンテナンスを任せることができる
こういった状況を作れて初めて「このアプリは大丈夫です」と言えると思います。
ただ、今回紹介したやり方がもちろん唯一の正解ではありません。設計書に何を書くか、Skillsをどう定義するか、どのMCPを使うか――プロジェクトの規模やチームのメンバースキルによっても全然変わってきます。
今回紹介したコードや設計書、スキルなどは全てGitHubに公開していますので、興味のある方はぜひ見てみてください。