Quick Start: Existing Project

Add Spec Kit to your existing codebase and build features the smart way.

📖 Table of Contents

• Why Use Spec Kit for Existing Projects?
• Quick Setup
• The Workflow
  • Step 1: Constitution with Constraints
  • Step 2: Specify the Feature
  • Step 3: Clarify Assumptions
  • Step 4: Validate with Checklists
  • Step 5: Technical Plan with Guidance
  • Step 6: Analyze & Iterate
  • Step 7: Generate Tasks
  • Step 8: Implement
  • Step 9: Encode Learnings
• Key Principles
• Real Example: Hugo Blog
• Troubleshooting
• What's Next?

Why Use Spec Kit for Existing Projects?

✅ Add new features without breaking existing code ✅ Guide AI with constraints about your architecture ✅ Document decisions for future refactoring ✅ Safe experimentation with git branches ✅ Team collaboration on feature specs

Quick Setup

Initialize in Your Project

cd my-existing-project
specify init . --ai copilot --script bash

What it adds:

• .github/copilot-instructions.md (or equivalent for your agent)
• .speckit/ folder (templates, scripts, memory)
• Does NOT modify your existing code!

The Workflow

Step 1: Constitution with Constraints

Command: /speckit.constitution

Critical: Define constraints based on your EXISTING architecture:

Static site built with Hugo.
Use existing theme in themes/ folder.
No extra dependencies - no package.json.
Data stored in config/ folder using TOML files.

Why this matters: Prevents AI from introducing unwanted frameworks

Step 2: Specify the Feature

Command: /speckit.specify

Be VERY specific about existing patterns:

Building a reading list page at /books route.
Data populated from config/ folder using TOML files.
Must follow existing site patterns.
Add navigation link in footer via existing TOML config.
DO NOT create new HTML templates from scratch - use existing partials.

Key principle: Reference existing files, folders, and patterns explicitly!

Step 3: Clarify Assumptions

Command: /speckit.clarify

Especially important for existing projects - AI will ask about:

• Ordering/sorting
• Pagination
• Data structure
• Integration points

AI: Where should the books data be stored?
A) /data/books/
B) /config/books.toml
C) /content/books/

You: B (matching existing config pattern)

Step 4: Validate with Checklists ✨ NEW!

Command: /speckit.checklist

Generate checklists to ensure compatibility:

/speckit.checklist UX
/speckit.checklist security

Then cross-check:

Cross-check the UX checklist with spec.md

Pro tip: Use accessibility checklist if your existing site has WCAG requirements

Step 5: Technical Plan with Guidance

Command: /speckit.plan

Guide AI to use existing infrastructure:

Consult README for project details.
No frameworks - do not introduce new ones.
Adding new template to Hugo-based website.
Use existing theme styles and layouts.
Not writing tests (or specify test requirements).

Common mistakes to avoid:

• ❌ Letting AI guess your architecture
• ❌ Not mentioning existing config locations
• ❌ Assuming AI knows your naming conventions

Step 6: Analyze & Iterate

Command: /speckit.analyze

Critical for existing projects - Catches conflicts:

Issue: Plan uses data/ but config/ exists in project
Recommendation: Update plan to use config/books.toml

Issue: Spec doesn't mention existing footer structure
Recommendation: Add detail about TOML-based navigation

Fix issues before proceeding:

Address issues A1 and I1.
Use standard Hugo conventions from existing codebase.
Update spec, plan, and tasks as appropriate.

Step 7: Generate Tasks

Command: /speckit.tasks

Tasks will be organized by MVP phases:

Phase 1: Setup
- Review existing project structure
- Identify integration points

Phase 2: Prerequisites
- Create data file in config/books.toml
- Set up template structure

Phase 3: MVP
- Implement books list page
- Add footer navigation link

Step 8: Implement

Command: /speckit.implement

AI builds on your existing codebase:

/speckit.implement

It will:

• Read existing structure
• Follow established patterns
• Use existing styles and components
• Respect your architecture

Step 9: Encode Learnings ⚠️ Critical!

After implementation, update the spec with what you learned:

Based on the conversation, encode the learnings
and experience pieces (not technical details)
into spec.md for the current feature.

Then:
Transform the learnings into relevant functional requirements.

Why this matters: Future rebuilds or tech stack migrations will be much easier!

Key Principles

✅ DO

1. Guide with constraints

   Use TOML config like in config/default/
   Follow existing component structure in layouts/
   

2. Reference existing files explicitly

   Add to footer using footer.toml, not by editing HTML
   

3. Iterate and refine

   • Test locally after each phase
   • Fix issues incrementally
   • Re-encode learnings in spec

4. Use git branches

   • Spec Kit creates feature branches automatically
   • Safe to experiment without breaking main

5. Switch models if needed

   • Try GPT*-4 and Claude* Sonnet 4
   • Different models understand different patterns better

❌ DON'T

1. Don't let AI guess

   • Always be explicit about architecture
   • Point to existing patterns

2. Don't skip encoding learnings

   • After iterating, update spec with refinements
   • Makes future rebuilds possible

3. Don't forget git workflow

   • Commit working code frequently
   • Review changes before committing
   • Discard unwanted changes

Real Example: Hugo Blog

Project: 10-year-old Hugo blog Goal: Add reading list feature

Constitution

Static site with no frameworks.
Built with Hugo.
Use existing theme in themes/ folder.
No extra dependencies - no package.json.

Specification

Building a reading list page at /books route.
Display books in grid with covers, titles, ratings.
Data from TOML files (Hugo pattern).
Add navigation link in footer via existing TOML config.

Clarification

AI: How should books be ordered?
You: By date finished reading (most recent first)

AI: Pagination size?
You: 20 books per page

AI: Star rating display?
You: Visual stars + numeric (4/5)

Analysis

Issue: Spec says config/ but plan uses data/
Fix: Use data/ (Hugo standard)
Update spec, plan, and tasks.

Result

✅ Reading list integrated with existing blog ✅ Respects 10-year-old architecture ✅ Spec captures initial + learned requirements ✅ Can rebuild if migrating to different SSG

See it live: den.dev/books/

Troubleshooting

Issue: AI creates unwanted files

Solution: Use git to unwind

1. Update spec with correct requirements
2. Commit spec changes
3. Discard code changes in git client
4. Re-implement from updated spec

Issue: AI ignores existing patterns

Solution: Be more explicit

Instead of: "Add configuration"
Better: "Add books.toml to config/ folder, following pattern in config/default/params.toml"

Issue: Spec drifts from implementation

Solution: Encode learnings

After iterations:
"Encode learnings into spec.md for current feature"
"Transform learnings into functional requirements"

What's Next?

• Command Reference - All commands explained
• Complete Guide - Advanced tips and FAQ
• New Project Guide - Starting from scratch

Need Help?

• GitHub Discussions*: Ask questions
• Video Tutorial: Existing projects walkthrough
• Blog Example: Real implementation

Transform your existing codebase with spec-driven development! 🎯