Welcome to Haposoft Blog

AI coding tools like Claude Code can generate entire features in minutes, but raw speed means nothing if the underlying business logic is flawed. The root cause is rarely the model itself, but rather the fact that we are still feeding it human-centric requirements filled with hidden assumptions. When an AI encounters ambiguity, it doesn't ask for clarification; it simply guesses, and those guesses will eventually break your production. This article explores how to bridge that gap by mastering the art of writing specs for AI coding. We will break down why traditional PRDs fail with autonomous agents, how to use the six-part CafeKit framework to eliminate ambiguity, and practical techniques like EARS and Example Mapping to handle complex edge cases. By the end, you will know exactly how to turn vague ideas into strict, machine-readable contracts that Claude Code can execute perfectly on the first try. Why Writing Specs for AI Coding Is Different Traditional PRDs work perfectly for human teams because developers share a massive amount of implicit context. They can read between the lines, ask quick questions, and align on business goals during a brief chat. An AI agent, however, operates in a complete vacuum without any of this shared background knowledge. When you hand a vague requirement to a human, they will pause and clarify before writing code. When you hand that same requirement to an AI, it immediately starts generating syntax based on statistical guesses. This fundamental difference completely changes how we must approach requirement documentation. AI Doesn't Interpret Requirements Like Humans Human developers are interpretive readers. When they see "users should receive a notification when an order is shipped," they understand the domain context. They know "notification" likely means email in a B2B system or push notification in a mobile app. They check existing code for patterns and ask the product owner when something is unclear. AI does none of this. It processes patterns from its training data and generates the most statistically likely implementation. Not necessarily the correct one–just the most common one it has seen. Human Developer AI Coding Agent Asks clarifying questions Makes assumptions based on available context Uses domain knowledge Only knows what is documented Challenges unclear requirements Interprets requirements literally Relies on team discussions Cannot access undocumented decisions Consider a coupon requirement: "The system shall apply discounts to orders." An AI might implement percentage-based discounts, fixed-amount discounts, or tiered discounts based on order value. It might apply them before tax, after tax, or only to specific categories. Without explicit guidance, it chooses one based on whatever it saw most often in open-source code. This decision might work, or it might be completely wrong for your business logic. Ambiguity Becomes Implementation This is the critical rule for AI specifications: every ambiguity in your requirement becomes a decision the AI makes for you. When you write "notify users when an order is shipped," the AI must select a delivery channel, an email template, a sender address, retry logic, opt-out handling, and rate-limiting rules. It will pick something for each of these without telling you. It does not mark its assumptions or flag uncertain areas. With human developers, ambiguity leads to questions. With AI, ambiguity leads to code. That code will compile, pass tests, and appear to work until the missing edge case surfaces in production. Missing Context Creates Wrong Assumptions AI agents work with the context you provide and nothing else. They can explore your codebase to understand existing patterns, but they cannot infer unstated architectural constraints. If your spec does not mention that all database operations use the repository pattern, the AI writes raw SQL queries in controllers. If you forget to specify JWT-based authentication, it implements session cookies. If you do not state that timestamps should be stored in UTC, it uses the server's local time. A human developer looks at the surrounding code and follows established conventions. Claude Code looks at your spec. If it is not in the spec, it does not exist. This is why your specification must serve as the AI's complete worldview–no assumptions can be left unstated. The Shift-Left Principle Starts at Specification In traditional development, shift-left means moving testing earlier in the cycle. For AI coding, it means moving clarity earlier–all the way to the specification phase. The cost of fixing bugs in AI-generated code is not in debugging but in regeneration. You catch the issue, rewrite the requirement, and rerun the agent. Each iteration costs time and token budget. A tight specification prevents these cycles. When you write "WHEN order.status changes to 'shipped', THE SYSTEM SHALL send an email to customer.email_address," the AI has no room to improvise. The output matches the intent because the input left nothing to interpretation. This is the fundamental productivity lever for AI coding: better specifications, not better prompting. And the most practical way to write specifications this precise is using a structured syntax designed to remove ambiguity–EARS. Using EARS to Reduce Ambiguity in AI Requirements What Is EARS EARS stands for Easy Approach to Requirements Syntax. It was developed by Alistair Mavin and colleagues at Rolls-Royce PLC for aerospace and defense systems—environments where misinterpretation can cost millions. The syntax forces requirements writers to use a strict, predictable structure that eliminates the natural ambiguity of human language. Every EARS requirement follows a clear pattern that specifies exactly what triggers an action, what conditions apply, and what the system must do in response. This structure is particularly valuable for AI coding agents because they process patterns far more effectively than they interpret intent. When you write a requirement in natural English, the AI must guess which words are the trigger, which words are the condition, and which words are the action. When you write in EARS format, the roles are clearly marked by the syntax itself. The AI does not need to infer–it simply maps the structured input to structured output. Why EARS Works Well for AI Agents AI coding agents perform best when instructions follow predictable patterns. While human readers can often infer meaning from loosely written requirements, AI models are far more reliable when requirements are structured and explicit. Consider how developers typically write requirements in a PRD: Users should receive notifications when an order ships. Most stakeholders understand the intent behind this statement. However, several important details remain open to interpretation. What type of notification should be sent? Who receives it? When should it be triggered? What happens if delivery fails? Using EARS, the same requirement becomes: WHEN an order status changes to "Shipped" THE SYSTEM SHALL send an email notification to the customer's registered email address within 5 minutes. The business intent remains the same, but the implementation details become much clearer. Instead of asking AI to interpret a broad statement, the requirement explicitly defines the trigger, action, and expected outcome. This structure reduces ambiguity and gives Claude Code a much stronger foundation for generating the correct implementation on the first attempt. Core EARS Requirement Types EARS is built around a small number of requirement patterns. These patterns cover most scenarios encountered during software development and help teams maintain consistency across specifications. For AI-assisted development, these patterns create a predictable structure that makes requirements easier to interpret and implement consistently. Pattern Structure When to Use Example Ubiquitous THE SYSTEM SHALL Behavior that always applies regardless of state or events THE SYSTEM SHALL log all payment transactions Event-Driven WHEN THE SYSTEM SHALL Behavior triggered by a specific event that occurs at a point in time WHEN a user submits a password reset request THE SYSTEM SHALL send a reset link State-Driven WHILE THE SYSTEM SHALL Behavior that applies during a continuous period or persistent state WHILE a user session is active THE SYSTEM SHALL refresh the authentication token every 15 minutes Optional Feature WHERE THE SYSTEM SHALL Behavior that is only available when a specific feature or condition is enabled WHERE the user has administrator privileges THE SYSTEM SHALL display the audit log Unwanted Behaviour IF THEN THE SYSTEM SHALL Behavior for edge cases, failures, or unwanted conditions IF the payment gateway returns a timeout error THE SYSTEM SHALL retry up to 3 times Traditional Requirement vs EARS Requirement The difference between a traditional requirement and an EARS requirement is not just about formatting–it is about what the AI can infer versus what you must explicitly state. Traditional requirement: "Users should receive notifications when an order is shipped." The AI reads this and must decide what "notification" means, what "shipped" means, who the user is, what channel to use, what the content should be, and what to do if the notification fails. These are all decisions the AI will make based on training data, not based on your actual system requirements. EARS requirement: "WHEN an order status changes to 'shipped' THE SYSTEM SHALL send an email notification to the customer's registered email address within 5 minutes of the status change." Now the AI knows exactly what to build. The trigger is a status change to a specific value. The response is an email to a specific address. The timing is constrained. There is nothing to interpret. If you want to specify what happens when the email fails, you add an error handling requirement. Here is a side-by-side comparison of what the AI must decide in each case. Traditional Requirement EARS Requirement Customers can apply discount codes at checkout. WHEN a customer enters a valid discount code during checkout, THE SYSTEM SHALL apply the corresponding discount before calculating the final order total. Invalid discount codes should show an error. IF a discount code does not exist or has expired, THE SYSTEM SHALL display an error message and prevent the discount from being applied. Premium users can use loyalty discounts. WHERE a customer has Premium status, THE SYSTEM SHALL allow loyalty discounts to be combined with promotional discount codes. Both versions communicate the same business idea. The difference is that EARS removes much of the interpretation required during implementation. For a human developer, this improves clarity. For Claude Code, it provides a much stronger signal about the behavior that should be generated. EARS Creates Better Inputs for Testing Another advantage of EARS is its natural alignment with testing practices. Many teams already use Behavior-Driven Development (BDD) to define acceptance criteria through Given-When-Then scenarios. EARS follows a similar mindset by making triggers, conditions, and expected outcomes explicit. For example, this requirement: WHEN a customer's subscription expires, THE SYSTEM SHALL revoke access to premium features. can easily be translated into a test scenario: Given a customer with an active premium subscription When the subscription reaches its expiration date Then premium features should no longer be accessible This relationship becomes particularly useful when working with AI coding tools. Claude Code can use the same requirement as the basis for implementation, unit tests, integration tests, and acceptance criteria. Instead of generating code from a vague description, the AI works from a specification that already defines expected behavior. EARS is not a complete framework for writing AI-ready specifications. It does not define business context, domain terminology, technical constraints, or edge cases. However, it provides a strong foundation for describing system behavior in a way that minimizes ambiguity and improves implementation accuracy. Read more: Spec-Driven Development for Claude Code: Comparing CafeKit, GitHub Spec Kit, BMAD, and claude-code-spec-workflow The Anatomy of an AI-Ready Specification EARS helps define system behavior clearly, but writing specs for AI coding requires more than well-structured requirements. Claude Code still needs enough context to understand the business problem, the domain it operates in, and the technical constraints it must follow. A common mistake is assuming that a collection of EARS requirements is enough for implementation. In reality, two teams can provide the exact same requirement and still receive very different outputs depending on the surrounding context. This is why high-performing AI engineering teams are moving toward AI-ready specifications–documents designed not only for human review but also for AI execution. While formats vary across organizations, most effective AI-ready specifications share the same core components. Context and Goal Before defining requirements, the specification should establish why the feature exists and what problem it solves. This section gives the AI the business context needed to make better implementation decisions. Without context, the model may focus on completing individual requirements while missing the broader objective behind the feature. For example, instead of jumping directly into requirements such as "WHEN a customer enters a discount code, THE SYSTEM SHALL apply the corresponding discount," provide a brief description of the feature goal. Something like: "The purpose of this feature is to increase promotional campaign adoption by allowing customers to redeem discount codes during checkout while ensuring discount rules remain consistent across web and mobile platforms." This gives Claude Code a clearer understanding of the business outcome it is supporting. Domain Glossary One of the fastest ways to create confusion in AI-generated code is inconsistent terminology. Many organizations use similar terms interchangeably during discussions, but those differences can have a significant impact during implementation. A specification might refer to User, Customer, Member, and Subscriber even though they represent different business entities. An AI-ready specification should include a glossary that defines important domain concepts before implementation begins. Term Definition Customer A registered user who can place orders Guest User A visitor who can browse products but cannot access order history Discount Code A promotional code that reduces order value when eligibility conditions are met Premium Customer A customer enrolled in the loyalty program Functional Requirements Using EARS Once context and terminology are established, functional requirements should be defined using a consistent structure. This is where EARS becomes the primary mechanism for describing system behavior. Instead of relying on free-form descriptions, each requirement clearly defines triggers, conditions, and expected responses. The five EARS patterns cover every scenario you will encounter: ubiquitous behavior that always applies, event-driven behavior triggered by specific actions, state-driven behavior that depends on system state, optional features that apply only under certain conditions, and error handling for when things go wrong. Error handling requirements are particularly important because teams tend to focus on the happy path and overlook exceptions. If you do not specify what happens when a coupon code is invalid, the AI will either ignore the case or invent behavior that may not align with your business rules. For each event-driven requirement, write at least one corresponding IF requirement for what happens when the operation fails. Example Requirements for a Discount System: WHEN a customer enters a valid discount code during checkout, THE SYSTEM SHALL apply the corresponding discount before calculating the final order total. IF a discount code has expired, THE SYSTEM SHALL display an error message and prevent the discount from being applied. IF a discount code has exceeded its usage limit, THE SYSTEM SHALL reject the application and display "This coupon has reached its usage limit." IF a customer applies a coupon while the order is in CONFIRMED status, THE SYSTEM SHALL reject the modification and display "Cannot modify confirmed order." IF two customers apply the same coupon simultaneously, THE SYSTEM SHALL process the applications sequentially and enforce the usage limit correctly. Because these requirements follow a predictable structure, they are easier for both reviewers and AI coding agents to understand. The AI does not need to guess how to handle exceptions–you have documented them explicitly. Acceptance Criteria Requirements define what the system should do. Acceptance criteria define how success will be measured. This section helps prevent different stakeholders from interpreting the same requirement in different ways. It also provides clear validation targets for AI-generated implementations. Many teams use a BDD-style format because it is both human-readable and testable. Example: Given a valid discount code exists When a customer applies the code during checkout Then the correct discount should be reflected in the order total Acceptance criteria create a direct connection between business expectations and implementation outcomes. Technical Constraints One of the biggest sources of unnecessary AI-generated complexity is missing technical guidance. When no constraints are provided, Claude Code may introduce new patterns, dependencies, or architectural approaches that differ from the rest of the system. A dedicated technical constraints section can significantly reduce this risk. Examples include: Use the existing Repository pattern. Reuse the Notification Service for all customer communications. Do not introduce new third-party dependencies. Follow the project's existing API response format. Ensure response times remain below 500ms under normal load. Validation Rules and Business Rules Many requirements fail because validation logic is implied rather than documented. For example, a specification might simply state "validate discount code input," which leaves too much room for interpretation. A stronger specification explicitly defines the rules: Discount code length must not exceed 50 characters. Codes are case-insensitive. Expired codes cannot be redeemed. Codes cannot be combined unless explicitly marked as stackable. The more specific the business rules, the less guesswork AI must perform during implementation. Test Scenarios and Definition of Done The final section should define how the feature will be verified and when it can be considered complete. This provides a clear finish line for both developers and AI coding agents. A Definition of Done may include: All EARS requirements implemented. Unit tests pass. Integration tests pass. Acceptance criteria satisfied. No critical security findings. Documentation updated. Taken together, these components transform a traditional requirement document into an AI-ready specification. EARS provides the structure for describing behavior, while context, terminology, constraints, and validation rules provide the information Claude Code needs to generate code that aligns with business expectations. However, even the most well-structured specification can fail if important edge cases are overlooked–which is why documenting exceptions, failure scenarios, and boundary conditions is the next critical step. Building an AI-Executable Spec with CafeKit Writing a good specification is only part of the challenge. As AI adoption grows across engineering teams, organizations quickly discover another problem: keeping requirements, business context, architectural decisions, and domain knowledge consistent over time. A single feature specification may contain dozens of EARS requirements, validation rules, edge cases, and acceptance criteria. Multiply that across multiple teams and projects, and maintaining a reliable source of truth becomes increasingly difficult. When information is scattered across documents, tickets, meeting notes, and chat conversations, AI coding agents often receive incomplete or outdated context. This is where platforms such as CafeKit become valuable. Rather than treating specifications as standalone documents, CafeKit helps teams manage the broader context that AI coding agents depend on. Requirements, business rules, domain terminology, and supporting knowledge can be organized in a structured format, making it easier for both humans and AI to access the same information. Read more about Cafekit: Beyond "Vibe Coding": How CafeKit Brings Spec-Driven Development (SDD) to AI Automation Centralizing Business Context One of the most common causes of AI implementation errors is fragmented context. Business requirements may live in one document, architectural decisions in another, and domain terminology somewhere else entirely. While experienced developers can usually navigate these gaps, AI agents struggle when important information is distributed across multiple sources. A centralized knowledge base reduces this problem by creating a single source of truth for requirements and supporting context. Instead of relying on assumptions, Claude Code can work from information that has already been documented and reviewed. This eliminates the guesswork that comes from the AI trying to piece together incomplete information from scattered sources. Maintaining Consistent Domain Knowledge As systems grow, terminology becomes increasingly important. Concepts such as Customer, Member, Subscriber, and User may appear similar but often represent different business entities. Without a shared glossary, inconsistencies can quickly spread into requirements, code, APIs, and documentation. AI-generated implementations are particularly sensitive to this issue because models tend to interpret terminology literally. By maintaining domain definitions in a central location, teams can reduce ambiguity and improve consistency across AI-assisted development workflows. When the AI knows exactly what a "Premium Customer" means, it generates code that correctly implements the associated business rules without introducing subtle errors. Preserving Architectural Decisions Requirements explain what a system should do. Architectural decisions explain how the system should be built. These decisions are often documented through Architecture Decision Records (ADRs), covering topics such as design patterns, infrastructure choices, integration approaches, and performance constraints. While developers may already be familiar with these decisions, AI agents can only follow them if they are accessible during implementation. Providing AI with access to architectural guidance helps reduce unnecessary deviations from established engineering standards and lowers the risk of introducing inconsistent solutions. When Claude Code knows that the team uses the repository pattern and follows specific API conventions, it generates code that fits seamlessly into the existing codebase rather than introducing novel patterns that require refactoring. Creating a Better Workflow for Claude Code Many teams are now moving away from simple prompt-based development and toward specification-driven workflows. Instead of asking Claude Code to "build a feature," the process becomes more structured: Define business goals and requirements. Document EARS requirements and acceptance criteria. Capture edge cases and validation rules. Provide architectural constraints and supporting context. Generate implementation and tests from the specification. This approach creates a much stronger foundation for AI-assisted development because the model spends less time making assumptions and more time executing clearly defined requirements. The result is not only better code generation, but also more consistent implementations, fewer revision cycles, and greater alignment between business expectations and engineering outcomes. Ultimately, tools like Claude Code become significantly more effective when they operate within a structured specification environment. Conclusion Writing specs for AI coding is fundamentally different from writing requirements for human developers. Human developers interpret, ask questions, and fill in gaps. Claude Code executes what you specify. When the specification or surrounding code is ambiguous, it makes the best inference based on available context. EARS removes ambiguity by forcing you to specify triggers, conditions, and responses explicitly. CafeKit provides the workspace and workflow–context, terminology, constraints, and validation rules–that AI agents need to generate code that aligns with your business expectations. We are actively using these practices in our projects at Haposoft and seeing significant improvements in code quality and development speed. CafeKit is open-source and available for early use. Install it and start writing specs for AI coding that actually work. Have questions or need advice? Reach out–we are happy to share what we have learned. Ready to put this into practice? CafeKit is open-source and available for early use. Install it and start writing specs for AI coding that actually work. bash npx @haposoft/cafekit GitHub Repository →

