LeanSpec: A Lightweight SDD Framework
# Introducing LeanSpec: A Lightweight Spec-Driven Development Framework
At the start of this year, I was astonished by the AI programming capabilities of **Claude Sonnet 3.7**.
While the term *Vibe Coding* wasn’t widely used yet, that’s exactly what I was doing — guiding AI to generate code while I focused on steering the conversation.
It felt magical… until the problems surfaced.
---
## The Rise and Fall of Vibe Coding
After several weeks, I began noticing patterns:
- **Redundant code** appearing across modules
- **Drifting implementation** — functional details straying from original intent
- **Lost context** between sessions, requiring constant rework
The honeymoon period was officially over. I needed a **structured AI coding approach** without heavy enterprise processes.
---
## Why LeanSpec Exists
Experimenting with **Kiro**, **Spec Kit**, and **OpenSpec** uncovered several drawbacks:
- **Vendor lock-in**
- Kiro (Amazon’s SDD IDE) is highly integrated but forces you to abandon existing tools.
- **High cognitive load**
- Spec Kit offers deep structure but demands mental overhead — too heavy for indie devs.
- **Poor multi-spec management**
- OpenSpec was close, but lacked robust project-level organization.
**LeanSpec** became the answer:
A **methodology-first** framework, light tools, minimal workflow disruption — similar to Agile in spirit, but built for modern AI-driven development.
---
## The Hidden Cost of Unstructured AI Coding
| Symptom | Root Cause | Impact |
|--------------------------------|--------------------------------------|------------------------------------------------------|
| **Code redundancy** | AI forgets prior implementations | Duplicate logic scattered throughout the project |
| **Intent drift** | Context loss between sessions | Features diverge from original vision |
| **Constant re-explaining** | No single source of truth | Wasted time and repeated background explanations |
| **Architectural inconsistency**| No structured guidance | Components fail to integrate smoothly |
✅ **Solution:** Spec-Driven Development (SDD) — maintain persistent specifications for AI and humans.
ℹ️ **Recommended Reading:**
[Spec-Driven Development: A Systematic Approach to Complex Features](https://marvinzhang.dev/zh/blog/spec-driven-development)
[The 2025 Landscape of SDD Tools](https://marvinzhang.dev/zh/blog/sdd-tools-practices)
[Practicing SDD Without Tools](https://www.lean-spec.dev/docs/tutorials/sdd-without-toolkit)
---
## First Principles of LeanSpec
LeanSpec rests on **five First Principles**:
1. **Context Economy**
- Specs must fit into human/AI working memory (≤300 lines, readable in under 10 min).
2. **Signal-to-Noise Maximization**
- Every line must drive a decision — zero filler.
3. **Intent Over Implementation**
- Document the *why*, not just *how*. Intent outlasts code details.
4. **Bridge the Gap**
- Specs must be equally clear to humans and AI.
5. **Progressive Disclosure**
- Start simple, add structure only when pain points appear.
LeanSpec’s `validate` command checks adherence automatically.
---
## Core Features
### 1. Web UI for Visual Spec ManagementLaunch Web UI
npx lean-spec ui
- Kanban view
- Detailed spec pages with Mermaid charts
- Dependency visualization
*LeanSpec Kanban View*
*Spec Detail Page*
---
### 2. First Principles Validationlean-spec validate
Example output:
specs/045-user-auth/README.md
⚠️ Spec exceeds 300 lines (342) context-economy
⚠️ Missing overview section structure
**Benefit:** Keeps specs concise & meaningful.
---
### 3. Intelligent Search & Project ManagementSemantic search
lean-spec search "authentication flow"
Advanced queries
lean-spec search "status:in-progress tag:api"
lean-spec search "created:>2025-11-01"
lean-spec board
📅 Planned (12) 🚧 In Progress (3) ✅ Complete (47)
---
### 4. MCP Server: AI Integration{
"mcpServers": {
"leanspec": {
"command": "npx",
"args": ["@leanspec/mcp"]
}
}
}
Enables tools like Claude Code, Cursor, GitHub Copilot to read/update specs directly.
---
## Development Journey
LeanSpec was **developed with LeanSpec itself**:
| Milestone | Date | Description |
|--------------------------|-------------|-------------------------------------------|
| First code | Oct 23, 2025| Basic spec CRUD |
| v0.1.0 | Nov 2, 2025 | 10 days from scratch to release |
| v0.2.0 | Nov 10, 2025| Added validation & full CLI |
| v0.2.7 | Nov 26, 2025| 10 versions released in 24 days |
120+ specs created — covering features, architecture, retrospectives, marketing.
---
## Unique Position in the SDD Landscape
| Dimension | Heavyweight Tools | LeanSpec |
|-------------------|----------------------------|---------------------------|
| Learning curve | Days–weeks | Minutes |
| Spec overhead | Large upfront work | Incremental |
| Token cost | Often > 2000 | Target < 300 lines |
| Flexibility | Rigid structure | Fits your workflow |
| Vendor lock-in | Common | Minimal |
---
## Quick Start Guide
Install & launch in 5 minutes:npm install -g lean-spec
lean-spec init
lean-spec create user-authentication
lean-spec ui
Try example projects:npx lean-spec init --example dark-theme
---
## Roadmap
- VS Code plugin (Spec #17)
- AI chat interface (Spec #94)
- Internationalization (Spec #91)
- GitHub multi-project support (Spec #98)
---
## Resources
- 📦 [GitHub](https://github.com/codervisor/lean-spec)
- 📚 [Docs](https://marvinzhang.dev/zh/blog/introducing-leanspec)
- 📊 [npm package](https://www.npmjs.com/package/lean-spec)
- 💬 [Discussions](https://github.com/codervisor/lean-spec/discussions)
**Full article:** [marvinzhang.dev: Introducing LeanSpec](https://marvinzhang.dev/zh/blog/introducing-leanspec)
---
## Final Thoughts
LeanSpec is built for developers who love AI-assisted coding but need **persistent, lightweight structure** to maintain quality over time.
If you’ve experienced code drift, redundant logic, or lost intent — LeanSpec may be the clarity your workflow needs.
Platforms like [AiToEarn官网](https://aitoearn.ai/) extend these principles beyond software — enabling open-source, cross-platform monetization of AI-generated creative work.
---
