0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Codeに本番SaaSを「監査→リファクタ→機能追加」まで任せてみた ― 個人開発アプリ健全化の全記録

0
Posted at

はじめに

個人開発でワイン・日本酒のセラー管理アプリ「Cellar Note」を運営しています。Next.js + Supabase + Cloudflare Workers + Stripe + Gemini API という構成の、月額¥400のFreemium SaaSです。

このアプリは開発初期からClaude Code(AI支援開発)で作ってきました。機能追加を繰り返し、途中でVercelからCloudflareへホスティングを移行し……と走り続けた結果、コードベースには移行の残骸・デッドコード・コピペの重複・そして本物のセキュリティホールが溜まっていました。

本記事は、この「動いてはいるが健全ではない」本番アプリを、Claude Codeを使って監査→リスク順リファクタ→AI機能追加まで一気通貫で健全化したプロセスの記録です。AIにコードを書かせている人なら誰でも遭遇する問題と、その対処の型を共有します。

対象読者:

  • Claude Code / AIエージェントで個人開発している人
  • 「AIに書かせたコード、そろそろヤバい気がする」と感じている人
  • Supabase + Stripe構成のFreemiumアプリを運営している人

大原則:いきなり「きれいにして」と頼まない

最初にやりがちな失敗は、AIに「コードをきれいにリファクタして」といきなり頼むことです。これをやると、AIは動いているコードまで大胆に書き換え、本番アプリでは高確率で何かが壊れます。

そこで診断と治療を分離しました。医者がいきなり手術しないのと同じで、まず監査レポートだけを書かせます。

実際に使ったプロンプトの骨子がこちらです。

プロジェクト全体を監査して、以下の観点でレポートを作成してください。
コードの修正はまだしないでください。レポートのみです。

## 監査観点
### 1. インフラ移行の残骸
- Vercel固有の設定・コードが残っていないか
- ハードコードされた旧URLはないか
### 2. 未使用コード・デッドコード
### 3. 一貫性の問題
- DBクライアント初期化方法のばらつき
- エラーハンドリングのパターンのばらつき
### 4. セキュリティ・パフォーマンス
- APIルートの認証チェック漏れ
- IDORの可能性(他人のIDを指定してアクセスできるAPIがないか)
### 5. 型安全性

## 出力形式
refactoring-report.md に優先度(高・中・低)付きでまとめてください。

ポイントは3つあります。

  1. 「修正するな」と明示する ― これがないとAIは親切心で直し始めます
  2. 観点を列挙する ― 「問題を探して」だけだとAIの得意分野に偏ります。過去の開発経緯(移行・機能変更)を知る人間が観点を与えることで、網羅性が上がります
  3. 優先度を付けさせる ― 後のバッチ分割の材料になります

監査で出てきた「本物の問題」トップ3

約5,300行のコードベースから、優先度「高」6件を含む36件の指摘が出ました。中でも刺さったものを紹介します。

1. robots.txtの競合でSEO設定が丸ごと無効化されていた

public/robots.txt(Vercel時代の遺物・旧URLのサイトマップ入り)と src/app/robots.ts(新しい設定)が両方存在していました。Cloudflare Workers(OpenNext)では静的アセットがWorkerより先に配信されるため、本番で配信されていたのは旧Vercel URLを指す古いrobots.txt。Search Consoleにサイトマップを送信して満足していましたが、クローラーへの案内は壊れたままでした。

インフラ移行をしたら「同じパスを2箇所が主張していないか」を確認する。これは移行チェックリストに入れるべき項目でした。

2. Freemiumの本数制限がクライアント側チェックのみだった

無料プランは50本まで、という制限をReactコンポーネント内のif文だけで実装していました。SupabaseはanonキーとRLSで直接INSERTできる構成なので、ブラウザのコンソールから制限を無制限に回避できる状態です。

RLSは「誰の行を触れるか」は守れますが「何行まで」は守れません。行数制限のようなビジネスルールの最終防衛線はDBトリガーです。

