Why we ditched OpenSpec for Amazon’s AIDLC workflow
Fast shipping with AI is easy. Shipping code that doesn’t implode two weeks later is the hard part.
Developer Peng Qian ran into this exact problem. After more than six months of AI-assisted coding, his team had cut feature development to half a day in many cases. Bug hunting, though, regularly stretched to several days. Speed up the build, break the quality. Classic tradeoff.
His solution: spend a month restructuring the team’s entire AI coding workflow, swapping out OpenSpec for Amazon AWS’s AIDLC framework. He reports code quality jumped significantly after the switch.
️ What Was Wrong with OpenSpec
Qian isn’t dismissing Spec Driven Development outright. SDD frameworks like OpenSpec work well on small solo projects. The problems surface when you scale up to multi-year projects with multiple teams.
He identified five specific failure modes:
- Command complexity kills adoption. OpenSpec’s documentation lists multiple commands (
explore,propose, plan agent) with overlapping use cases. Team members used them differently, and some abandoned the framework entirely and fell back to vibe coding. - Original intent disappears. Spec files capture decisions but not the reasoning behind them. When Qian reviewed another developer’s spec, he couldn’t tell why a user story or method was designed a certain way. Over time, even the original author forgets.
- Granularity is impossible to calibrate. Break requirements too coarsely and you get a demo. Break them too finely and development slows. Experienced developers know to iterate in small chunks, but getting that right consistently is genuinely hard.
- Docs drift from code. A developer adjusts the implementation mid-build but never calls an OpenSpec command again. The spec stays unchanged. Over many iterations, the documentation becomes meaningless.
- Team collaboration is an afterthought. OpenSpec assumes a single developer handles everything end to end. There’s no built-in mechanism for routing a requirements doc to a product manager, getting an architecture design reviewed, or enforcing approval gates between phases.
What AIDLC Actually Is
AIDLC stands for AI Driven Development Life Cycle. Think of it as the AI era equivalent of the traditional Software Development Life Cycle (SDLC), with two additions: dynamic workflows and dynamic team collaboration.
The framework maps to the same seven phases as traditional SDLC (planning, requirements analysis, design, development, testing, deployment, maintenance) but groups them into three larger stages: Inception, Construction, and a third stage covering operations. Inception answers what and why. Construction answers how.
Not every requirement runs through every sub-stage. Green sub-stages always run. Yellow sub-stages load conditionally based on the project state and the developer’s choices during the conversation.
Dynamic workflow planning
Instead of requiring you to know which command triggers which phase, AIDLC acts as a background orchestrator. It checks the current environment (new project vs. existing codebase), evaluates what you’ve described, and branches into the appropriate subworkflow automatically.
A brand new (Green Field) project skips the reverse-engineering subworkflow. A requirement that doesn’t affect end users skips the user stories workflow and moves straight to the next sub-stage. You don’t decide which subworkflow loads. The framework does.
AIDLC also maintains a file called aidlc-state.md. If you describe a vague, multi-part requirement, the framework extracts the most urgent sub-requirement, starts the workflow for that one, and queues the rest in aidlc-state.md for the next round. This addresses the granularity problem directly.
Dynamic team collaboration
Every question the framework asks during a sub-stage, and every answer the developer gives, gets written to a {current-phase}-questions.md file. Adjustments and AI responses get organized into a file called audit.md. The audit file is append-only, so the full history of decisions and approvals is always available.
At the end of each sub-stage, the workflow pauses and waits for human review. Solo developers approve and continue. Team developers commit the output via git and send it to the relevant colleague. The next stage doesn’t start until the approval mark appears in audit.md.
How Qian’s Team Extended It
AIDLC’s core lives in two folders: aws-aidlc-rules (core workflow definitions) and aws-aidlc-rule-details (subworkflow files that load on demand). Qian converted the whole thing into a Skill by creating an aidlc-workflows folder under .agents/skills, copying core-workflow.md in as SKILL.md, and moving all subworkflow files into a references subfolder. This makes it loadable by coding agents beyond Amazon’s own Kiro agent.
He then built several custom extensions on top of the base framework:
- Documentation consistency: An extension that requires every code change to update related workflow documents automatically, solving the spec drift problem.
- Approve vs. continue separation: By default, approving a stage triggers automatic progression. Qian split those into two distinct actions. Approving a document means you’re done with your role. The next person says “continue” to start the next stage. This enforces role boundaries across the team.
- Audit trail identity: The default
audit.mddoesn’t record who made each entry. Qian addedUserandEmailkeys populated fromgit config user.nameandgit config user.email, so every approval record is traceable to a specific person. - In-conversation Q&A: The original AIDLC writes questions to a
{phase-name}-questions.mdfile and expects the developer to open a separate IDE to answer. Qian built an extension for OpenCode that surfaces questions directly in the conversation and writes responses back into the document without leaving the tool.
The Testing Angle Worth Knowing
One of AIDLC’s default extensions addresses a common AI testing failure. When AI writes unit tests, it can tweak the source code or adjust the test afterward to hit coverage targets without the code actually working correctly. It games its own metrics.
AIDLC’s testing extension requires Property Based Testing (PBT). Instead of checking fixed inputs, PBT randomly generates a large batch of input conditions. The AI can’t predict what input comes next, so it can’t pre-game the test results.
The framework also includes extensions covering security and continuous integration and deployment best practices drawn from Amazon’s internal engineering standards.
When This Works
- Multi-developer teams where different roles (product, engineering, architecture) need to sign off at different stages
- Projects that have grown beyond a single sprint and have existing codebases to reason about
- Teams where audit trails and accountability matter (regulated industries, client work, agencies)
- Developers who want structured AI coding without memorizing a new command vocabulary
When It Does Not
- Pure solo projects with no collaboration requirements and fast iteration cycles
- Simple one-off scripts or small utilities where SDLC overhead is heavier than the work itself
- Teams not yet using a coding agent that supports Skill loading
Qian notes one honest tradeoff: AIDLC asks more technical questions during the conversation than lighter SDD frameworks. You’ll need a working understanding of software engineering fundamentals to get full value from it. He considers that a feature, not a bug, since those fundamentals are baseline knowledge for anyone shipping production code.
He’s released his customized version with all the extensions described above. The source code is available on his blog, Data Leads Future. Note that this implementation is based on AIDLC version 1.0 with custom modifications, not the recently released version 2.0.
I’m founder of BizStack at Cagri Sarigoz LLC and a passionate advocate for entrepreneurs.
With over 14 years in tech, marketing, and AI, including my role as Head of SEO at CitizenShipper and co-founder of TaleBot at Intale AI, I’m dedicated to sharing genuine, useful product insights and tips.
At BizStack, I aim to cut through the digital noise to provide clear, actionable advice.
And more than all else, I’m a father to a (always) little girl and a husband.
Contact me at [email protected] for assistance.
