Welcome to Haposoft Blog

The emergence of AI coding agents like Claude Code and GitHub Copilot has fundamentally shifted how software is built. "Just give AI commands in natural language, and it will write code for you"—something that was science fiction a few years ago—has now become a daily reality. Yet, as adoption scales, a familiar set of friction points emerges: "What was that plan I made three hours ago?"– More and more time is being spent scrolling through chat history. After assigning tasks to AI, it was discovered that AI implemented unexpected features (over-engineering). As the conversation lengthens, important specifications get buried in context. When changing sessions, we have to explain the context to the AI ​​all over again. That is why more teams are moving away from pure “vibe coding” workflows and paying attention to Spec-driven development (SDD). Instead of relying on scattered prompts, SDD keeps specifications at the center of the development process. The spec becomes the shared reference point for both engineers and AI coding agents throughout implementation. 1. What is Spec-Driven Development (SDD)? 1.1 Definition Spec-Driven Development (SDD) is a development method in which the specification document is considered as "Single Source of Truth", and code generation is handled by a coding agent based on that specification. Traditional development usually follows a code-first workflow. Developers write the code first, then update documents later. SDD works the other way around. Before implementation starts, the team first defines what needs to be built through structured specifications. Once the requirements are clear, developers and AI agents use that spec as the foundation for implementation. That spec-first mindset is the core idea behind Spec-driven development. 1.2 Where SDD Fits in the Evolution of Software Development Spec-driven development is not an entirely new concept. In many ways, it brings back a familiar engineering principle that software teams have followed for decades: Define requirements → Design → Implement → Test. The difference is that this workflow is now being adapted for the AI era. As AI coding tools become more capable, teams are realizing that prompting alone is not enough for large-scale development. Without structured specifications, context becomes unstable and outputs become harder to control. SDD addresses that problem by keeping requirements and decisions documented in a persistent format instead of leaving everything inside chat conversations. The approach started gaining broader attention after Thoughtworks included Spec-Driven Development in the “Assess” stage of its Technology Radar Vol.33 in November 2025. Around the same period, AWS also introduced Kiro IDE, an AI-integrated development environment built around requirements → design → tasks → code generation workflow. 1.3 Spec-Driven Development vs. Vibe Coding The difference between vibe coding and Spec-driven development becomes much clearer in day-to-day development workflows. Criteria Vibe Coding Spec-Driven Development (SDD) Starting point Natural language ideas and prompts Structured specification Main Source of Context Chat history Specification file (Markdown...) Plan Continuity Context gets buried in conversations It exists as a file. Handover between sessions Difficult to continue across sessions Letting AI read the specifications is a viable option. Sharing within the team Hard Easy thanks to file sharing. Review Only the output code can be reviewed. Review can be done right from the spec stage. 2. Real-World Benefits of Spec-Driven Development Spec-Driven Development is still an emerging practice in 2025 and 2026, and the industry does not yet have a unified way to measure its impact. However, after applying spec-first workflows across production projects, we at Haposoft started seeing measurable improvements in delivery speed and project execution. Those workflows later became the foundation of CafeKit. 2.1 Reduce Total Project Effort by 30% Measurement Context: We compared actual man-hours from kickoff to production release across mid-to-large Web/SaaS projects (3–12 months scale), contrasting the legacy workflow (code-first, documentation later) with the new Spec-Driven Development (SDD) workflow integrated with AI coding agents. Effort Savings Breakdown Across the Project Lifecycle: Requirement & Design: Structured specifications from day one reduce client clarification loops. Common modules (authentication, payments, notifications) are reused from existing spec libraries instead of being redefined from scratch. Implementation: AI coding agents use the spec as a single source of truth, generating accurate code on the first attempt and significantly reducing back-and-forth prompting cycles between engineers and AI. Testing: Test cases are auto-generated directly from the spec’s acceptance criteria, eliminating manual test design after development is complete. Rework (Largest Saving): Human-AI alignment on specs before coding virtually eliminates "build-then-realize-misunderstanding" scenarios. This drastically cuts rework overhead, which is typically the biggest efficiency drain in Vietnam-Japan offshore projects due to language barriers. Documentation: Handover documentation is automatically generated from the spec, meeting the stringent documentation standards expected by Japanese enterprise clients without adding engineering overhead. The 30% reduction in total project effort translates to faster time-to-market, lower burn rates, and higher margin predictability across the portfolio. Teams can deliver more value within fixed timelines while maintaining strict quality and documentation compliance. 2.2 Increase SDLC delivery speed by 50% We also compared the time required to move from kickoff to the first production release between traditional code-first projects and projects using SDD workflows with AI coding agents. The biggest improvement came from reducing requirement misunderstandings. Reduced rework due to misunderstanding of requirements. Because the specifications are agreed upon by both humans and AI before writing the code, instances of "implementing and then discovering misunderstandings" are significantly reduced. This is the biggest source of waste in global offshore projects due to the language barrier. AI implements faster when specifications are clear. Coding agents with specifications as a "guide" will generate more accurate code the first time, reducing the number of back-and-forth prompt cycles. Test cases are generated from the acceptance criteria of the specification. No need to write tests from scratch after the code is finished. The handover document is automatically generated from the spec.– especially important for Japanese clients who require meticulously prepared documentation. One of the biggest improvements came from reducing rework. With SDD, many of those issues were identified earlier during the specification phase. A 50% efficiency increase has been observed on medium to large-scale greenfield development projects. For small maintenance or hotfix projects, the overhead of writing specifications can outweigh the time saved – this is one reason CafeKit has a mechanism to allow skipping phases for minor changes. 2.3 Other Qualitative Effects Beyond measurable delivery metrics, our team, Haposoft, also observed several operational improvements after adopting Spec-driven development. Clearly define responsibilities between humans and AI: Specifications define what needs to be built, while AI focuses on implementation. This separation helped teams maintain control over project direction while still improving development speed. Continuity transcends session boundaries: Even if the Claude Code session is interrupted or if the engineer in charge changes midway (which frequently happens in offshore companies), as long as the specification file remains, the new person can take over the project in a short time. Documents are automatically accumulated: requirements, implementation decisions, and project progress were stored as structured Markdown files inside the repository. Teams spent less time reconstructing context weeks or months later, especially during onboarding and handovers. This is especially important for project structures where developers work together across multiple time zones. 3. Typical workflow of SDD So how does Spec-driven development actually work in practice? While workflows may vary between teams and tools, most SDD processes follow six core phases. Phase 1: Requirements Teams describe business goals, user problems, functional requirements, and nonfunctional requirements in natural language. During this stage, developers often work together with AI tools to structure ideas into user stories and acceptance criteria. The goal is not to create perfect documentation from the start. Instead, the focus is on building a shared understanding of what needs to be developed. Phase 2: Design This may include architecture decisions, data models, API structures, screen flows, and system behavior. Many teams also use design docs or ADRs to record why certain technical decisions were made. Keeping those decisions documented becomes especially useful later when projects scale or new engineers join the team. Phase 3: Task Breakdown Break down the design into manageable tasks. Using the "1 task = 1 commit" standard will help streamline progress management and review. Phase 4: Implement (Implementation) Assign AI to generate code for each task unit. Because it implements and references the specification simultaneously, the AI ​​can write consistent code without "losing the overall picture." Phase 5: Test Generate and run test code based on acceptance criteria derived from the specification. Because the specification and tests correspond one-to-one, coverage is easy to visualize. Phase 6: Review Human engineers check for consistency with specifications, code quality, and security. Because the specification document serves as a "reference standard," the review criteria become clear. 4. Popular Spec-Driven Development Tools As Spec-driven development continues gaining attention, more tools are appearing around AI-assisted workflows and coding agents like Claude Code. Each tool approaches SDD differently. Some focus on documentation workflows, while others provide end-to-end environments that connect requirements, implementation, testing, and AI-generated code. 4.1 GitHub Spec Kit GitHub Spec Kit is an official toolkit built around the idea that AI performs better when working from clear specifications. The toolkit helps teams create and manage documents such as PRDs, design docs, and ADRs before implementation begins. Instead of relying entirely on prompts, developers can structure project context in a more reusable format. 4.2 Kiro IDE Kiro IDE is an AI-integrated development environment introduced by AWS. The platform supports workflows that move from natural language requirements into structured phases such as design, task breakdown, implementation, testing, and code generation. Rather than treating AI as a simple autocomplete tool, Kiro positions AI agents as part of the overall development workflow. 4.3 claude-code-spec-workflow The CLI tool originated from the OSS community. Implementing the SDD flow for Claude Code, it can launch a new feature development workflow with just one command. For teams already working heavily with Claude Code, this type of workflow helps reduce prompt fragmentation during development. 4.4 cc-sdd / OpenSpec This group of lightweight tools offers a flow spec → task → implement approach based on various philosophies. The choice depends on the scale and preferences of the project. Different tools also follow different philosophies, allowing teams to choose workflows that fit their project size and engineering culture. 4.5 CafeKit CafeKit is the open-source SDD toolkit developed by our team at Haposoft. The tool was designed specifically for Claude Code workflows and follows a six-phase Spec-driven development process. Instead of treating specifications as static documents, CafeKit keeps them closely connected to implementation, testing, and project tracking throughout development. 5. CafeKit: An SDD Toolkit Built for Enterprise Development 5.1 What is CafeKit? CafeKit (cafekit.haposoft.com) is an open-source CLI toolset designed specifically for Claude Code, implementing the 6-phase Spec-Driven Development workflow. One of the main goals behind CafeKit was making SDD workflows easier to apply in enterprise development environments, where documentation, review processes, and long-term maintainability are often critical parts of delivery. 5.2 The Core Six Phase Workflow in CafeKit CafeKit uses the same familiar terminology as in the Japanese development environment, providing the following phases: Requirements Definition → Design → Task Breakdown → Implement → Test → Review Each phase produces structured Markdown files stored directly inside the repository, manageable with Git. Because specifications are version-controlled together with the codebase, teams can track changes more consistently and maintain a clearer project history over time. The workflow also makes collaboration easier between engineers, reviewers, and AI coding agents since everyone works from the same documented context. 5.3 Why We Built CafeKit When we started applying SDD workflows in production projects, we noticed that many existing tools focused heavily on prompting but provided limited support for maintaining long-term project structure. CafeKit was designed to solve several practical issues we encountered during real development workflows: Keeping specifications and implementation synchronized throughout the project lifecycle. Making project context easier to continue across AI sessions. Improving collaboration between multiple engineers working with AI coding agents. Maintaining reusable documentation instead of relying entirely on chat history. The goal was not simply to generate code faster. It was to create a workflow where both humans and AI could work from stable and reusable specifications. 5.4 Getting Started with CafeKit Setting up CafeKit only takes a few minutes. 1. Prerequisites Make sure you have Node.js (v18 or higher) and `npm`/`npx` installed. 2. Navigate to Project Root Open your terminal and `cd` into the root folder of your project. 3. Initialize CafeKit Run the setup command: npx @haposoft/cafekit The command above will automatically download and run the CLI. Follow the interactive prompts to configure your project. Additional setup instructions and documentation are available on the official CafeKit website. 6. How to Start Applying Spec-Driven Development For teams interested in introducing Spec-driven development into their workflow, the transition does not need to happen all at once. In most cases, starting small is more effective than trying to redesign the entire development process immediately. Step 1: Start with a small project Avoid applying SDD across a large project from day one. A better approach is to start with smaller internal tools, isolated features, or new side projects. This gives the team time to adjust to spec-first workflows without adding unnecessary delivery risk. Step 2: Prepare Specification Templates Well-structured templates make SDD much easier to adopt consistently across teams. Depending on the project type, teams may prepare templates for requirements, design documents, API specifications, or acceptance criteria. Starting from existing templates and customizing them gradually is usually more practical than creating everything from scratch. Step 3: Keep Tasks, Commits, and Specs Aligned One useful practice is maintaining a close relationship between tasks, commits, and specification updates. Some teams follow a simple structure: 1 Todo = 1 Commit = 1 Spec Update Step 4: Move Review Earlier into the Specification Phase Traditional workflows often rely heavily on code review after implementation is already finished. SDD shifts part of that review process earlier by reviewing specifications before development starts. Catching requirement gaps during the specification phase is usually much cheaper than rebuilding features later in implementation. Step 5: Standardize Tools Across the Team If each individual uses a different tool, the specification format will become chaotic. It's best to use a consistent tool (e.g., CafeKit) throughout the team. 7. Common Challenges When Adopting Spec-Driven Development Like any development methodology, Spec-driven development is not a perfect solution for every situation. Teams adopting SDD often run into several common problems during the transition phase. Trap 1: Writing too much specification. One of the most common mistakes is over-documenting everything from the beginning. If teams spend too much time trying to create perfect specifications, the speed advantage of AI-assisted development quickly disappears. In practice, lightweight specifications are often enough to get started. A gentler approach, "starting with a few bullet points," is also very effective – AI will help you expand the specifications. Trap 2: Specifications and Code Falling Out of Sync Another common issue appears when implementation changes but specifications are not updated afterward. Over time, outdated specifications become unreliable and teams stop trusting the documentation entirely. To avoid this, specifications and implementation need to evolve together throughout the project lifecycle. Trap 3: Overtrusting AI-generated Output Even with structured specifications, AI coding agents still make mistakes. Specifications improve consistency, but they do not guarantee correct implementation in every case. SDD works best when AI is treated as a development partner rather than a fully autonomous replacement for engineering judgment. 8. How Spec-Driven Development May Change Engineering Careers The rise of AI coding tools is also changing how engineering skills are evaluated. As AI becomes better at generating implementation code, the value of simply “writing code” may gradually become less differentiated. At the same time, skills related to defining requirements, structuring problems, and designing systems are becoming more important. This is one reason Spec-driven development is attracting attention beyond productivity alone. In SDD workflows, engineers are expected to translate unclear business requirements into structured specifications that both humans and AI can understand consistently. In many ways, SDD shifts part of the engineer’s role from pure implementation toward specification design and decision-making. For those looking to shift their career from "coder" to "specification designer," SDD is definitely an essential skill set. Summary Spec-driven development is not just about using AI to generate code faster. It is about creating a more structured development process where both humans and AI work from the same source of truth. As AI-assisted development continues evolving, workflows built around clear specifications will likely become more common across modern software teams. If you want to start using SDD in enterprise development, give this a try. CafeKit (cafekit.haposoft.com) fully compatible with Claude Code, free OSS – deployable today. Contact CafeKit For support, enterprise customization, or SDD related consulting, feel free to contact our team at Haposoft. Official website: cafekit.haposoft.com Haposoft: This offshore development company has its headquarters in Hanoi (Vietnam) and an office in Tokyo ( Japan). It is certified as an AWS Select Tier Partner, ISO 9001:2015, and ISO 27001. Let development in the AI ​​era be guided by solid specifications.