Skip to main content

Understanding LeanSpec

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

LeanSpec is a mindset and methodology for writing specifications that actually get used in AI-powered development. It's built on immutable constraints (physics, biology, economics) and designed to bridge human intent with machine execution.

What is LeanSpec?​

LeanSpec is:

  • A constraint-based methodology for writing specs that fit in working memory
  • A bridge between human intent and AI agent execution
  • A context engineering practice for managing AI working memory
  • A persistent memory layer for AI agents across sessions
  • An agile approach to specification: start small, iterate, focus on outcomes

LeanSpec provides:

  • CLI tooling for creating and managing specs
  • Structured frontmatter for project management (status, tags, dependencies)
  • MCP server integration for AI agent access
  • Sub-spec files for managing complexity
  • Validation and project health tracking

The Problem LeanSpec Solves​

Traditional Specs Fail​

Traditional specifications fail for predictable reasons:

  • Too long → Nobody reads them (violates working memory limits)
  • Too detailed → They become outdated quickly (maintenance burden)
  • Too rigid → They can't adapt as understanding grows (premature structure)
  • Too formal → They discourage collaboration (friction over value)

These aren't process failures—they're constraint violations.

The AI-Powered Development Gap​

In AI-assisted development, a new challenge emerges:

  • Human thinks in goals and context ("Make the dashboard fast")
  • AI needs clear, unambiguous instructions ("Cache with Redis, <100ms p95")
  • The gap must be bridged or AI hallucinates, misunderstands, or asks repeatedly

Traditional documentation doesn't bridge this gap because it's either:

  • Too vague for AI execution (high-level strategy docs)
  • Too detailed for human reading (comprehensive API references)
  • Not structured for AI retrieval (prose without examples/criteria)

Why Existing Solutions Fall Short​

Why not just use tickets/issues?

  • Too brief for complex features (no rationale, constraints, or trade-offs)
  • No persistent memory for AI agents (each session starts fresh)
  • Hard to maintain context across multiple issues

Why not comprehensive documentation?

  • Too long to fit in AI context windows (>10k lines common)
  • Too formal and exhaustive (violates Signal-to-Noise)
  • Maintenance burden scales with size (becomes outdated)

Why not just chat with AI?

  • Context is ephemeral (lost between sessions)
  • No persistent record of decisions
  • Can't scale to team collaboration
  • Requires re-explaining context repeatedly

The LeanSpec Solution​

LeanSpec works because it aligns with how humans and AI actually work:

1. Respects Fundamental Constraints​

Based on three immutable constraints:

  • Physics: Context windows are limited (even with 1M+ tokens)
  • Biology: Working memory is small (~7 items, 5-10 min attention)
  • Economics: Time and tokens cost money

→ Context Economy: Specs must fit in working memory (<400 lines)

2. Bridges Human and AI Understanding​

Specs written for both audiences:

  • For humans: Clear problem, rationale, trade-offs (why it matters)
  • For AI: Structured requirements, examples, success criteria (what to build)
  • Both get: Natural language + structured data they can parse

→ Bridge the Gap: Align human intent with machine execution

3. Serves as Persistent Memory​

Specs function as semantic memory for AI agents:

  • Decisions and rationale persist across sessions
  • MCP server enables reliable retrieval
  • Cross-references create knowledge graph
  • Updates keep memory current

→ AI Agent Memory: Context that survives beyond chat sessions

4. Applies Context Engineering​

Manages AI working memory proactively:

  • Partition (split into sub-specs when >400 lines)
  • Compact (remove redundancy)
  • Compress (summarize completed phases)
  • Isolate (separate unrelated concerns)

→ Context Engineering: Prevent context failures before they happen

5. Embraces Progressive Disclosure​

Start simple, add structure only when pain is felt:

  • Solo dev: Just status + created date
  • Small team: Add tags, priority
  • Enterprise: Add assignee, epic, sprint

→ Progressive Disclosure: No premature abstraction

When to Use LeanSpec​

LeanSpec is designed for AI-powered SDD (Spec-Driven Development). Write a spec when it helps bridge human intent to machine execution. Skip it when the gap is already clear.

Write a Spec When...​

🎯 Intent needs clarification:

  • Multiple valid interpretations exist
  • Trade-offs or constraints aren't obvious
  • "Why" matters as much as "what"
  • Decisions need to be documented

🤖 AI will implement:

  • AI agent needs executable context
  • Success criteria must be explicit
  • Constraints aren't inferable from code
  • Implementation paths need to be narrowed

