AIを信じるな、設計を信じろ:エージェント乱立時代の爆死回避術

著者: ClaudeMix Team |

Stripeエージェントが「実装完了」と報告してきたコードを確認すると、SSoT違反(spec.yamlではなくコード内にハードコード)が大量に含まれていた。「動いているコード」を全削除し、設計書を座標として再実装することで汚染を排除した。

症状

  • 使用スタック: Remix v2 / Cloudflare Pages・Workers / Stripe / Claude Code + VSCode Stripe拡張
  • 登場するエージェント: VSCode Stripeエージェント(決済実装、Stripe公式ベストプラクティス準拠)、Claude Code(プロジェクト全体の監査・統括)
  • VSCode Stripeエージェントが「実装完了」と報告。Payment Element方式(フロントエンドにStripe UIを埋め込む、公式ドキュメント通りの実装)だったが、プロジェクトの設計書とは異なる方式だった

原因

直感を確かめるため、Claude Codeに監査を依頼した。

差分のあるファイルからストライプ関係の実装を割り出して、どんな実装がされているのか確認して
問題点・懸念点:
1. spec-yamlなし - SSoT違反。設計ファイルが未作成
2. 金額ハードコード - ¥1,000がcheckout.tsxに直接記述
3. スタイル不整合 - style jsx使用(プロジェクト標準はユーティリティCSSフレームワーク)
4. テストなし - TDDプロセス未実施

根本原因は「正解」の衝突だった。Stripeエージェントは「Stripeのベストプラクティス」に従っていたが、それはプロジェクトの設計書とは異なる「正解」だった。

# 設計書で定義していた方針
stripe_integration:
  method: "Checkout Session"  # Payment Elementではなく
  implementation: "Server-side only"  # フロントエンド実装なし
  reason: "保守性を優先。5年後も理解できるシンプルさ"

Stripeエージェントはプロジェクトの設計書を読まない。各エージェントは自分の「ベストプラクティス」を押し付ける。人間が明示的に監査しないと、設計との乖離は発見できない。

解決策

汚染されたコードを全削除した。

【削除したファイル】
- app/lib/stripe.ts
- app/routes/checkout.tsx
- app/routes/webhook.tsx
- app/components/checkout/CheckoutForm.tsx
- app/components/checkout/ ディレクトリ全体

修正ではなく全削除を選んだ理由は、Payment Element方式とCheckout方式は設計思想が根本から異なり、「修正」で埋められる差ではないため。構造が違うコードを修正して使い回すのは、癌細胞を移植するのと同じ。

全削除の判断基準

【全削除すべき場合】
- 設計思想が根本から異なる(例: Payment Element vs Checkout)
- 修正するより書き直す方が早い
- 汚染されたコードを残すと、後続の実装も汚染される

【修正で対応できる場合】
- 変数名やスタイルの不整合
- 細かなロジックの調整
- テストの追加

設計書に従って再実装した。

// app/routes/subscribe.tsx
export async function action({ request, context }: ActionFunctionArgs) {
  const stripe = new Stripe(context.env.STRIPE_SECRET_KEY);
  const session = await stripe.checkout.sessions.create({
    mode: "subscription",
    payment_method_types: ["card"],
    line_items: [{ price: context.env.STRIPE_PRICE_ID, quantity: 1 }], // 金額はenv経由(ハードコードしない)
    success_url: `${context.env.APP_URL}/subscribe/success`,
    cancel_url: `${context.env.APP_URL}/subscribe/cancel`,
  });
  return redirect(session.url!); // Stripeの決済ページにリダイレクト。フロントエンドにUIを埋め込まない
}
観点 Checkout方式(採用) Payment Element方式(却下)
フロントエンドの複雑さ なし UIコンポーネント必要
PCI DSS準拠 Stripe側で完結 追加考慮が必要
5年後の保守性 高い(シンプル) 低い(依存関係多)
カスタマイズ性 低い 高い

学び

  • 【設計書という正解の座標】: 実装前に「採用する方式・不採用の方式と理由・実装場所」を明記した設計書があったことが、AIの暴走を止められた最大の要因。詳しすぎると人間が疲弊し、粗すぎるとAIが「どっちでもいい」と解釈して暴走する
  • 【監査役としてのAI】: 実装したエージェント自身に「問題ない?」と聞いても無意味。別のAI(Claude Code)に「差分から実装を割り出して設計書との整合性を確認して」と依頼する、独立した監査フローが必要
  • 【引き算の意思決定】: 設計思想が根本から異なるコードは「もったいない」で修正せず、迷わず全削除する。この判断の先送りが、後続の実装まで汚染を広げる
  • 続くStripe本番審査では、設計書を守って実装しても審査プロセスという別の壁があった