JP_Stripes Fukuoka Vol.12 Presentation Report ~ Pioneering Stripe API Migration with Speculative Implementation × AI
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
- Feature Flag Approach
- 👉 Gradually migrate to Basil
- ⚠️ Discovered that SDK doesn’t support multiple API versions simultaneously!
- Environment Variable Switch Approach
- 👉 Dynamically control with
STRIPE_API_VERSION - 🧠 High explicitness in configuration, but also increased management cost
- 👉 Dynamically control with
- 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
- Make internal documentation AI-friendly too
- Add “AI comprehensibility” to external service selection criteria
- 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
- ROUTE06 | AI-Driven Development with Giselle, Liam & Acsim
- Giselle: AI App Builder
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.