We recently upgraded Giselle's Stripe integration from Acacia to Basil.
This migration experience reinforced the power of "speculative implementation" in AI collaboration and the critical importance of high-quality documentation that enables it.
Accelerating Decision-Making Through Speculative Implementation
The most effective approach in this migration was what we call "speculative implementation" using AI.
In traditional development, we read documentation, analyze impact, solidify design, and then begin implementation. However, with AI, the cost of code generation is extremely low, allowing us to immediately materialize our understanding into multiple concrete code patterns.
After having Claude Code and ChatGPT Codex read Stripe's Basil migration guide, we immediately had them implement three migration approaches in parallel:
- Gradual migration using feature flags
- Environment variable-based switching
- Complete migration
Early Discoveries Through Speculative Implementation
This speculative approach revealed critical constraints that we wouldn't have noticed from documentation alone.
SDK Compatibility Constraints The moment we implemented the feature flag version, we discovered that the Stripe SDK doesn't support multiple API versions in a single SDK version. This allowed us to immediately pivot from our initial gradual migration plan to a complete migration strategy.
Avoiding Database Changes For the change from
subscription.current_period_* to subscription.items[0].current_period_*, we
initially thought DB schema changes would be necessary. However, seeing the
helper function code generated by AI, we realized we could handle it with our
existing table structure, avoiding risky database migrations.
What was ambiguous in natural language specifications became clear when expressed as actual code, enabling more accurate decision-making. This is the true value of speculative implementation.
AI-Friendly Documentation as the Key to Success
Behind the success of this speculative implementation approach was Stripe's excellent documentation design.
Structured Information Architecture
Stripe's documentation had these characteristics:
- All breaking changes clearly listed
- Abundant Before/After code examples
- Detailed explanations of affected API endpoints
- Concrete migration paths presented
This structured information enabled AI to accurately understand the changes and generate technically correct code. Meanwhile, humans could focus on higher-level decisions like business impact and migration timing while validating the AI-generated code.
Ideal Division of Labor Between AI and Humans
The division of labor enabled by excellent documentation:
- AI: Accurately converting technical specifications to code, rapidly generating multiple implementation patterns
- Human: Business requirement decisions, environment-dependent configurations, migration strategy determination
For example, humans handled context-dependent decisions like Pro Plan identification logic (using environment variable PRICE IDs) and Blue/Green deployment timing, while pure technical implementation was delegated to AI.
Gratitude to Stripe and Implications for the Future
The smooth completion of this migration was thanks to Stripe's high-quality documentation.
The official migration guide organized information in a way that was understandable for both humans and AI. Detailed documentation was provided for individual breaking changes like subscription period changes and invoice reference changes.
Lessons Learned
From this experience, we gained important insights for future product development:
- Improving Our Own Documentation: Writing API documentation and READMEs in structured formats that AI can easily understand
- External Service Selection Criteria: Adding "documentation suitable for AI collaboration" as an evaluation criterion
- Evolution of Development Process: Establishing a workflow of "Documentation understanding → Speculative implementation → Early feedback → Accurate decision-making"
Summary
We successfully migrated Giselle's Stripe integration from Acacia to Basil by using AI-powered "speculative implementation" - generating multiple migration approaches in parallel to quickly discover technical constraints and make informed decisions. Stripe's well-structured, AI-friendly documentation was crucial to this success, demonstrating how quality documentation enables effective AI-human collaboration in modern software development.