# specdown

> Markdown + specifications. A way to write executable software specifications by putting acceptance tests inside Markdown documents. A product of Agentic engineering experiment 4.

[Markdown](https://wiki.g15e.com/en/pages/Markdown.txt) + specifications. A way to write executable software specifications by putting <acceptance tests> inside Markdown documents. A product of [Agentic engineering experiment 4](https://wiki.g15e.com/en/pages/Agentic%20engineering%20experiment%204.txt).

- https://corca-ai.github.io/specdown (homepage and specification)
- https://github.com/corca-ai/specdown (source code)

## Further explanation

Drawbacks of natural-language documents:

- Discrepancies between natural-language documents and code are hard to detect. In my case, coding agents began making mistakes when the code reached roughly 40,000 lines (excluding comments and blank lines). (As of March 2025.)
- It is difficult to express precisely what you have in mind in natural language. Even when you do, the implications often differ from what you expected. (See [Specification written in natural language](https://wiki.g15e.com/en/pages/Specification%20written%20in%20natural%20language.txt).)

Drawbacks of traditional tests (E2E, unit tests):

- Testing every possible case is practically impossible.
- Finding the necessary test cases is not easy.

Drawbacks of formal model checking:

- Models are difficult to read and write.

Combining the three makes a powerful whole ([Beneficially relating elements](https://wiki.g15e.com/en/pages/Beneficially%20relating%20elements.txt)).

Natural language is easy to read, Alloy models check every possible combination within a bounded scope, and traditional tests connect the specification to the code deterministically. Alloy model instances (run) and counterexamples (check) suggest good test cases. They also reduce unnecessary code by mechanically discovering properties that inevitably follow from a given design. Weaving natural-language specifications, models, and traditional tests into a single file can greatly reduce discrepancies among models, documents, and code, thereby reducing mistakes by coding agents and humans alike.

## Example of the rendered result

The following is part of a specification for what happens when Enter is pressed in an editor.

![specdown.png](https://wiki.g15e.com/data/specdown.webp)

## See also

- [Framework for integrated test](https://wiki.g15e.com/en/pages/Framework%20for%20integrated%20test.txt)
- <Literate programming>
- [Alloy Analyzer](https://wiki.g15e.com/en/pages/Alloy%20Analyzer.txt)