Announcing mini-spec: spec-driven development for Claude in ~93 lines

-

mini-spec

Spec-driven development for Claude in ~93 lines

AI hallucinates features you didn't ask for. Sometimes they're great, so good you rely on them. Then you regenerate and they vanish. Mini-spec fixes this.

GitHub: https://github.com/zot/mini-spec

The three-level approach

specs/     What you asked for (human-written)
   ↓
design/    What the AI understood (reviewable)
   ↓
src/       What got built (traceable)

The middle layer is key. It shows how Claude interprets your specs: what you left out, where the ambiguities are, what you over-specified. Design docs are small and readable compared to code, so you can verify correctness before a single line is written.

How it tracks drift

design.md serves as the project's status memory. Each design file lists implementation files with checkboxes. When Claude changes code, it unchecks affected artifacts so it knows:

  1. A design review is needed
  2. Exactly what to look at

There's also a "Gaps" section tracking discrepancies between specs, design, and implementation.

Why mini-spec?

Feature Mini-Spec Heavy Frameworks
Skill file ~93 lines 500+ lines
Agents 1 optional Multiple required
Scripts None Build tooling
Learning curve Minutes Hours

This supersedes my earlier claude-crc methodology. Smaller, cleaner, and what I'm using now.

What's included

  • Skill (~93 lines) for design and implementation workflow
  • Optional agent for running design tasks in isolated context (keeps main conversation lean)
  • Full example app (Contacts manager with specs, design, and implementation)

Mini-spec lets you make designs, implement them with tests and docs, update code, reverse-engineer existing code, and keep everything in sync.

Comments

Post a Comment

Popular posts from this blog

Calculator/spreadsheet tool for Acme

-
I got Plan9 from User Space and started messing with it in the hopes of getting a nice toolbench going with Acme. Since I wrote Ober , I've been interested in this idea. Now, I'll probably rewrite it in Go. I'm wondering if I can just use named pipes to mimic what Acme does with its 9p interface. Anyway, I wrote a simplified version of the Calc tool I wrote for Ober and I put it, here . The calc tool searches an Acme window for variables and their values and some code at the bottom. Then, it executes the code, sending the variables and values to its stdin. The code is expected to output new values for some of the variables. Calc parses the output and replaces the new values into the window. I'm also including two wrappers that make it easy to write calc scripts in rc or Go, so you can say something like this: Bob's age=30, he is yearsleft=0 years away from retirement (calc). #!/usr/bin/env calcgo yearsleft = 55 - age If you middle-click "calc" in t...
Read more

Safe navigaion in Scala, take 2

-
OK, revisiting this topic after a very short time, I have a new implementation, again using that interesting anonymous class technique from James Iry's comment: implicit def richOption[T](x : T) = new { def ??[B](f : T => B):B = if (x != null) f(x) else null.asInstanceOf[B] } I changed the operator from "?!" to "??" because that's a lot easier to type and I chose "??" instead of "?" so people wouldn't confuse it with the questi-colon operator from Java and C. It's stand-alone (doesn't depend on Option or anything) and I had to use a cast to get the types to work out properly, but the test case from my last post does work println(p3??(_.bud)??(_.bud)??(_.bud)??(_.name.drop(1))) prints null and println(p3??(_.bud)??(_.bud)??(_.name.drop(1))) prints ubba. For those new to Scala, the expressions in parentheses are anonymous functions because they use "_" as identifiers. (_.bud) expands to (x => x.bud), where Sca...
Read more

Quick update on The Philosopher's Stone

-
I have changed TPS many times in the past year and a half, but the core idea is still to be a collaborative story telling RPG that feels like a traditional RPG. The latest version of it is called Death of the Vele and the (lame) website is here It has a link to the latest rules. Wow, taking a look at the old rules, I see that I have streamlined the mechanics a LOT since last year. They are simpler, lighter weight, and more intuitive. There are also tools to promote more integrated and structured stories (spotlights, hitting aspects, etc.). Death of the Vele also adds a back story (which you can remove if you don't like, of course). I'm hoping to publish Death of the Vele within the next 12 months. In the mean time, the rules are out there for free, so anyone who wants to can use them. Here is the feature list from the latest copy of the rules: Collaborative, but feels like a traditional RPG Your characters are yours Supports campaign-length stories Game play ...
Read more