Claudeとともにイベント用ウェブアプリを開発した記録

1. はじめに

チーム単位のオフラインイベントで行われる対抗活動をデジタル化するため、参加チームが仮想通貨で資源を購入して成果物を作り、リアルタイムで変動する条件に対応しながら得点を競うWebベースのアプリケーションを、1人開発体制で企画・実装しました。従来は紙の台帳と手計算で進めていた活動だったため、進行役のミスがそのまま得点に反映されたり、参加者が自分の資源状況をリアルタイムで確認できなかったりするという課題が明確にありました。こうした非効率を実際に経験した立場から、「この規模のシステムなら、1人でもきちんと作れるのではないか」という考えがプロジェクトの出発点となりました。

同時に個人的には、AIを単なる補助ツールではなく、設計・実装・デバッグの全工程にわたる開発パートナーとして活用した場合、実際にどこまで生産性を高められるのかを検証してみたいという目標もありました。企画からデプロイまでの全工程を1人で担わなければならない制約はむしろ、Claudeとの協業方法をさまざまな角度から試し、その効果をありのままに確認できる良い機会となりました。管理者向けダッシュボード、参加チームごとの資産管理、リアルタイムに近いイベント処理、多数の同時接続環境での安定性まで求められる、短いスケジュールの中では決して軽くない課題でした。

この記事では、プロジェクトの技術的な詳細よりも、この過程でClaudeをどのように開発パートナーとして活用したかに焦点を当てて整理します。企画から設計、実装、デバッグ、デプロイまでの全工程を1人で担わなければならない状況で、AIとの協業方法が実際の生産性にどのような影響を与えたのかを、実務の観点から共有します。

2. プロジェクト概要

フロントエンドにはReactとTypeScript、バックエンドにはNext.js API Routesベースのサーバーレス関数、データベースにはサーバーレスPostgreSQLを使用しました。デプロイプラットフォームにおけるサーバーレス関数数の制限という現実的な制約があったため、機能単位ではなくドメイン単位でAPIをまとめる設計を初期段階で確定しました。この設計に関する議論自体も、Claudeとの対話を通じて複数の案を比較しながら決定したものであり、その後のプロジェクト全体の構造を左右する重要な出発点となりました。

3. Claudeとの協業原則

今回のプロジェクトでClaudeは、コード自動補完ツールを超えて、設計の議論からデバッグ、リファクタリングまでをともに行う協業パートナーとしての役割を果たしました。何度も試行錯誤を重ねて整理した協業原則は、次のとおりです。

「完璧な答えを一度に得ようとするよりも、質問の精度を高めることに時間を使うほうが、結果的には速かった。」

振り返ってみると、Claudeを効果的に活用する鍵は、結局のところ「どれだけ具体的な文脈を提供できるか」にかかっていました。曖昧な依頼は曖昧な結果となって返ってきましたが、制約条件と既存のパターンを明確に示すほど、実務にすぐ反映できる成果物が得られました。これは単なるコツではなく、AIを開発プロセスに組み込む際に求められるコミュニケーション能力そのものが、新たな生産性要素になることを意味していました。

4. 実際の協業事例

4.1 設計に関する議論：構造変更の範囲をともに整理する

初期のデータモデルでは、1つの主体が所属情報と資産を同時に持っていました。しかし、実際の要件が具体化するにつれて、「誰が活動に参加するのか」と「誰が資産を所有するのか」を分離する必要が生じました。このような構造変更は、関連するすべての検索ロジックと権限体系に連鎖的な影響を及ぼします。そこでClaudeにすぐコードの修正を依頼するのではなく、まず「この変更が影響するファイルとロジックの一覧を一緒に整理してほしい」と依頼しました。その結果得られた一覧を基準に、1つずつ順番に反映していったことで、漏れや衝突なくマイグレーションを完了できました。この経験を通じて、AIに実行を任せる前に、まず「地図」を一緒に描く段階がいかに重要かを実感しました。

4.2 最新ライブラリへの対応：ドキュメントと実際の動作の隔たりを埋める

イベントの予約処理のために導入したスケジューリングライブラリが、ちょうどメジャーバージョンアップを経たことで、従来知られていた使い方と実際の動作が一致しない箇所がありました。このような場合は、エラーメッセージと使用中のバージョン情報をClaudeに一緒に提供し、公式ドキュメント上のAPIと実際の動作の違いを1つずつ確認しながら調整していきました。特に、トリガーの設定場所、キャンセル条件の指定方法、タイムゾーンの変換といった微妙でありながら致命的になり得る部分で、この方法が有効でした。最新技術を扱う際には、AIの学習時点と実際の最新バージョンとの間に隔たりがある可能性を認識し、エラーログとバージョン情報を積極的に共有することが、問題解決のスピードを大きく左右しました。

4.3 段階的なデバッグ：症状から始め、結論は後に出す

