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本番審査では、設計書を守って実装しても審査プロセスという別の壁があった