AI coding agents like Claude Code boost development speed, but they also introduce new problems. Code looks correct but doesn't meet requirements. Context gets lost between sessions. Large changes break design consistency. Spec-Driven Development (SDD) addresses these issues by adding structure: specify, plan, task, implement. Instead of prompting AI directly, teams define requirements first, then let AI execute against a clear spec. This article compares 4 SDD tools for Claude Code: CafeKit (Haposoft) GitHub Spec Kit BMAD-METHOD claude-code-spec-workflow We'll look at each tool's workflow, strengths, tradeoffs, and which scenarios they fit best—especially for B2B enterprise teams. Understanding Spec-Driven Development for Claude Code Most teams start using Claude Code in a straightforward way: write a prompt, generate code, review the output, then refine the prompt if something is missing. This works well for small features and isolated tasks. However, as projects become larger, requirements become harder to track, implementation decisions get scattered across conversations, and important context can easily disappear between sessions. Spec-Driven Development (SDD) takes a different approach. Instead of treating prompts as the primary source of instructions, SDD treats specifications as the foundation of the development process. Requirements, implementation plans, tasks, and technical decisions are documented before development begins, giving both developers and AI agents a shared source of truth throughout the project lifecycle. How the SDD Workflow Works Although every framework has its own methodology, most SDD workflows follow four core stages. Stage Description Specify Define requirements, business rules, and acceptance criteria Plan Create technical designs and implementation plans Task Break work into smaller executable tasks Implement Generate and review code based on approved specifications The goal is not to add more documentation. The goal is to reduce ambiguity. When requirements, plans, and tasks are already defined, Claude Code spends less time interpreting intent and more time executing clearly defined work. This becomes particularly valuable for large features involving multiple business rules, stakeholders, or development iterations. Why SDD Works Well with Claude Code One of the biggest challenges when working with AI coding agents is maintaining consistency over time. A feature that takes several days or weeks to complete may involve hundreds of requirements, decisions, and implementation details. Some of that information lives in prompts, some in documents, and some only exists in conversations between team members. SDD brings those decisions together in a structured workflow. Specifications define what needs to be built, plans define how it should be built, and tasks define what should be implemented next. Claude Code can then work against a documented plan rather than relying solely on prompt history, making the development process more predictable and easier to manage. Detailed Comparison of 4 SDD Tools for Claude Code CafeKit (Haposoft) cafekit.haposoft.com CafeKit is an open-source Spec-Driven Development (SDD) tool developed by Haposoft. The framework guides teams through the entire software development lifecycle, from requirements definition and technical design to implementation, testing, and review. Compared with other SDD tools in this comparison, CafeKit provides the most detailed phase structure and places a stronger emphasis on documentation, quality control, and traceability. Phase Structure: 6 Phases CafeKit organizes development into six distinct phases. Each phase produces its own outputs and serves as an input for the next stage of the workflow. Requirements Definition — Transform business requirements into structured specifications using EARS to eliminate ambiguity Design — Define architecture, database design, API contracts, and technical decisions Task Breakdown — Split the design into independently executable tasks with complexity estimates Implementation — Generate code for each task following the design and technical constraints Testing — Create test plans, test cases, and execute automated testing Review — Evaluate code quality, check consistency with specs, and record decisions The biggest difference from other tools is that CafeKit separates Testing and Review into their own phases. While GitHub Spec Kit and BMAD fold these activities into the implementation phase or leave them outside the main flow, CafeKit treats them as mandatory stages. This is especially valuable for projects requiring strict quality control or compliance with enterprise testing and review standards. Key Features Native Japanese language support for all generated artifacts (requirements docs, design docs, test plans, review records) Slash command system optimized for Claude Code with phase-specific templates Automatic generation of enterprise-format documentation alongside code Built on methodologies validated through real offshore delivery projects Best For CafeKit works well for both small and large projects. It is especially strong in enterprise environments with strict documentation requirements and formal quality control processes. The detailed phase structure is valuable for distributed teams where clear handoffs reduce miscommunication. Organizations that need formal deliverables at each stage will find CafeKit aligns with their workflows. GitHub Spec Kit github.com/github/spec-kit GitHub Spec Kit is the official Spec-Driven Development tool from GitHub, launched in September 2025. It has gained significant traction quickly and is currently the leading candidate for the de facto standard. The current version is 0.9.5 (early June 2026). GitHub describes it as an experimental project, and community feedback has been mixed—teams praise its structure and predictability but note higher token consumption and slower workflows compared to other tools. Phase Structure: 4 Phases /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement Each command generates artifacts that feed into the next phase. The workflow is linear but supports iteration through modification commands. The specification phase captures requirements, the planning phase defines the approach, the tasks phase breaks work into units, and implementation generates the code. The biggest advantage of this structure is its simplicity. Teams can learn the four commands quickly and start using the tool with minimal ramp-up. However, the simplicity also means less granular control compared to CafeKit's 6-phase approach. Testing and review activities are not explicitly called out as separate phases, which may require teams to build their own quality gates outside the main flow. Key Features Agent-agnostic design supporting 20+ AI agents (Claude Code, GitHub Copilot, Cursor, Gemini CLI, and others) Two-layer customization: Extensions (add functionality) and Presets (modify existing workflows) Automatic feature numbering, branch creation, and directory structure generation Quality validation commands: /speckit.checklist (spec quality) and /speckit.analyze (consistency across artifacts) YAML-defined workflows supporting multi-step automation with pause and resume Active OSS community with rapid feature development Best For GitHub Spec Kit is ideal for teams building new products in a global, English-speaking environment. It works well for organizations using multiple AI coding agents simultaneously. Startups and modern SaaS companies following OSS trends will benefit from its active community and rapid development pace. Teams that prioritize staying current with the latest SDD practices should consider this tool. BMAD-METHOD docs.bmad-method.org BMAD stands for "Breakthrough Method for Agile AI-Driven Development." It is a framework that reimagines Spec-Driven Development within an Agile context. The defining characteristic is its multi-agent architecture, where different AI agents play specialized roles throughout the development process. The framework has recently migrated from .claude/commands to .claude/skills with the release of BMAD Method v6, which provides a native implementation for Claude Code. Phase Structure: 4 Phases Analysis → Planning → Solutioning → Implementation The Analysis phase focuses on understanding business requirements and user needs. The Planning phase creates epics, stories, and sprint plans. The Solutioning phase handles architecture and technical design. The Implementation phase generates code and executes tests. Unlike other tools that treat the workflow as a linear sequence, BMAD supports parallel execution across phases through its multi-agent system. Multiple specialized agents can work simultaneously on different aspects of the project, making it suitable for larger teams and longer-term projects. Key Features 21 specialized agents with distinct roles (Business Analyst, Product Manager, Architect, Developer, Scrum Master, QA) Over 50 guided workflows covering common development scenarios Native implementations for multiple AI tools: Claude Code, Cursor, Windsurf, GitHub Copilot Sprint planning, story creation, and parallel implementation support Expansion Packs for specialized domains like Game Dev, DevOps, and Infrastructure Strong alignment with Scrum and Agile methodologies Best For BMAD-METHOD is designed for Agile teams with clear role definitions. It works best for long-term product development where requirements evolve over multiple sprints. Large-scale refactoring projects also benefit from the structured agent collaboration. Teams with dedicated product owners and architects will find the role-based approach natural. claude-code-spec-workflow (Pimzino) github.com/Pimzino/claude-code-spec-workflow claude-code-spec-workflow is a lightweight, pragmatic SDD tool created by independent developer Pimzino. It currently has 2,544 stars on GitHub with approximately 5,450 downloads per month (version 1.5.9). The tool is designed for simplicity, with a single-command installation and a focus on practical, day-to-day development workflows. The author is currently shifting development focus to an MCP-based version (@pimzino/claude-code-spec-workflow-mcp), meaning the current version will receive fewer updates going forward. Phase Structure The tool provides two separate workflows depending on the type of work: New feature workflow: Requirements → Design → Tasks → Implementation Bug fix workflow: Report → Analyze → Fix → Verify The bug fix workflow is the most distinctive feature of this tool, as no other tool in this comparison provides a dedicated flow for bug fixes. This makes it particularly suitable for maintenance projects where fixing issues is a primary activity rather than building new features. Key Features Single-command installation: npx @pimzino/claude-code-spec-workflow Separate workflow for bug fixes (Report → Analyze → Fix → Verify) Real-time dashboard showing progress across specs Lightweight and easy to adopt with minimal setup Focus on practical, day-to-day development scenarios Best For claude-code-spec-workflow is best for maintenance projects focused on bug fixes and small feature additions. It works well for teams wanting to experiment with SDD without committing to a heavy framework. Small to medium-sized teams looking for a lightweight alternative will find it easy to adopt. Teams that primarily work on existing products rather than greenfield development will appreciate the dedicated bug fix workflow. CafeKit focuses on documentation, quality control, and phase-based delivery. GitHub Spec Kit emphasizes a simple and extensible workflow that works across multiple AI coding agents. BMAD-METHOD takes an Agile-first approach built around specialized AI roles, while claude-code-spec-workflow prioritizes simplicity and day-to-day practicality. The four tools share the same core idea: using specifications as the foundation for AI-assisted development. The difference lies in how much structure they introduce and which development challenges they prioritize. For most teams, the choice is less about features and more about workflow preferences. The best tool is usually the one that aligns with how the team already plans, reviews, and delivers software. Which Tool Should You Choose? The right choice depends on your project type, team structure, and development workflow. The table below summarizes the best fit for each scenario. Scenario Recommended Tool Why Enterprise projects with formal documentation requirements CafeKit Structured 6-phase workflow with dedicated testing and review stages New product development in global teams GitHub Spec Kit Strong community support, agent-agnostic design, and rapid ecosystem growth Agile teams managing long-term products BMAD-METHOD Role-based workflows aligned with Agile and Scrum practices Maintenance projects and bug-fix-heavy workloads claude-code-spec-workflow Dedicated bug fix workflow and minimal setup requirements Enterprise Projects with Formal Documentation Recommended Tool: CafeKit CafeKit's 6-phase structure aligns well with enterprise delivery processes that require formal artifacts at each stage. Requirements documents, design specifications, test plans, and review records are treated as part of the workflow rather than optional deliverables. Teams working with regulated industries, large clients, or strict quality assurance processes will benefit most from this approach. New Product Development in Global Teams Recommended Tool: GitHub Spec Kit GitHub Spec Kit is a strong option for teams building new products in distributed environments. Its agent-agnostic architecture supports a wide range of AI coding tools, while the active open-source community helps keep workflows and best practices up to date. Teams already following modern AI-assisted development trends will find adoption relatively straightforward. Agile Teams Managing Long-Term Products Recommended Tool: BMAD-METHOD BMAD-METHOD fits naturally into organizations that already operate with Agile roles and processes. The framework supports sprint planning, story creation, architecture design, and implementation through specialized AI agents. This makes it particularly useful for product teams working across multiple releases and evolving requirements. Maintenance Projects and Bug-Fix-Heavy Workloads Recommended Tool: claude-code-spec-workflow The dedicated bug fix workflow is the main differentiator here. Rather than adapting a feature-development process to maintenance work, teams can follow a workflow specifically designed for issue resolution. The lightweight setup and lower learning curve also make it a practical option for smaller teams. Can Teams Use Multiple SDD Tools? Absolutely. Adopting Spec-Driven Development does not require an organization to standardize on a single framework. In practice, different teams often have different requirements, workflows, and project types. A tool that works well for a new product team may not be the best choice for a maintenance team or an enterprise delivery project. A common approach is to select tools based on project characteristics rather than enforcing a single standard across the organization. For example, enterprise client projects with formal documentation requirements may benefit from CafeKit's structured workflow. Product teams building new applications may prefer GitHub Spec Kit because of its active ecosystem and agent-agnostic design. Teams focused primarily on maintenance and bug fixing may find claude-code-spec-workflow more practical due to its dedicated bug-fix workflow. The good news is that these tools are not mutually exclusive. Most operate as command-based workflows within Claude Code and can coexist within the same engineering organization. This allows teams to adopt the workflow that best matches their project needs while continuing to use a familiar AI development environment. The goal is not to choose the most feature-rich framework. The goal is to choose the workflow that helps your team deliver software more consistently. For many organizations, that may involve using different SDD tools for different types of work. Conclusion Spec-Driven Development has matured significantly since late 2025. GitHub Spec Kit leads in standardization and multi-agent support. BMAD-METHOD excels in Agile environments. claude-code-spec-workflow offers a lightweight option with unique bug fix workflows. CafeKit provides enterprise-grade structure with strong documentation support. The best choice depends on your project type and team structure. For hybrid environments, using multiple tools in parallel is a practical strategy. Ready to try Spec-Driven Development with your team? Start with CafeKit—it's open-source and ready to use. Install it today and experience structured AI-assisted development. bash npx @haposoft/cafekit GitHub Repository → Have questions about implementing SDD in your organization? Reach out—we are happy to share our experience. About CafeKit and Haposoft CafeKit is available at cafekit.haposoft.com. For implementation support, customization, or internal training, contact Haposoft. Haposoft JSC Headquarters: Hanoi, Vietnam Japan Office: Haposoft Japan (Ebisu, Tokyo) 200+ engineers, ISO 9001:2015 / ISO 27001 certified, AWS Select Tier Partner

AI coding assistants promise unprecedented speed, but they frequently deliver spaghetti code that often disregards your project's actual architecture. This happens because models operate on isolated prompts, lacking a structured workflow to maintain context across complex codebases. CafeKit, developed by Haposoft, is a lightweight runtime for Claude Code that brings structure and accountability to AI-assisted software development. Instead of relying on long prompts and manual oversight, it guides AI through a spec-driven workflow where requirements, code, tests, and documentation stay synchronized from start to finish. The result is a more reliable development process with less context switching, fewer missed requirements, and higher confidence in every release. What is CafeKit? The Engine Behind Spec-driven Development CafeKit is a lightweight runtime developed by Haposoft that brings Spec-Driven Development (SDD) to Claude Code. Installed directly into your project's `.claude` directory, it adds a structured workflow on top of Claude's coding capabilities, helping teams move from requirements to production-ready code without losing context along the way. To understand why CafeKit matters, it's worth looking at how most AI-assisted development works today. Developers often start with a prompt, generate some code, make a few adjustments, and move on to the next task. The feature may work, but requirements get buried in chat history, documentation falls out of date, and nobody is completely sure whether the final implementation still matches the original intent. Spec-Driven Development solves this problem by making the specification the starting point of every feature. Before any code is written, requirements, expected behavior, edge cases, and success criteria are documented and approved. Development then follows that specification step by step, ensuring that implementation, testing, and documentation remain aligned throughout the entire process. Read more: What is Spec-Driven Development? Unraveling the new software development method of the AI ​​era CafeKit is the tooling layer that turns this philosophy into a practical workflow for AI. Rather than relying on Claude to remember dozens of prompts and project rules, it provides a set of commands, agents, and automated checks that guide every stage of development. A feature request becomes a requirements document, the requirements become a technical design, and the design is broken down into verifiable tasks before implementation even begins. This structure becomes especially valuable on larger projects where AI-generated changes span multiple files, services, or teams. By enforcing quality gates and keeping specifications synchronized with the codebase, CafeKit helps prevent the "fake progress" that often appears in AI-assisted development-when a task looks complete on the surface but introduces regressions, breaks existing functionality, or quietly drifts away from the original requirements. How CafeKit Automates AI Discipline (Enforcing the SDD Contract) AI-generated code is no longer the hard part. The real challenge is ensuring that code remains aligned with requirements, design decisions, and project standards as development progresses. This is where Spec-Driven Development (SDD) becomes valuable-and where CafeKit provides the structure needed to make it work in practice. Why Do AI Coding Workflows Break Down? Most AI coding tools are designed to generate output as quickly as possible. While this can accelerate development, it also introduces a familiar problem: context gradually gets lost. Requirements live in chat history, design decisions become scattered across conversations, and documentation often falls behind the implementation. This is why many teams experience "spec drift" when working with AI. A feature may start with a clear goal, but after multiple prompts, revisions, and follow-up requests, it becomes difficult to verify whether the final result still matches the original intent. The larger the project becomes, the more difficult this problem is to manage. Spec-Driven Development takes a different approach by making the specification the source of truth. Instead of relying on prompt history, every requirement, design decision, task, and validation step is tied back to an approved specification. Vibe Coding Spec-Driven Development Starts with prompts Starts with approved specifications Context lives in chat history Context lives in project artifacts Fast for small experiments Scales better for complex projects Documentation is often updated later Documentation evolves alongside development Difficult to audit decisions Every change can be traced back to requirements How Does CafeKit Keep AI on Track? CafeKit operationalizes this process inside Claude Code. Once installed in your project's `.claude` directory, it introduces a set of specialized agents and workflow rules that help ensure work remains aligned with the approved specification. Rather than relying on developers to manually check every step, CafeKit delegates specific responsibilities to a set of purpose-built agents throughout the workflow. Three of the most important for keeping work aligned are: Tester Agent (test-runner) Validates implementations against predefined test commands, acceptance criteria, and expected behavior. Reviewer Agent (code-auditor) Checks whether completed work satisfies the approved specification and follows project standards. Doc-Sync Agent (docs-keeper) Keeps documentation, project records, and specifications synchronized as development progresses. Because these checks are built into the workflow itself, developers spend less time repeating context, verifying assumptions, or chasing outdated documentation. While Cafekit’s agents and automated checks reinforce the process around it. What Happens Before Code Can Move Forward? AI-generated code often looks finished long before it's actually ready to ship. A feature might appear to work during a quick review, but still miss edge cases, fail integration tests, or leave documentation out of date. As teams rely more heavily on AI, these small gaps can accumulate into larger maintenance problems. CafeKit addresses this by treating code generation as only one step in the workflow. Before a task can be completed, the implementation must satisfy the approved specification and pass the required validation checks. Documentation updates can also be enforced as part of the process, helping teams keep project knowledge aligned with the codebase rather than updating it weeks later. The goal isn't to add more process for the sake of process. It's to create a workflow where progress is measured by verified outcomes instead of generated output. That gives teams more confidence in what the AI produces and reduces the amount of manual verification needed before work moves forward. The CafeKit Workflow: 6 Steps from Spec to Ship Most AI coding sessions start with a prompt. CafeKit starts with a specification. Instead of asking Claude to improvise/guess an entire feature, CafeKit forces a structured sequence. Every stage produces a verifiable artifact, ensuring context isn't lost as the codebase scales. Steps 1–5 are available today. Step 6 (/hapo:deploy) is on the roadmap. For now, deployment is handled through the /hapo:devops skill. Note that /hapo:develop already runs an internal quality gate—test, spec review, and code review with self-healing—after every task, so Steps 3 and 4 are explicit, broader verification passes rather than the only place QA happens. Stage Commands What You Get Spec /hapo:specs Feature contract with validation Develop /hapo:develop Incremental implementation per task packet Test /hapo:test Verification with real build signals Review /hapo:code-review Regression and security checks Git /hapo:git Safe commit and push workflow Deploy /hapo:deploy Deployment handoff to your stack - on the roadmap Step 1: Create the Feature Contract with /hapo:specs This is where vague product ideas transform into strict engineering contracts. The command captures your feature request and generates a structured spec workspace—requirements, research, design, and verifiable task files—with explicit scope, behaviors, constraints, and success criteria. You then validate the spec using /hapo:specs validate, which ensures the requirements are complete and implementation-ready. The task registry tracks the validation status, and the AI cannot proceed until the spec passes all checks. Step 2: Implement One Task Packet at a Time with /hapo:develop During the spec stage, CafeKit already broke the approved spec into atomic, independently testable task packets. Each packet has a single objective, explicit completion criteria, and predefined verification commands. When you run /hapo:develop with a specific task packet, Claude implements exactly that piece of work-nothing more, nothing less. This prevents the AI from losing track as the context window fills up​​, eliminates scope creep, and keeps the AI from drifting from the approved design. Step 3: Verify with Real Build and Runtime Signals /spec-test Implementation is not complete until it passes automated quality gates. Running /hapo:test executes the exact verification commands defined in the task packet, checking against real build outputs and runtime behavior. What happens if a test fails? The workflow halts immediately. The AI must fix its own mistakes and re-run the tests before progressing. This completely eradicates "fake progress" where looks complete on paper (in the task checklist) but actually breaks the build. Step 4: /hapo:code-review - Review for Regressions and Security Before any code touches your main branch, CafeKit enforces a structured review process. The /hapo:code-review --pending command triggers specialist agents that scan for regressions, security vulnerabilities, and architectural inconsistencies. These agents cross-check the implementation against the original spec to ensure minimize deviation. Only when the review verdict is positive does the work qualify for the next stage Step 5: /hapo:git - Commit and Push Safely With all quality gates passed, the /hapo:git commit command prepares a clean, verified commit. Any documentation updated earlier in the workflow is committed alongside the code. The runtime ensures your spec registry and task state are synchronized with the actual implementation. Then /hapo:git push safely transfers the work to your remote repository. Every commit is traceable back to an approved spec and verified task packet. Step 6: hapo:deploy - Ship with a Deployment Handoff The final stage will hand off the verified release candidate to your existing deployment stack. Whether you use Vercel, AWS, or custom CI/CD pipelines, /hapo:deploy ensures the deployment process receives only code that has passed every checkpoint. Your documentation, spec registry, and production codebase remain stay aligned. Getting Started with CafeKit One of CafeKit's biggest advantages is how easy it is to introduce into an existing development workflow. There's no need to migrate frameworks, replace tools, or overhaul your tech stack. CafeKit works alongside Claude Code, adding the structure needed for Spec-Driven Development without disrupting how your team already builds software. Install CafeKit To install the runtime, simply navigate to your project's root directory and execute: npx @haposoft/cafekit That is it. This single command provisions your .claude directory with the necessary slash commands, workflow templates, and operational rules. For a deeper dive into advanced configurations, custom hooks, and edge-case handling, follow the official From Zero to CafeKit guide. Once installed, you immediately trigger the spec-to-ship lifecycle: /hapo:specs → /hapo:develop → /hapo:test → /hapo:code-review → /hapo:git → /hapo:deploy Get Support Because CafeKit is entirely stack-agnostic, it supports everything from Node.js and Python to Ruby on Rails and modern frontend frameworks. Teams can adopt the workflow incrementally on isolated legacy modules or greenfield projects alike. If your engineering org is evaluating SDD at scale and needs hands-on implementation guidance, direct support is available. You can request a technical walkthrough through the CafeKit contact form or connect directly through our email sale@haposoft.com to discuss your specific architecture. Conclusion: Build with Confidence, Not Hope The primary bottleneck in modern AI coding is no longer generation speed. It is context retention and architectural integrity. Unstructured prompting inevitably leads to fragmented logic, hallucinated dependencies, and mounting technical debt that senior engineers must clean up later. CafeKit addresses that challenge by bringing structure to AI-assisted development. Instead of treating AI as a powerful autocomplete tool, it turns Claude Code into a structured development environment where specifications, implementation, testing, and documentation move together. Whether you're experimenting with AI-assisted development or looking for a more reliable way to scale it across a team, CafeKit provides a practical starting point. Want to see how it works in a real project? Book a walkthrough with the Haposoft team or try CafeKit on your next feature and experience the spec-to-ship workflow firsthand

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.