火曜日の午前2時、課金システムがユーザーに2倍の料金を請求していることに気づきました。そのバグは本番環境で6時間も放置されていました。その日の午後、Claude Codeが支払い照合ロジックを生成し、私はそれをレビューし、テストし、デプロイしました。コードは完璧に見えました。すべてのテストをパスしていました。しかし、根本的に壊れていたのです。
これは、AIコーディングアシスタントを使って、274のAPIルート、46のデータベースモデル、10万行以上のコードを持つLemonDataを構築した物語です。よくある「AIがいかに生産性を高めるか」という美化された話ではありません。失敗、午前3時のデバッグセッション、そしてAI支援開発が本当に良いアイデアなのか疑問に思った瞬間を含んだ、リアルな物語です。
AI支援開発の理想と現実
AIコーディングアシスタントの売り文句は魅力的です。やりたいことを説明すれば、AIがそれを書き、人間がレビューしてデプロイする。理論上、一人の開発者がチーム全体の仕事をこなせるようになります。
実際はどうだったか？最初の2週間は素晴らしいものでした。Claude Codeは私のコードベースを理解し、完全な機能を生成し、ファイル間をまたいでリファクタリングを行いました。これまでのキャリアでかつてないほどのスピードで開発を進めていました。次々と課題を解決していくドーパミンは中毒性がありました。
しかし、次第に亀裂が見え始めました。
同じ関数が3つの異なるファイルに、わずかに異なる実装で現れました。設定値がランダムな場所にハードコードされていました。型定義がパッケージ間で矛盾していました。コードベースは急速に成長していましたが、同時に「なぜか動くが理由はわからない」コードの迷宮になりつつありました。
そして、あの課金バグです。Claudeは、一見完璧に見える照合関数を生成しました。しかし、非同期の支払い確認フローにおけるレースコンディション（競合状態）を考慮していませんでした。私が明示的に伝えていなかったため、AIはそのエッジケースを知る由もありませんでした。また、一部AIによって生成されたテストスイートも、それをカバーしていませんでした。
壊れ続けた7つのパターン
Claude Codeで構築を始めて1ヶ月後、私はリストを作り始めました。バグそのものではなく、パターンのリストです。同じような失敗が繰り返されており、それはClaudeのせいというより（少なくとも完全には）、AIが「明日動くコード」ではなく「今動くコード」を最適化した結果として予測可能なものでした。
1. 一貫性の問題
Claudeは、作業しているファイルや直前に見た例、あるいは単なるランダムなバリエーションによって、同じロジックを異なる方法で実装することがありました。あるAPIエンドポイントは{ data: users }を返し、別のエンドポイントは{ users }を返すといった具合です。どちらも動作はしますが、互いに一致していません。デバッグはさながら考古学のようになりました。
2. コピー＆ペーストの問題
コードを複製する方が早く、既存の機能を壊すリスクがないのであれば、なぜAIが共有ユーティリティを作成する必要があるでしょうか？既存の機能に似た新機能を依頼するたびに、リファクタリングされた共有ソリューションではなく、新しい実装が提供されました。3週間後には、5つの異なる「通貨フォーマット」関数がコードベースに散在していました。
3. 型の乖離の問題
新しいステータス値が1つのファイルには追加されるが、enum定義には追加されない。あるフィールドがAPIレスポンスではオプションだが、フロントエンドの型では必須になっている。TypeScriptはこれらの一部をキャッチしましたが、意味的な不一致、つまり型は技術的に正しくても論理的に矛盾しているケースまでは防げませんでした。
4. 設定の散乱の問題
データベースのURL、APIキー、フィーチャーフラグ、レート制限などが、その時のタスクに都合の良い場所に配置されてしまいました。環境変数にあることもあれば、設定ファイルにあることも、ハードコードされていることもありました。ある値が定義されているすべての場所を見つけ出すのは、宝探しのようになりました。
5. テストカバレッジの幻想
AIが生成したテストは、正常系（ハッピーパス）を徹底的にテストする一方で、エッジケースを完全に見逃す傾向があります。課金バグは完璧な例です。テストスイートは通常の支払いフローを美しくカバーしていましたが、2つの支払い確認が同じミリ秒以内に到着した場合に何が起こるかは一度もテストしていませんでした。
6. サイレントエラーの問題
Claudeは、例外を飲み込んでしまうcatch (error) { console.log(error) }ブロックを追加することがありました。開発中、エラーはコンソールに表示されるため問題ないように見えます。しかし本番環境では、重大な障害が静かにログに記録され、そのまま忘れ去られていきました。
7. ドキュメントの欠如
Claudeは優れたコードコメントを書きます。しかし、優れたアーキテクチャドキュメントは書きません。関数が何をするかは説明できますが、なぜシステムがそのような構造になっているのか、あるいはどのような制約が特定の設計決定につながったのかを説明することはできません。
CLAUDE.mdという解決策
転機は3週目に訪れました。プロジェクトのルートディレクトリに、Claudeが知っておくべきすべての規約、制約、アーキテクチャ上の決定事項を記述したCLAUDE.mdを作成したのです。
これは人間向けのドキュメントではなく、AIのためのドキュメントです。
## API Response Format
Always use: { success: true, data: T } or { success: false, error: string }
Never return raw data without the wrapper.
## Currency
Internal storage: USD. Display: formatCurrency(amount, currency, rate).
Never hardcode exchange rates. Never store CNY directly.
## Error Handling
Never use catch(e) { console.log(e) }.
Always use the logger: logger.error('context', { error }).
効果は絶大でした。Claudeは一貫して規約に従い始めました。ルールに違反するコードを生成したときも、CLAUDE.mdの特定の行を指摘するだけで、自己修正するようになりました。
しかし、CLAUDE.mdだけでは不十分でした。自動化された強制力が必要でした。
セーフティネットの構築：AI生成コードのためのCIゲート
私たちは、従来のコードベースでは過剰に思えるようなゲートを備えたCIパイプラインを構築しました。これらは、AIが生成したバグがユーザーに届く前にキャッチするために存在します。
- モノレポ全体にわたる型チェック
- 重複した実装が存在しないことを検証するSSOT監査
- データベースのenumとTypeScriptのenum間の同期チェック
- APIレスポンス形式の検証
- 課金、権限、認証コードのためのセキュリティゲート
重要な洞察はシンプルです。Claudeは増幅器であり、代替品ではありません。生産性を増幅させますが、間違いも増幅させます。強力な規約がなければ、Claudeは独自の規約を作り出し、それらは一貫性のないものになります。自動チェックがなければ、Claudeのバグは人間が作るバグよりも早く本番環境に到達してしまいます。
あの課金バグはもう起こり得ません。それはClaudeが賢くなったからではなく、パイプラインが非同期のレースコンディションの明示的な処理を要求し、支払いフローにおける適切なロックをチェックするゲートによって検証されるようになったからです。
「AIネイティブ開発」の本当の意味
LemonDataが「AIネイティブ・インフラストラクチャ」であると言うとき、それは既存の製品にAI機能を追加したという意味ではありません。開発プロセス全体が、AIコーディングパートナーと協力するという現実に合わせて形作られていることを意味します。
私たちのドキュメントは、人間のチームメイトなら推測できるような文脈をClaudeが明示的に必要とするため、通常よりも詳細です。私たちの型システムは、Claudeが曖昧さを利用してしまうため、必要以上に厳格です。私たちのCIパイプラインには、AI生成のバグをキャッチするためのゲートがあります。
その結果、私がこれまで関わってきた多くのコードベースよりも、実はメンテナンスしやすいものになりました。AIが人間より優れたコードを書くからではなく、AI支援開発のために、通常はシニアエンジニアの頭の中にしかない規約やチェックをすべて明文化せざるを得なかったからです。
AIネイティブという哲学についての詳細は、What Is AI Native?をご覧ください。
より実践的な「どうやってこれを始めるか」については、agent-first API design guideとmigration guideの2つが最適です。一方はAPIの形状について説明し、もう一方はワークフローがモデルの切り替えを前提に設計されていれば、チームがいかに早く方向転換できるかを示しています。
AIコーディングアシスタントで開発するエンジニアへの教訓
もしあなたがClaude Code、Cursor、あるいはその他のAIコーディングアシスタントでプロジェクトを始めるなら：
CLAUDE.mdを、私のように3週目ではなく、初日に作成してください。- 規約の強制を自動化してください。AIがルールを覚えていることに頼ってはいけません。
- AIのコードは、ジュニア開発者が書いたものとしてレビューしてください。高速で有能ですが、文脈が欠けています。
- エッジケースは手動でテストしてください。AI生成のテストは正常系をカバーしますが、レースコンディションはカバーしません。
- 設定は最初から一元化してください。散乱問題は急速に悪化します。
- 厳格なTypeScriptを使用してください。これが型の乖離に対する最善の防御策です。
- CIゲートを早期に構築してください。最初の1週間で元が取れます。
もう一度やるか？
もちろんです。ただし、CLAUDE.mdは3週目ではなく初日に作成します。そして、10倍の生産性向上には、間違いがもたらす結果も10倍になるということを忘れないようにします。
私たちが構築したプラットフォーム——300以上のAIモデル、統合API、多通貨課金、13言語の国際化——は、従来のチームであれば数ヶ月かかっていたでしょう。私たちはそれを30日でリリースしました。バグは現実にありましたが、開発スピードもまた本物でした。
AI支援開発は魔法ではありません。それは新しい種類のエンジニアリング規律です。そして、すべての規律と同様に、その制約を尊重する者に報いてくれます。
FAQ
一人の開発者で本当にClaude Codeを使ってプロダクションプラットフォームを構築できますか？
はい、ただし注意点があります。AIはコード生成とリファクタリングを驚異的なスピードでこなしますが、依然として強力なアーキテクチャ上の判断、自動化された品質ゲート、そしてすべてを注意深くレビューする規律が必要です。10倍のスピードには、注意を怠れば10倍速いバグも含まれます。
CLAUDE.mdとは何ですか？
CLAUDE.mdは、AIコーディングアシスタントが文脈を把握するために読み取るプロジェクトレベルの指示ファイルです。AIが従うべきコーディング規約、アーキテクチャ上の決定、制約事項が含まれています。AIのチームメイトのためのオンボーディングドキュメントと考えてください。
本番環境でのAI生成バグをどうやって防いでいますか？
自動化されたCIゲートが不可欠です。型チェック、SSOT監査、enumの同期検証、ドメイン固有のセキュリティゲートなどです。重要なのは、AIは生産性と間違いの両方を増幅させるため、その増幅された間違いをキャッチするための自動チェックが必要だという点です。
AI支援開発は課金や支払いシステムに適していますか？
はい、ただし細心の注意が必要です。支払いコードには、明示的なレースコンディションの処理、適切なロック、そして徹底的なエッジケースのテストが必要です。AI生成のテストは正常系に偏る傾向があるため、失敗シナリオや並行操作を手動でテストする必要があります。
LemonDataは、単一のAPIを通じて300以上のAIモデルへのアクセスを提供します。無料で開始して、1ドル分のクレジットでプラットフォームをお試しください。