🏗️ Work is significant:

  • Touches multiple parts of the system
  • Architectural or structural changes
  • Breaking changes or major refactors
  • Cross-system dependencies

📚 Knowledge needs capture:

  • Research findings and trade-offs
  • Technical exploration or experiments
  • Retrospectives (what worked, what didn't)
  • Decisions for future reference

Examples:

  • New feature with AI implementation
  • API design affecting multiple consumers
  • Architecture decision (microservices vs monolith)
  • Significant refactoring (not trivial renames)
  • Research spike documenting findings

Skip the Spec When...​

✂️ Intent is self-evident:

  • Obvious bug fixes (clear cause, clear fix)
  • Trivial refactoring (rename, extract function, format)
  • Well-documented in code/comments already
  • Change is purely mechanical

🔬 Work is exploratory:

  • Rapid prototyping to discover requirements
  • Experimenting with multiple approaches
  • High uncertainty, likely to throw away
  • Learning by doing is faster

Note: Write a spec after prototyping to capture learnings

📄 Wrong tool for the job:

  • API reference docs (use auto-generated docs)
  • User manuals (use dedicated tools)
  • Compliance docs with specific formats (use required format)
  • Dependency updates (standard version bumps)

Examples:

  • One-line bug fix
  • Simple rename or code formatting
  • Standard dependency version bump
  • Experimental prototype (document after if it works)

The Core Question​

"Will a spec help bridge human intent to machine execution, or is the gap already clear?"

If yes → Write it (keep it <300 lines)
If no → Skip it or use code/comments

Apply First Principles to guide judgment.

How LeanSpec Works in Practice​

The SDD Workflow​

  1. Discover - Check existing specs with lean-spec list
  2. Plan - Create spec with lean-spec create <name> when needed
  3. Implement - Write code, keep spec in sync as you learn
  4. Update - Mark progress with lean-spec update <spec> --status <status>
  5. Complete - Mark complete when done, archive if finished

For Solo Development​

  • Start minimal (just status + created date)
  • Add structure as needs emerge
  • Use specs for complex features you'll forget
  • Let AI agents implement from specs

For Team Development​

  • Specs provide shared understanding
  • Dependencies track coordination needs
  • Board view shows project health
  • MCP enables AI collaboration across team

For AI-Powered Development​

Specs serve dual purposes:

  • Human-AI bridge: Translate intent into executable context
  • AI memory: Persist decisions and rationale across sessions

AI can help write specs:

  • Human provides intent, constraints, success criteria
  • AI drafts structure, examples, formatting
  • Human refines for clarity and lean principles

Three modes of spec creation:

  1. Human-written, AI-implemented - You write spec, AI builds from it
  2. AI-drafted, human-refined - AI drafts spec from your intent, you review/refine
  3. Co-created iteratively - Build spec together through conversation

All three modes are valid. Choose based on context.

AI-assisted spec writing decision:

When AI helps with spec authoring, the decision shifts from "Will AI need this to execute?" to:

"Does formalizing intent as a spec add value over continued conversation?"

Write a spec (with AI assistance) when:

  • ✅ Intent needs to persist (decisions, reference, onboarding)
  • ✅ Conversation has clarified what to build (~5+ turns)
  • ✅ Multiple stakeholders need alignment
  • ✅ Complexity warrants structure (would drift in chat)
  • ✅ Compliance or audit trail required

Skip spec, continue conversing when:

  • ❌ Still discovering what to build (keep exploring)
  • ❌ Quick feature with no ambiguity (implement directly)
  • ❌ One-off prototype or experiment
  • ❌ Context already clear in codebase

The checkpoint model: Most specs start as conversation → crystallize into spec when ready → implement from spec. The spec becomes a formalized checkpoint in your work.

Learn more: Writing Specs with AI covers workflows, patterns, and best practices.

AI implements from specs:

  • Clear requirements reduce hallucination
  • Examples show expected patterns
  • Success criteria define "done"
  • Constraints prevent wrong paths

The Bottom Line​

LeanSpec is a mindset, not a format.

It works because it aligns with reality:

  • Context windows are limited (physics)
  • Working memory is small (biology)
  • Time costs money (economics)

Focus on:

  • Why over what
  • Clarity over completeness
  • Action over documentation
  • Evolution over perfection

Success metric: If your specs help people (and AI agents) build better software faster, you're doing LeanSpec right.

Learn More​

Core Concepts (WHY):

Getting Started (HOW):

Reference: