by Vinicius Negrisolo on October 14, 2025

The software development world is buzzing about a new paradigm that's changing how we build features: Spec-Driven Development. With tools like spec-kit from GitHub, product owners can now create comprehensive specifications with AI assistance, reducing ambiguity and accelerating the handoff to development teams. Let's run through the flow on a real project and see how hot it is.

To install the spec-kit from GitHub follow their docs and you may also need to install UV Python manager.

After installing spec-kit, I navigated to our project folder and ran:

specify init .

The tool prompted me to choose an AI platform (I selected claude) and a shell (zsh). Within seconds, it created Claude commands in a .claude/ folder and scripts and templates in .specify/.

Important: The tool warned us to add .claude/ to .gitignore to prevent credential leakage - definitely heed that advice.

> Consider adding .claude/ (or parts of it) to .gitignore to prevent accidental credential leakage.

Throughout this process, the AI interacted with me multiple times. For this experiment, I accepted all suggestions as is just to see how autonomous the workflow can be. Pro tip: Commit your changes frequently at each step. These AI interactions generate substantial content, and you'll want granular git history to review changes easily.

With setup complete, I opened Claude Code:

claude

The first critical step in Spec-Driven Development is creating a constitution. A foundational document that guides all future specifications and changes. Inside Claude Code, I ran:

/speckit.constitution

While you can provide input to shape your constitution, the default template is remarkably intelligent. It inferred valuable information from our codebase automatically, generating a 250-line .specify/memory/constitution.md file in this project that I am working on.

Yes, it's wordy. But it's worth reviewing and refining this document - it becomes the bedrock for every spec you create. As your project evolves, revisit and update the constitution to keep it aligned with your current standards and practices.

Side Note: Spec-kit maintains files in the memory/ folder that load automatically in each new AI session, ensuring consistency across your workflow.

With our project configured, we're ready for actual Spec-Driven Development. This workflow brilliantly separates "product owner" responsibilities from "developer" tasks. Let's explore the product owner's side first.

Our product owner gave us minimal direction: "Remove the Team Tab from top of website. Leave it in the footer." That's it - one sentence.

We started the spec with:

/speckit.specify Remove the Team Tab from top of website. Leave it in the footer.

I knew this was a simple change, possibly just one line of code, but I wanted to test spec-kit's capabilities on a stable, well-tested codebase.

Within a couple of minutes, the AI:

• Created a git branch and checked it out
• Generated two comprehensive files:
  • specs/001-remove-the-team/spec.md
  • specs/001-remove-the-team/checklists/requirements.md

The automatic branch creation and organized folder structure is a great starting point. Technically, you should review these files carefully (and regenerate if needed), but they can be lengthy and time-consuming to read thoroughly.

As a start the spec.md file bring Acceptance Scenarios and Edge Cases, which are valuable info:

**Acceptance Scenarios**:

1. **Given** a visitor is on the homepage, **When** they view the header navigation, **Then** the Team link should not be visible in the header menu
2. **Given** a visitor is on any page of the website, **When** they scroll to the footer, **Then** the Team link should be visible and clickable in the footer navigation
3. **Given** a visitor clicks the Team link in the footer, **When** the page loads, **Then** they should be taken to the team page
4. **Given** a visitor is on the team page, **When** they view the header navigation, **Then** no Team link should be highlighted or visible in the header

### Edge Cases

- What happens when users have bookmarked the team page? The team page should remain accessible at its current URL
- What happens when users navigate directly to /team or /rocketeers URLs? These URLs should continue to work normally
- What happens on mobile devices? The header navigation should not show Team in the mobile menu
- What happens when users are already on the team page? The page should remain functional with footer navigation available

Here's an honest observation: Spec-Driven Development generates significant text as a byproduct. You could view this as waste - or recognize it as structured information for the AI to consume downstream. In practice, I found myself glancing at these files rather than deep-reading them, trusting the AI to do the heavy lifting. In the end AI is there to help us to produce code faster not to delay us.

The next optional step lets the AI identify and resolve unclear requirements. I noticed in the requirements file: - [x] No [NEEDS CLARIFICATION] markers remain, so I ran:

/speckit.clarify

The result came back in under a minute:

After reviewing the specification against the ambiguity taxonomy, I've found that this is
a well-defined, straightforward feature with clear requirements.

No critical ambiguities detected worth formal clarification.

Recommendation
✅ Proceed to /speckit.plan to create the implementation plan.

The AI resolved its own questions autonomously. Am I just a rubber duck now? Quack quack.

But here's the real value: On more complex features, the clarify step asked genuinely insightful questions. The kind that tech teams typically raise when discussing requirements with product owners. Questions about edge cases, user flows, error/empty states. If AI can surface these ambiguities before specs reach developers, it saves entire teams from prolonged meetings and back-and-forth conversations.

At this point, the product owner's responsibilities are complete. We've transformed a single sentence into a comprehensive, clarified specification ready for the development team.

In our next post, we'll dive into the technical part of the workflow - how developers turn these specs into working-tested code. Stay tuned to see how the entire process comes together.

At Hashrocket, we've been crafting exceptional web and mobile applications for over a decade. Whether you're working with Elixir, Phoenix, Ruby on Rails, React, React Native, or other modern technologies, our team can help you build better, faster, ship smarter, and deliver products your users love.

We're passionate about developer productivity, clean architecture, and emerging tools like Spec-Driven Development. If you're looking for a partner who stays on the cutting edge while delivering reliable, maintainable code, let's talk.

Let's build something great together.