Spec-Driven Code Evolution

CodeSpeak is built on a simple premise: a lot of code contains details that go without saying for humans. Before LLMs, machines couldn't figure these out, so we had to spell them out. Now we don't have to.

Specs replace code

In CodeSpeak, you write specs — plain English descriptions of what your software should do. CodeSpeak generates the implementation. You maintain the spec, not the code.

This is similar to how C raised the level of abstraction above Assembly, and Java above C. CodeSpeak raises it further: you describe what you want, and the toolchain figures out how.

Specs are more concise than code

Specs capture essential complexity — the parts of your application that a machine can't figure out on its own. Everything else is boilerplate that CodeSpeak handles.

In practice, specs are typically 5-10x shorter than the code they generate. A spec change of +23 lines can generate +221 lines of code. This isn't just about typing less — it's about reasoning at a higher level.

How specs evolve

Specs evolve the same way code does, but at a higher level of abstraction:

1. Add a feature — add lines to the spec, rebuild. CodeSpeak turns the diff in the spec into a diff in the code.

2. Remove a feature — delete lines from the spec, rebuild. The generated code shrinks accordingly.

3. Fix a spec bug — if the behavior is wrong because the spec is wrong, edit the spec and rebuild.

4. Fix an implementation bug — if the spec is right but the code has a bug, use codespeak change to fix the code without changing the spec.

5. Split a growing spec — as a spec gets large, use imports to break it into focused modules. Each module has its own spec and its own managed files.

From code to specs

Existing code can be migrated to specs using codespeak takeover. It reads your source files and generates a spec that captures their behavior. From that point on, you edit the spec instead of the code.

See the Takeover tutorial for a step-by-step walkthrough.

Modularity for humans

CodeSpeak specs are designed for human teams working on large applications over time:

• Conceptually self-contained modules — each spec describes one concern
• Clear dependencies — the import directive makes relationships explicit
• Scoped changes — modifying one spec doesn't affect unrelated parts of the codebase
• Version control — specs are plain text files that work with git, code review, and all existing workflows