バグが発生したとき、すぐに「直して」と依頼するのではなく、症状をできるだけ具体的に説明し、原因の候補をともに絞り込んでから修正するという順序を守りました。特に非同期処理のタイミングやデータベースの制約条件に関するバグは、焦って解決策から適用すると、表面的な症状だけが消えて根本原因が残る場合が少なくありませんでした。まず原因を説明するよう依頼し、その説明が実際のログやデータと一致しているかを検証したうえで修正を進める方法により、再発率を大幅に下げることができました。

4.4 リファクタリングのタイミングを判断する：3回目の繰り返しで切り出す

機能が増えるにつれて、画面ごとに似たUIパターン（フィルター、ローディング処理、確認ダイアログ）が繰り返し登場しました。そのたびにClaudeと「このパターンを再利用可能なコンポーネントとして切り出すタイミングか」を一緒に判断しました。あらかじめ定めた基準は、「同じパターンが3つ目の画面に登場した瞬間」でした。この基準を対話に明確に含めるようにすると、Claudeもその後、似た依頼を受けた際に、まず再利用の可能性に言及するよう対応が変わりました。AIとの協業を重ねるほど、対話の中に蓄積された文脈そのものが、ある種のチームコンベンションのように機能することを確認できました。

4.5 コードレビューの観点からの協業：結果ではなく根拠を尋ねる

Claudeが提示したコードをそのまま適用するのではなく、なぜその構造を選んだのかを問い返すことを習慣にしました。たとえば、特定の検索ロジックで結合方式を提案されたとき、「この方式を選んだ理由は何か、代替案があるなら何か」と尋ねました。その回答の中から、より単純な代替案が見えてくることも少なくありませんでした。これは、実際の人間の同僚とのコードレビューで行う質問と大きく変わりませんでした。AIが提示した成果物をそのまま受け入れず、根拠を検証する手順を踏むことは、結果的にコードの品質だけでなく、開発者自身の理解度を維持するうえでも重要でした。

また、1つの大きな依頼を投げるのではなく、検証可能な単位に依頼を分割することも効果的でした。たとえば「取引所機能全体を作って」ではなく、「取引の登録 → 取引一覧の取得 → 取引の成立」のように段階を分けて依頼すれば、各段階で実際の動作を確認してから次の段階へ進めるため、エラーを早期に発見できました。成果物の規模と検証サイクルを合わせる感覚は、AIとの協業においても、人間同士の協業と同じくらい重要な能力であることを実感しました。

5. 数値で振り返るプロジェクト

完成したシステムの規模を数字で整理すると、次のとおりです。デプロイプラットフォームの制約内で、バックエンドAPIは11ファイルに集約し、その中で認証・組織・チーム・メンバー・資源・成果物・取引・組み合わせ・為替レート・イベントおよびログまで、合計11のドメインを処理しています。データベースのテーブルは20個で構成され、フロントエンドは管理者向け画面9種と参加者向け画面5種、合計14の主要画面に分かれています。開発期間中にデータモデルを2度大きく再設計したにもかかわらずスケジュールを守れたのは、変更範囲を先にリスト化し、1つずつ順番に反映していく協業習慣のおかげでした。

• APIファイル：11個（ドメイン単位で統合設計）

• 主要データテーブル：約20個

• 画面（View）構成：管理者9種、参加者5種

• データモデルの再設計：2回（① player-team-packageの所有構造を分離、②取引所の購入・売却方式から一方向の販売構造へ移行）

6. 学んだこと：AIとの協業から得た実務的な洞察

• 文脈の具体性が成果物の品質を左右する：同じ質問でも、制約条件と既存コードの文脈を併せて提供した場合と、そうでない場合とでは、成果物の品質に大きな差がありました。

• 実行よりも「地図を描くこと」が先：構造変更のように影響範囲が広い作業では、すぐに実行を依頼するのではなく、影響範囲を併せて整理する段階を設けることで、手戻りを減らせました。

• 対話は蓄積された資産になる：設計意図や意思決定の根拠を対話の中で明示的に整理しておくと、その後の関連作業でも繰り返し説明することなく、一貫した結果を得ることができました。

• 最新技術であるほど人による検証が必要になる：ライブラリのバージョンが新しいほど、AIの学習時点との乖離が生じる可能性があるため、エラーログと公式ドキュメントを併せて照合する習慣が重要でした。

• AIはツールというより協業相手に近い：コードを代わりに書いてくれるツールとして扱うよりも、意思決定の過程に参加させ、根拠を共に積み上げていくパートナーとして接したときのほうが、生産性の向上幅ははるかに大きくなりました。

7. おわりに

今回のプロジェクトを通じて得た最大の学びは、「AIに何を任せるか」よりも「AIとどのように対話するか」が、成果物の品質と開発スピードの両方を左右するという確信でした。具体的な文脈の提供、明確な制約条件の伝達、段階的な検証という3つの原則を守ったことで、1人開発の体制でも、定められた期間内に実際のサービス水準の成果物を完成させることができました。

これは特定のプロジェクトに限られた経験ではなく、今後の業務全般に適用できる協業の方法論だと考えています。AIを実務の開発パートナーとして活用する能力は、結局のところ、明確に考え、意思疎通を図る能力と直結しています。今回の経験をもとに、この方法をチーム業務全般にも段階的に適用していきたいと考えています。

PYS