Have you ever asked someone to help you with a project, only to get back something that looks right but isn’t quite what you wanted? That’s exactly what happens when we work with AI coding assistants today. We describe what we want, get code back, and often find ourselves saying “Well, it’s close, but…”
GitHub just released a free tool called Spec Kit that solves this problem by teaching us a better way to communicate with AI assistants. Think of it as a structured conversation method that helps both you and the AI stay on the same page.
The Problem: Why “Just Tell the AI What You Want” Doesn’t Work
Imagine you’re renovating your kitchen and you tell the contractor: “I want it to look modern and functional.” Without more details, they’ll make their best guess based on what they think “modern” and “functional” mean. The result might be beautiful, but probably won’t match your vision.
The same thing happens with AI coding assistants. When we give vague instructions like “build me a photo sharing app,” the AI has to guess at hundreds of details:
- How should users organize their photos?
- Can they share albums with friends?
- Should it work on phones and computers?
- How do they sign in?
Some guesses will be right, some won’t, and you often won’t discover the problems until much later in the process.
The Solution: Spec-Driven Development
Spec-Driven Development is like having a detailed conversation before starting any work. Instead of jumping straight into building, you:
- Clearly describe what you want (the “what” and “why”)
- Plan how to build it (the technical approach)
- Break it into small steps (manageable tasks)
- Build it step by step (focused implementation)
The magic happens because each step builds on the previous one, creating a clear roadmap that both you and the AI can follow.
How Spec Kit Makes This Easy
Spec Kit provides a simple toolkit with four phases that anyone can learn:
Phase 1: Specify – “What do you want to build?”
You describe your vision in plain language, focusing on:
- Who will use it? (your target users)
- What problem does it solve? (the main purpose)
- How will people use it? (the user experience)
- What does success look like? (your goals)
Example: Instead of “build a task manager,” you’d say:
“Build a team productivity app where project managers can assign tasks to engineers, team members can move tasks between ‘To Do,’ ‘In Progress,’ and ‘Done’ columns, and everyone can leave comments on tasks. It should be easy to see at a glance which tasks are yours versus others.”
Phase 2: Plan – “How should we build it?”
Now you get technical (but still in everyday terms):
- What technology should we use? (website, mobile app, etc.)
- What are the constraints? (budget, timeline, compatibility needs)
- What are the rules? (security requirements, company standards)
Example:
“Build this as a simple web application that works in any browser. Store data locally on the user’s computer – no cloud storage needed. Keep it simple with minimal external dependencies.”
Phase 3: Tasks – “What are the specific steps?”
The AI breaks your big vision into small, manageable pieces:
- Create user login system
- Build the task board layout
- Add drag-and-drop functionality
- Implement commenting system
Each task is something that can be built and tested independently.
Phase 4: Implement – “Let’s build it!”
Your AI assistant tackles each task one by one, and you review focused changes instead of overwhelming code dumps.
Why This Approach Works Better
Traditional approach: “Build me a photo sharing app” → AI makes 1000 assumptions → You get something that’s 70% right
Spec-driven approach: Clear specification → Detailed plan → Small tasks → AI builds exactly what you described
The key insight is that AI assistants are incredibly good at following detailed instructions, but terrible at reading your mind. By being explicit upfront, you get much better results.
Getting Started with Spec Kit
Spec Kit works with popular AI coding assistants like:
- GitHub Copilot
- Claude Code
- Gemini CLI
Installing and Using Spec Kit
1. Install Specify
uv tool install specify-cli –from git+https://github.com/github/spec-kit.git
specify init reading-assistant
2. Establish project principles
/constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements
3. Create the spec
/specify
GOAL
– Input: URL (or pasted text)
– Process: Fetch article → summarize (150–250 words) → generate 3–5 practice questions
– Output: Markdown with Summary, Questions, Source
– Constraint: Minimal Python CLI
4. Create a technical implementation plan
/plan
ARCHITECTURE
– Python CLI with argparse
– Modules:
• fetcher.py: download HTML
• extractor.py: parse text with BeautifulSoup
• llm.py: call OpenAI (gpt-4o-mini)
• markdown.py: render Markdown
– Flow: URL/text → fetch & extract → LLM → Markdown → stdoutDEPENDENCIES
– requests, beautifulsoup4, python-dotenvOUTPUT FORMAT
# Summary
<summary># Questions
1. …
2. …# Source
<url or ‘pasted text’>
5. Break down into tasks
/tasks
– [ ] Setup project skeleton + requirements
– [ ] Implement fetcher (requests)
– [ ] Implement extractor (BeautifulSoup)
– [ ] Implement LLM client with prompt
– [ ] Implement Markdown renderer
– [ ] Wire CLI (argparse)
– [ ] Smoke test with one URL and one pasted file
– [ ] Add README with quick start
6. Execute implementation
/implement
FILES
1) requirements.txt
requests
beautifulsoup4
python-dotenv2) app.py
– argparse: –url, –text
– orchestrate modules and print Markdown3) fetcher.py
– fetch_url(url) with timeout, retry4) extractor.py
– extract_text(html) → title + paragraphs5) llm.py
– summarize_and_ask(text) → {“summary”: str, “questions”: [str]}
– uses OPENAI_API_KEY; friendly error if missing6) markdown.py
– render(result, source) → Markdown string7) README.md
– Quick start instructions
– Example commands
Result
References:
