github / github/spec-kit

[Experience Report] 2 months intensive Spec Kit usage by non-technical user

Open
#860 7 comments 5 reactions 0 assignees View on GitHub
stale
Dominant language
Python
Stars
137k
Forks
12.3k
Avg merge
2d 7h
Merged PRs (30d)
155

Description

## 👋 Context
- **Profile**: Non-technical (zero coding experience)
- **Tools used**: Claude Code + Spec Kit (transitioned from Super Claude)
- **Project**: File sharing system (Rust/SvelteKit)
- **Duration**: ~2 months, 6 features created
- **Transparency**: This project was built 100% with AI assistance

## 🎯 Why I'm sharing this
Spec Kit enabled me to build a production system without coding knowledge.
I've identified patterns (both positive and problematic) that could help
improve the framework for other non-technical users.

## 📊 Quick Metrics
| Feature | Spec Lines | Tasks | Status |
|---------|-----------|-------|--------|
| 009 | 420 | 46 | ✅ |
| 014 | 873 | 163 | WIP |

**Complexity escalation observed**: +107% (spec) and +254% (tasks)

## ⭐ What Works Exceptionally Well
1. **Project Constitution** (emergent pattern not in docs)
- Created 454-line constitution with 7 measurable principles
- Feature 014 entirely dedicated to reaching 100% compliance

2. **Structured User Stories with Priorities**
- P0/P1/P2 system works brilliantly for incremental delivery

3. **Clarifications Documentation** (spontaneous addition)
- Added Q&A sections naturally to specs
- Not in template but highly valuable

## ⚠️ Friction Points Identified
1. **Uncontrolled complexity escalation**
- 420 lines → 873 lines for similar features
- No guidance on "appropriate size"

2. **Bug-fix workflow inadequate**
- Feature 013: 142L spec but 0 tasks
- Framework optimized for new features, not bugs

3. **Over-specification risk for non-technical users**
- Without experience, hard to know when to stop detailing

## 💡 Concrete Recommendations
1. **Quick win**: Add "Clarifications" section to spec-template.md
2. **Medium**: Create bug-fix-template.md alternative
3. **Long-term**: Document "Constitution" pattern with examples

## 📝 Full Analysis Available
I've prepared a detailed analysis (2600+ words) with:
- Complete metrics for all 6 features
- Code examples from actual specs
- Detailed recommendations with templates

**Question for maintainers**: Would you prefer I:
- A) Post full analysis here (long but comprehensive)
- B) Link to external document (GitHub Gist or Google Doc)
- C) Break into multiple focused issues

I want to contribute constructively without creating noise.
Happy to iterate based on your preferences!

---
*Built with: Rust/Actix-web backend, SvelteKit frontend, all guided by Spec Kit + Claude Code*

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.