Stripe Integration Skill

Stripe決済連携の実装・デバッグ・テストのためのスキル。

When to Use This Skill

• Stripe決済機能を新規実装・改善する時
• Webhook処理でエラーが発生した時
• サブスクリプション管理を実装する時
• 決済フローのデバッグが必要な時
• Stripe CLIでローカルテストする時
• 課金プランの変更を実装する時

主要ファイル

役割	ファイル
Stripeクライアント	src/lib/stripe/client.ts
サブスクリプション	src/lib/stripe/subscription-service.ts
Webhook処理	src/app/api/stripe/webhook/route.ts
ゲストチェックアウト	src/app/api/stripe/guest-checkout/route.ts
決済アクション	src/app/actions/payment.ts

Webhook イベント

イベント	処理内容
checkout.session.completed	支払い完了 → プラン更新
customer.subscription.updated	サブスク更新 → 期間更新
customer.subscription.deleted	サブスク解約 → Freeに戻す
invoice.payment_failed	支払い失敗 → 通知

ローカルテスト

Stripe CLI でWebhook転送

stripe listen --forward-to localhost:3000/api/stripe/webhook

# 別ターミナルでイベント送信
stripe trigger checkout.session.completed

テスト用カード番号

カード番号	用途
4242424242424242	成功
4000002500003155	3Dセキュア認証
4000000000009995	残高不足
4000000000000341	カード拒否

環境変数

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

プラン設計

SSOT: src/lib/stripe/config.ts の PLAN_CONFIGS を参照。 プラン名・価格・制限値はすべてこのファイルで一元管理される。

import { PLAN_CONFIGS, type PlanName } from "@/lib/stripe/config";
// PLAN_CONFIGS.free / PLAN_CONFIGS.standard / PLAN_CONFIGS.pro

DBテーブル

-- profiles.stripe_customer_id: Stripe顧客ID
-- user_plans: プラン情報
-- stripe_events: Webhook履歴（重複防止）

よくある問題

1. Webhookシグネチャ検証失敗

• 原因: rawBodyが必要
• 対策: route.ts で request.text() を使用

2. 二重課金

• 原因: Webhookの重複配信
• 対策: stripe_events で idempotency チェック

3. サブスク状態の不整合

• 原因: Webhookミス
• 対策: 定期的な stripe.subscriptions.retrieve で同期

Evidence Doc（変更証跡） (CRITICAL)

Stripe関連ファイルを変更するPRには必ずEvidence Docが必要。 CIの stripe-evidence-check.yml が自動チェックする。

必要なもの

1. docs/evidence/stripe-change-evidence-YYYYMMDD-<説明>.md を作成
2. PR本文に ## Evidence Doc セクションを追加しファイル名を記載

手順

# 1. テンプレートからコピー
cp docs/evidence/stripe-change-evidence-TEMPLATE.md \
   docs/evidence/stripe-change-evidence-$(date +%Y%m%d)-<説明>.md

# 2. 必須セクションを記入
#    §1 変更概要, §4 リスク評価・ロールバック手順, §5 検証結果, §7 承認

# 3. 承認欄のプレースホルダを実際の値に置換
#    __APPROVER_GH_HANDLE__ → @YourHandle
#    __APPROVAL_DATE__ → 2026-02-18

# 4. PR本文に追記
## Evidence Doc
- 変更証跡: [stripe-change-evidence-YYYYMMDD-xxx.md](docs/evidence/stripe-change-evidence-YYYYMMDD-xxx.md)

CIが検出するファイルパス

src/lib/stripe/**
src/app/api/stripe/**
src/app/actions/payment.ts
docs/policies/billing-tax-invoice-policy.md
docs/configuration/stripe-dashboard-setup.md
docs/runbooks/stripe-webhook-recovery.md

上記を触るPRでEvidence Docリンクがなければ CIがfailする。

AI Assistant Instructions

このスキルが有効化された時:

1. 環境確認: Stripe環境変数が設定されているか確認
2. テストモード確認: sk_test_ / pk_test_ を使用しているか確認
3. Webhook検証: シグネチャ検証が正しく実装されているか確認
4. 冪等性確認: 二重課金防止の実装を確認
5. Evidence Doc確認: Stripe関連ファイル変更時にEvidence Docを作成・リンクしたか確認

Always:

• テスト用カード番号（4242...）を使用する
• Webhookはidempotencyチェックを実装する
• rawBodyで署名検証する
• stripe_events テーブルで重複防止する
• Stripe関連変更時はEvidence Docを作成する

Never:

• 本番キー（sk_live_）をコードにハードコードしない
• Webhookシグネチャ検証をスキップしない
• ユーザー入力を検証せずにStripe APIに渡さない
• Evidence Docなしで決済関連PRを作成しない