Spec-Driven Development Walkthrough (Video)
This walkthrough shows how to use the ACT workflow on a real brownfield feature, starting from a short prompt and moving through spec, refine-spec, plan, work, and final QA.
The example task is to add a stacked history chart to an existing Flutter app while preserving the codebase’s patterns, constraints, and testing expectations.
What This Walkthrough Covers
Section titled “What This Walkthrough Covers”- turning a vague feature request into a concrete spec file
- answering clarifying questions that surface hidden product decisions
- using
refine-specto catch gaps and codebase misalignment before implementation - generating a phased plan from the refined spec
- implementing the feature with
work - doing final UI QA and tightening the result based on what the running app reveals
Why This Matters
Section titled “Why This Matters”The main idea is simple: the cheapest place to remove ambiguity is before code is written.
In the video, the original request sounds straightforward, but the spec workflow surfaces a number of important decisions early:
- whether to replace the existing chart or add a toggle
- what touch interactions should do
- whether to show a legend and where it should go
- how the stacked chart should be ordered
- what should persist across app restarts
By making those decisions explicit up front, the later planning and implementation steps become much calmer and more predictable.
Key Takeaways
Section titled “Key Takeaways”- the
specstep is the highest-leverage part of the workflow for multi-layer features refine-specis useful because it challenges the spec against the actual codebase- planning and implementation work better when they inherit a strong spec
- UI work still needs human QA, even with a good spec and plan
- the workflow favors quality and maintainability over raw speed