Skip to main content

What is LeanSpec?

LeanSpec is a lightweight, agile Spec-Driven Development (SDD) methodology and adaptive workflow designed to reduce spec "mind burden" and keep teams—both humans and AI coding agents—focused on what truly matters.

LeanSpec is not just a document—it's an adaptive workflow, SOP (Standard Operating Procedure), and living process for AI-powered development teams.

The Problem​

Traditional software specifications often suffer from:

  • Documentation Overload: Lengthy documents that nobody (human or AI) reads or maintains
  • Frozen Contracts: Specs that become outdated as soon as development begins
  • Exhaustive Overthinking: Trying to document every possible edge case upfront
  • Mind Burden: Cognitive load from managing verbose, complicated documentation
  • Lost Intent: The "why" gets buried under mountains of "what" and "how"

Development teams—including AI coding agents—need clear direction without being buried in documentation debt.

The LeanSpec Solution​

LeanSpec is a mindset and methodology, not a rigid format or tool. It's about capturing what truly matters with minimal overhead.

A simple example structure might include:

  • The Goal: Why this work exists
  • Key Scenarios: The critical user journeys that must succeed
  • Acceptance Criteria: Clear, testable conditions for "done"
  • Technical Contracts: Essential interfaces and constraints
  • Non-Goals: What we're explicitly not doing (to maintain focus)

But the key is the mindset: focus on clarity, keep it lean, make it living documentation. The structure should serve your needs, not constrain them.

Key Benefits​

For Development Teams​

  • Reduced Cognitive Load: Short, scannable specs that are easy to understand
  • Faster Onboarding: New team members quickly grasp project direction
  • Better Alignment: Everyone shares the same understanding
  • Living Documentation: Specs stay current as requirements evolve
  • Focus on Outcomes: Emphasis on "what" and "why" over implementation details

For AI Coding Agents​

  • Clear Context: Starting with "why" gives AI agents the purpose behind the work
  • Concrete Scenarios: Specific examples help AI understand expected behavior
  • Testable Criteria: Clear targets guide AI implementation
  • Boundaries: Explicit non-goals help AI avoid scope creep
  • Adaptable Structure: Whatever format you choose, consistency helps AI parse effectively

AI coding agents work best with clear, concise specifications that balance context with brevity—exactly what the LeanSpec mindset promotes.

What You Get​

Core CLI - Lightweight spec management from your terminal:

  • Create, organize, and search specs with simple commands
  • Track project health with Kanban board (lean-spec board) and analytics (lean-spec stats)
  • Validate specs for quality and complexity (lean-spec validate)
  • Understand dependencies between specs (lean-spec deps)
  • Full CLI reference →

MCP Server - Native AI assistant integration:

  • Works with Claude Desktop, Cline, and other MCP-compatible tools
  • Your specs are available directly in AI chat context
  • AI agents can read, search, and understand your specs
  • Setup guide →

Templates & Customization:

  • Three templates: minimal, standard, enterprise
  • Custom fields adapt to your workflow
  • Progressive structure that grows with your team

Want to see what's coming next? Check out our roadmap for planned features like VS Code extensions, GitHub Actions, and more.

A Simple Example​

Here's an example structure (adapt sections to your needs):

---
status: in-progress
created: 2025-11-07
tags: [api, feature]
priority: high
---

# User Authentication API

## Goal
Enable secure user login and session management for the mobile app.

## Key Scenarios
1. User logs in with email/password → receives JWT token
2. User accesses protected endpoint with token → gets data
3. User token expires → receives 401, must re-authenticate

## Acceptance Criteria
- [ ] Login endpoint returns valid JWT on success
- [ ] JWT includes user ID and expiration
- [ ] Protected endpoints verify JWT signature
- [ ] Expired tokens are rejected with 401

## Technical Contracts
- Endpoint: POST /api/auth/login
- Token expiration: 24 hours
- Password hashing: bcrypt

## Non-Goals
- Social login (future feature)
- Password reset (separate spec)
- Two-factor auth (not needed yet)

Clean, focused, and actionable.

Philosophy​

"The best spec is the one that gets read, understood, and acted upon—by humans and AI alike."

LeanSpec embraces:

  • Start with why: What problem are you solving?
  • Capture the essentials: What absolutely must be communicated?
  • Stay lean: If it doesn't add clarity, cut it
  • Keep it living: Update as you learn

Next Steps​

Ready to get started? Head over to the Getting Started guide to install LeanSpec and create your first spec.

Want to understand the foundational constraints? Start with Understanding LeanSpec to see why LeanSpec is designed the way it is.

Need practical execution guidance? Explore The 12 Patterns for AI‑Executable Specs for day-to-day techniques.

Working with AI coding agents? See Agent Configuration and MCP Integration for setup guidance.