cc-sdd Tutorial: Your First Spec-Driven Feature in 30 Minutes
A hands-on walkthrough of installing cc-sdd, running steering on a real project, and using the full SDD pipeline to build a user profile feature.
DevForge Team
AI Development Educators
What You Will Build
By the end of this tutorial, you will have used the complete SDD pipeline to build a user profile editing feature on a real Next.js project. The feature includes: profile display page, edit form with validation, and avatar upload. Time: approximately 30 minutes.
Prerequisites: A Next.js project with Supabase auth already configured, and Claude Code installed.
Step 1: Install cc-sdd (2 min)
In your project root:
npx cc-sdd@latestThis creates a .kiro/ directory with three subdirectories:
.kiro/steering/— will contain project memory files.kiro/specs/— will contain feature specifications.kiro/settings/— templates and custom rules
Add .kiro/ to your git repository. This is team-shared context.
Step 2: Run Steering (5 min)
In Claude Code, type:
/kiro:steeringClaude Code reads your entire codebase and generates steering files. Here is what was generated for a sample Next.js project:
architecture.md (generated):
# Architecture
## System Overview
Next.js 14 App Router application with Supabase backend.
Server Components for data fetching, Client Components for interactivity.
## Directory Structure
- app/ — Next.js App Router pages and layouts
- components/ — Reusable React components
- lib/ — Utilities, Supabase client, type definitions
- public/ — Static assets
## Key Patterns
- Server Components fetch data directly via supabase server client
- Client Components receive data as props, handle user interactions
- Forms use Server Actions for mutations
- All types defined in lib/types.tsReview the generated files. Add any rules the AI missed:
# Add to domain-rules.md
- User avatars stored in Supabase Storage bucket "avatars"
- Display names must be 2-50 characters, no special characters
- Profile slugs are auto-generated from display name, must be uniqueStep 3: Initialize the Feature (1 min)
/kiro:spec-init "user profile editing — display name, bio, avatar upload, profile page"cc-sdd creates .kiro/specs/user-profile/ with empty template files.
Step 4: Generate Requirements (5 min)
/kiro:spec-requirements user-profileThe generated requirements.md:
# User Profile Requirements
REQ-001 (Ubiquitous): The system shall display user profiles at /profile/[slug] showing display name, bio, avatar, and post count.
REQ-002 (Event-driven): When an authenticated user visits /profile/edit, the system shall display a form pre-populated with their current profile data.
REQ-003 (Event-driven): When a user submits valid profile updates, the system shall save the changes and redirect to their profile page with a success message.
REQ-004 (Unwanted behavior): If a user submits a display name shorter than 2 characters, the system shall show "Display name must be at least 2 characters" and block submission.
REQ-005 (Event-driven): When a user uploads a new avatar image, the system shall upload it to Supabase Storage, generate a public URL, and update the user's profile record.
REQ-006 (Unwanted behavior): If a user uploads a file larger than 5MB or not an image format, the system shall show an appropriate error and reject the upload.
REQ-007 (State-driven): While a profile update is saving, the system shall disable the submit button and show a loading indicator.Review gate: Does this match your intent? Are there missing requirements? For this example, we add REQ-008: "The system shall generate a URL-safe profile slug from the display name on save."
Approve and continue.
Step 5: Generate Design (5 min)
/kiro:spec-design user-profileThe generated design.md includes:
Database schema addition:
ALTER TABLE profiles ADD COLUMN IF NOT EXISTS bio TEXT;
ALTER TABLE profiles ADD COLUMN IF NOT EXISTS avatar_url TEXT;
ALTER TABLE profiles ADD COLUMN IF NOT EXISTS slug TEXT UNIQUE;
CREATE INDEX idx_profiles_slug ON profiles(slug);API Routes (Server Actions):
updateProfile(data)— validates and updates profile recorduploadAvatar(file)— uploads to Supabase Storage, returns URL
Components:
ProfilePage— Server Component, fetches by slug, renders profileProfileEditForm— Client Component, form with React Hook Form + ZodAvatarUpload— Client Component, handles file selection and preview
Review gate: Does the schema match your database? Are the server actions consistent with your existing patterns? Approve.
Step 6: Generate Tasks (2 min)
/kiro:spec-tasks user-profileGenerated tasks.md (abbreviated):
Task 1.1 [P0] — Add bio, avatar_url, slug columns to profiles table
Task 1.2 [P0] — Create updateProfile server action with Zod validation
Task 1.3 [P1] — Create uploadAvatar server action with file validation
Task 2.1 [P0] — Build ProfilePage server component
Task 2.2 [P0] — Build ProfileEditForm client component
Task 2.3 [P1] — Build AvatarUpload component with preview
Task 3.1 [P0] — Integration test: full profile edit flowStep 7: Implement (10 min)
Start with the foundation:
/kiro:spec-impl user-profile 1.1,1.2,1.3Claude Code creates the migration and server actions. Review the output — it should match the design document exactly.
Then the UI:
/kiro:spec-impl user-profile 2.1,2.2,2.3The Result
A fully implemented feature with: database migration, server actions with validation, profile display page, edit form with Zod schema, and avatar upload with file validation. All tracing back to REQ-001 through REQ-008.
Compare to building the same feature with a single ad-hoc Claude Code prompt. The SDD approach took longer at the spec stage, but required no fixes after implementation because the spec was precise enough to implement correctly.
For the complete SDD curriculum, see the SDD Framework module.