An AI collaboration platform that helps technical specification writing through dual-Claude architecture, ensuring you build the right thing before you write a single line of code.
SpecDrafter - Where two AI minds collaborate to transform your ideas into crystal-clear technical specifications.
Ever spent weeks building a feature only to realize it wasn't what you actually needed?
Building software without clear specifications is like constructing a house without blueprints. SpecDrafter ensures you build the right thing from the start.
❌ Requirements get lost in translation between stakeholders and developers
❌ Over-engineering creeps in - building features nobody asked for
❌ Technical constraints discovered too late in the process
❌ Specs take forever to write and become outdated immediately
✅ Two Specialized AI Minds Working Together:
| AI Role | What It Does | Why It Matters |
|---|---|---|
| Discovery AI 🔵 | • Talks to humans naturally • Challenges assumptions • Anti-over-engineering built-in |
Gets to what users ACTUALLY need, not what they think they want |
| Review AI 🔴 | • Technical reality checks • Feasibility analysis • Architecture validation |
Catches problems before you write code |
- Node.js 18+ (required for ES modules)
- Claude Code installed globally
- Valid Claude API credentials
While SpecDrafter works out of the box, installing these MCP servers greatly enhances the AI's capabilities:
- Context7 - Provides up-to-date library documentation for Review AI's technical analysis
- DeepWiki - Enables AI to access and search public repository documentation
These servers allow the Review AI to validate technical decisions against current best practices and real-world implementations.
# Clone the repository
git clone https://github.com/peterkrueck/SpecDrafter.git
cd SpecDrafter
# Install dependencies
npm install
# Start the application
npm startThe application will open at:
- Frontend: http://localhost:3001
- Backend: http://localhost:3002
┌─────────────────────────────── USER INTERFACE ───────────────────────────────┐
│ │
│ ┌─────────────────────┐ ┌──────────────────────────────┐ │
│ │ │ │ │ │
│ │ CHAT PANEL │ │ COLLABORATION PANEL │ │
│ │ │ │ │ │
│ │ User ←→ Discovery │ │ ┌────────────────────────┐ │ │
│ │ │ │ │ AI Dialogue Tab │ │ │
│ │ - Natural language │ │ │ │ │ │
│ │ - Requirements │ │ │ Discovery ←→ Review │ │ │
│ │ - Q&A flow │ │ │ Real-time dialogue │ │ │
│ │ │ │ └────────────────────────┘ │ │
│ │ │ │ ┌────────────────────────┐ │ │
│ │ [Generate & Review │ │ │ Specification Tab │ │ │
│ │ Spec Button] │ │ │ │ │ │
│ │ │ │ │ Live spec preview │ │ │
│ │ │ │ │ Markdown → HTML │ │ │
│ └──────────┬──────────┘ │ └────────────────────────┘ │ │
│ │ └──────────────────────────────┘ │
└─────────────┼────────────────────────────────────────────────────────────────┘
│
│ User message
▼
┌─────────────────────────┐ @review: ┌─────────────────────────┐
│ │ ─────────────────→ │ │
│ DISCOVERY AI │ │ REVIEW AI │
│ (Claude Instance 1) │ │ (Claude Instance 2) │
│ │ ←───────────────── │ │
│ • Requirements focus │ Auto-routed │ • Technical analysis │
│ • User communication │ responses │ • Feasibility checks │
│ • Anti-over-engineering │ │ • Architecture review │
│ • Spec drafting │ │ • No user interaction │
└────────────┬────────────┘ └─────────────────────────┘
│
│ Final specification
▼
┌──────────────┐
│ SPEC OUTPUT │
│ │
│ specs/*/ │
│ spec.md │
└──────────────┘
Each AI has its own CLAUDE.md configuration:
backend/workspaces/requirements-discovery/CLAUDE.md- Discovery AI behaviorbackend/workspaces/technical-review/CLAUDE.md- Review AI behavior
Choose between two Claude 4 models:
- Opus: Best for complex projects requiring deep analysis
- Sonnet: Balanced performance for most use cases (default)
# Optional: Set custom ports
FRONTEND_PORT=3001
BACKEND_PORT=3002
# Optional: Enable debug logging
DEBUG=true- Don't Use Claude Code While Using SpecDrafter: Avoid using Claude Code simultaneously as this can lead to context mixing
- Use Opus 4.1 Model: Opus 4.1 is recommended as it follows instructions best
- Let Discovery AI Lead: Don't jump straight to technical details
- Trust the Process: The anti-over-engineering principle works
- Watch the Collaboration: Understanding AI reasoning helps you make better decisions
- Iterate: Use the Review AI's feedback to refine requirements
- Export Early: Download specs as markdown for version control
No. SpecDrafter is built with the Claude Code SDK which requires a locally installed Claude Code CLI. You must have Claude Code installed (
npm install -g @anthropic-ai/claude-code) and connected to your Anthropic account with valid API credentials. The entire dual-AI architecture depends on the Claude Code SDK for managing the AI instances.
SpecDrafter implements a dual-AI system where two specialized Claude instances collaborate. Discovery AI focuses on understanding your actual needs while Review AI ensures technical feasibility. You get the benefit of two expert perspectives working together, plus a structured specification process.
Currently, SpecDrafter is optimized for English. The AI instructions and prompts are in English, though Claude can understand other languages.
All specifications are stored locally in your
specs/directory. Nothing is sent to external servers except the Claude API calls for AI processing.
Yes! Each AI's behavior is controlled by its
CLAUDE.mdfile in the workspaces directory. You can modify these to adjust how the AIs interact with users and each other.
Separation of concerns. Discovery AI can focus entirely on understanding user needs without getting bogged down in implementation details. Review AI can be brutally honest about technical feasibility without worrying about user relationships. This creates better outcomes than a single AI trying to balance both roles.
Absolutely! SpecDrafter adapts its communication style based on your technical background. Non-technical users get plain English explanations, while developers can dive into technical details.
No. SpecDrafter implements strict security sandboxing for both AI instances:
File System Access:
- Both AIs can ONLY access the
specs/directory in your project- No access to your home directory, system files, or other projects
- Discovery AI can read/write specifications only
- Review AI has read-only access (cannot modify any files)
Tool Restrictions:
- No shell/bash access - Neither AI can execute system commands
- No arbitrary code execution - AIs cannot run scripts or programs
- Limited to safe operations: File reading, web searches, and documentation lookups
- Discovery AI cannot spawn sub-agents (no Task tool)
- Review AI cannot modify files (no Write/Edit tools)
What Each AI Can Do:
- Discovery AI: Read/write specs, search web, fetch documentation
- Review AI: Read specs only, analyze code, spawn analysis sub-agents
This sandboxing is enforced through Claude Code's permission system (
.claude/settings.jsonin each workspace), ensuring the AIs can help you create specifications without any risk to your system or other files. You can verify these restrictions yourself in thebackend/workspaces/directory.
We welcome contributions in many ways:
- Code Contributions: Submit PRs for bug fixes, features, or improvements
- Documentation: Help improve docs, add examples, or translate content
- Testing & Feedback: Use SpecDrafter and share your experience
- Report Issues: Found a bug? Let us know!
- Feature Ideas: Share your ideas for making SpecDrafter better
Check the
Open_Issues/folder to see documented challenges where we'd especially appreciate help. Each file contains detailed investigation notes that can help you understand the codebase better.
Apache License 2.0 - see LICENSE.md for details.
- Built with Claude Code SDK
- Inspired by the need for better requirements engineering
- UI design inspired by Freigeist.dev aesthetics
Remember: The best code is the code you don't have to write because you built the right thing the first time. 🎯
Feel free to contact me on LinkedIn: https://www.linkedin.com/in/peterkrueck/