I had the opportunity to speak at the community event “JP_Stripes 福岡Vol.12 - サービスを支える決済の裏側” (JP_Stripes Fukuoka Vol.12 - Behind the Scenes of Payment Systems Supporting Services) held in Fukuoka.

This article shares the content of my presentation along with the materials.

Presentation Content

Below are excerpts from the presentation slides Speculative Implementation × AI で切り拓く Stripe API 移行実践記 (Pioneering Stripe API Migration with Speculative Implementation × AI).

🧭 Presentation Overview

For migrating Stripe API from Acacia → Basil, we attempted Speculative Implementation (proactive multiple implementations) leveraging AI.

Parallel implementation with AI achieved the following 👇

• Early discovery of constraints not documented
• Accelerated selection of optimal migration approach
• Safe handling of Breaking Changes

⚙️ Background: Stripe API Migration Challenges

• 🧩 Complex compatibility across API versions
• 🧠 Risks are hard to identify just by reading documentation
• 🔁 Many options: “feature flag,” “env variables,” “full switch,” etc.

🤖 What is Speculative Implementation?

A method where AI generates multiple implementation patterns, discovering constraints by actually running them

• A development approach unique to the AI era where code generation costs are low
• Proceeds in the order of “implementation → discovery → design” rather than “design → implementation”

🔍 Three Approaches Validated in Parallel

1. Feature Flag Approach
   • 👉 Gradually migrate to Basil
   • ⚠️ Discovered that SDK doesn’t support multiple API versions simultaneously!
2. Environment Variable Switch Approach
   • 👉 Dynamically control with STRIPE_API_VERSION
   • 🧠 High explicitness in configuration, but also increased management cost
3. Full Migration Approach
   • 👉 Batch switch to Basil
   • 💪 Reliable and easy to maintain

🧩 Learnings from Implementation

Discovery	Details	Learning
SDK Constraints	Cannot use multiple API versions with the same SDK	Abandoned gradual migration for full migration
Subscription Structure	subscription.current_period_* → subscription.items[0].*	Determined that DB schema changes are unnecessary
Metering Logic	AI organized complex aggregation logic	Accelerated understanding in codebase

📈 Simplified Billing Implementation with Basil

• New API greatly simplified Usage-based Billing
• Clear separation of responsibilities between metering and billing logic

📚 Ideal Division of Labor: AI × Documentation

Role	Responsibility	Content
🤖 AI	Code Generation	Convert documentation to code and present multiple options
👩‍💻 Human	Decision Making	Judge business requirements, environment dependencies, and switching strategies

🔑 Key to Success: Structured documentation design that AI can understand

🧭 Excellence of Stripe Documentation

• ✅ Breaking Changes are listed
• ✅ Before / After code examples
• ✅ Detailed scope of impact for each API
• ✅ Explicit migration paths

→ Factors that enabled AI to understand accurately and generate correct code

🧠 Learnings and Future Implications

1. Make internal documentation AI-friendly too
2. Add “AI comprehensibility” to external service selection criteria
3. Evolution of development process
   • “Read → Speculative implementation → Feedback → Decision making”

🏁 Summary

• Speculative Implementation × AI enabled verification and visualization of Stripe API migration risks through code
• Stripe’s high-quality documentation supported the success
• Development in the AI era is “dialogue between documentation and code”

✨ Achieved safe and fast migration through collaboration between AI and humans ✨

🔗 References

• Upgrading Stripe API version with AI-powered Speculative Implementation - Giselle
  • Basil | Stripe Changelog
  • Acacia | Stripe Changelog
  • Adds subscription item-level billing periods and removes subscription-level periods | Stripe Documentation
• ROUTE06 | AI-Driven Development with Giselle, Liam & Acsim
• Giselle: AI App Builder
  • GitHub: giselles-ai/giselle: Giselle: AI App Builder. Open Source.

Final Notes

Thank you to everyone who attended, the Stripe team, and especially Mr. Okamoto from DigitalCube for giving me this opportunity to speak!

That’s all from the Gemba, where we want to fully leverage Stripe and AI in our development.

References

• JP_Stripes 福岡Vol.12 - サービスを支える決済の裏側 - connpass
• Speculative Implementation × AI で切り拓く Stripe API 移行実践記 - Speaker Deck