CREATE OR REPLACE FUNCTION public.check_bottle_limit()
RETURNS TRIGGER AS $$
DECLARE
  bottle_count INTEGER;
  premium BOOLEAN;
BEGIN
  SELECT is_premium INTO premium FROM public.profiles WHERE id = NEW.user_id;
  IF premium IS TRUE THEN
    RETURN NEW;
  END IF;
  SELECT COUNT(*) INTO bottle_count FROM public.bottles WHERE user_id = NEW.user_id;
  IF bottle_count >= 50 THEN
    RAISE EXCEPTION 'FREE_PLAN_LIMIT_REACHED';
  END IF;
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

クライアント側のチェックは「善良なユーザー向けのUX」として残し、アプリ側ではこの例外メッセージを拾って日本語のアップグレード案内に変換しています。

3. Stripe Webhookが失敗時に200を返していた

決済完了イベントの処理でDB更新に失敗しても { received: true, error: ... } をHTTP 200で返していました。Stripeは200を受け取るとイベントを再試行しません。つまり「お金は払われたのにPremiumが付与されないまま、誰も気づかない」が起こり得る実装でした。

Webhookの鉄則は「処理に失敗したら5xxを返して再試行させる」です。Stripeは最大3日間再試行してくれるので、一時的なDB障害なら自動回復します。

リスク順のバッチ分割

36件の指摘を一気に直させるのは危険です。リスクの異なる変更を1コミットに混ぜると、問題発生時の切り分けとrevertが地獄になるためです。次の4バッチに分割しました。

バッチ 内容 リスク
1 優先度「高」6件(SEO・制限回避・決済ロスト) 実害に直結、最優先
2 削除候補の一掃(ファイル・npmパッケージ) 低(消すだけ)
3a 機械的な掃除(デバッグログ・リネーム・文言) 低(1ファイル完結)
3b 構造の共通化(ナビ・型・フック統合) 高(動くものを壊し得る)

バッチ2を3より先にやるのは、削除で消えるコードを共通化の対象から外せるからです。逆順だと「共通化した直後に削除」という無駄が発生します。

結果として、バッチ2だけで約2,500行の削減(未使用ファイル6件、create-next-appの残骸、実装完了済みの指示書アーカイブ、未使用npmパッケージ5個)。全バッチ合計で約3,000行減りました。

AIへの指示に「脱出口」を作る

リスクの高いバッチ3b(構造の共通化)では、指示文に必ず中止条件と報告義務を仕込みました。

- 型エラーが解消できないファイルがあれば、そのファイルは any のまま残して
  最後に報告すること(無理に as で握りつぶさない)
- PdfTemplate はスタイルの形が違う場合、色定数の参照だけ共通化して
  レイアウトは触らないこと
- 「見た目や挙動が変わってしまう」と判断した箇所は
  変更せずスキップして最後にまとめて報告してください

これが効きました。Claude Codeからの完了報告には次のようなスキップ判断が含まれていて、どれも妥当でした。

page.tsx は usePremium 未適用 ― サーバーコンポーネントのためフックが使えません。クライアント化するとバナー表示がちらつく挙動変化が出るため、サーバー側SELECTのまま残しました。

脱出口を作らないと、AIは指示を完遂するために型エラーを as any で握りつぶしたり、見た目が変わる変更を強行したりします。「無理なら止まって報告せよ」を指示に入れ、報告で必ず回収する。この往復がAIとの分業の要だと感じています。

もうひとつ、PDFテンプレートのレイアウトを聖域にしたのには理由があります。PDFの座標は過去に実機確認を何往復もして「実測で正解を出した」部分で、ビルドは通るのに出力が崩れるというビルドでは検知できない劣化が起こり得るからです。テストで守られていない見た目は、リファクタで最も慎重に扱うべき領域です。

おまけの収穫:解約バグの根本原因は「0行UPDATE」だった

リファクタ後、「サブスク解約したのに翌月もPremiumのままだった」という不具合を調査しました。ここでも診断→治療の順で、まず調査だけをさせたところ、根本原因が判明します。

Supabase(PostgREST)のUPDATEは、条件に0行しかマッチしなくてもエラーになりません。

解約Webhookは stripe_subscription_id でユーザーを特定していましたが、IDの保存漏れや再購読でのID変化があると、UPDATEは0行マッチ→静かに成功→200返却→Stripeも「配信成功」と記録。誰も気づかないまま解除処理だけが空振りしていました。

修正は2点です。

// 更新行数を検証し、0行なら500でStripeに再試行させる
const { data } = await admin
  .from('profiles')
  .update({ is_premium: false, stripe_subscription_id: null })
  .eq('stripe_customer_id', subscription.customer)
  .select('id')  // ← これがないと更新行数が分からない

if (!data || data.length === 0) {
  console.error('[stripe-webhook] no matching profile')
  return NextResponse.json({ error: 'not found' }, { status: 500 })
}

あわせて customer.subscription.updated も購読し、status が active/trialing 以外なら解除するようにしました。解約イベントだけに反応する設計だと「カード期限切れ→unpaid」のルートで逆向きの穴(払っていないのに有料機能が使える)が残るためです。特定イベントに反応するのではなく、statusを正として同期するのがWebhook実装の定石です。

ちなみに検証は、Stripeをテストモードに切り替えて「決済→Dashboardから即時キャンセル」のフルサイクルで行いました。期間終了時解約を待つと1ヶ月かかりますが、即時キャンセルなら customer.subscription.deleted をその場で発火させられます。

健全化してから機能を作る

土台がきれいになってから、Gemini APIを使った新機能「AIソムリエ」(セラー内の未開封ボトルから気分・料理に合う1本を推薦)を実装しました。LLM機能で意識した設計を2つだけ紹介します。

銘柄名ではなくIDで返させ、サーバー側で実在チェックする。 LLM最大のリスクは「もっともらしい創作」です。銘柄名で返させるとセラーにない架空のワインを推薦してきます。プロンプトでID返却を強制し、さらにレスポンスのIDがボトルリストに実在するかをコードで検証する二段構えにすると、ハルシネーションが起きてもユーザーに届く前に落ちます。

必ず以下のJSON形式のみで返してください:
{"recommendations":[{"bottle_id":"リスト内のid","reason":"推薦理由を80文字以内で"}]}
重要:bottle_idは必ず提供されたリスト内のidをそのまま使うこと。
リストにないボトルを創作しないこと。

AIに渡すデータは判断に必要な最小限に絞る。 ボトルの全カラム(写真URL・タイムスタンプ等)を送っても推薦品質は上がらず、トークンコストとプロンプトインジェクションの面積だけが増えます。7フィールドに圧縮して送っています。リクエストボディも同様に、想定フィールドのみ抽出するホワイトリスト方式です。

まとめ:AIと本番アプリを運用するための5原則

今回のプロセスで手に入れた型をまとめます。

  1. 診断と治療を分離する ― いきなり修正させず、まず監査レポート。人間は観点を与え、優先順位を決める役
  2. リスク順にバッチを分割する ― 実害系→削除系→機械的掃除→構造変更。異なるリスクを1コミットに混ぜない
  3. 指示に脱出口を仕込み、報告で回収する ― 「無理ならスキップして報告」がないと、AIは型エラーを握りつぶしてでも完遂しようとする
  4. ビジネスルールの最終防衛線はDBに置く ― クライアントのチェックはUX、RLSは行の所有権、行数や課金制限はトリガー
  5. 「静かな失敗」を疑う ― 0行UPDATE、Webhookの200返し、robots.txtの競合。エラーが出ない失敗こそ本番で長生きする

AIコーディングの弱点は「書けないこと」ではなく、書けてしまった大量のコードの負債が見えなくなることだと思います。監査→バッチ→脱出口のループは、その負債を定期的に棚卸しする仕組みとして、今後も回していく予定です。


アプリ本体はこちらです。ワイン・日本酒を記録する方はぜひ。

0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?