A software engineering methodology for the AI era.
Author: Frank Heikens
Code is disposable. Behavior is permanent.
STDD defines systems using specifications and tests. AI generates the implementation. If the implementation becomes outdated, complex, or broken, it is discarded and regenerated. The specifications and tests remain.
This is the regeneration model: code is deliberately disposable because the specification and test layers are strong enough to verify any new implementation from scratch.
Validated on a real system. STDD has been applied to the Arq project — 521 specification rules with full traceability and explicit coverage across all behavioral requirements, integration contracts, and non-functional constraints.
- Specifications define intent.
- Tests verify behavior.
- Together, specifications and tests define the system.
- Implementations are replaceable artifacts.
Read the full Manifesto.
1. Define the specification
2. Define the expected behavior
3. Write tests that verify the behavior
4. Generate implementation with AI
5. Run the tests
6. Pass → accept. Fail → regenerate.
flowchart TD
A[Specification]
B[Behavior Definition]
C[Test Suite]
D[AI Generated Implementation]
E[Run Tests]
F{Tests Pass?}
G[Accept Implementation]
H[Regenerate Implementation]
A --> B
B --> C
C --> D
D --> E
E --> F
F -- Yes --> G
F -- No --> H
H --> D
Start with the Quick Start to build your first feature. Then go deeper based on your role.
| Document | Description |
|---|---|
| Quick Start | Build your first STDD feature in 90 minutes |
| Document | Description |
|---|---|
| Manifesto | Why STDD exists and what it stands for |
| Document | Description |
|---|---|
| Core Model | Specification taxonomy, test taxonomy, lifecycle, execution flows, traceability rules |
| Method | The STDD workflow — how it works in practice |
| Writing Specifications | How to write precise, testable specifications |
| Architecture | Designing systems for safe regeneration |
| NFR Framework | Non-functional requirements as testable constraints |
| Engineering Playbook | Applying STDD in real projects |
| AI Prompt Engineering | Writing specifications that AI gets right on the first attempt |
| Metrics & Measurement | Defining and measuring quality in STDD |
| System-Level STDD | Applying STDD across service boundaries |
| Adoption Guide | How to adopt STDD in existing teams and projects |
| Versioning the Knowledge Layer | Version control for specifications and tests |
| Features vs Implementations | Language independence in STDD |
| Document | Description |
|---|---|
| Glossary | Quick reference for all STDD terminology |
| Anti-Patterns | Common mistakes and how to avoid them |
| STDD vs Existing Methods | Comparison with TDD, BDD, and other approaches |
| v2 Transition Notes | What changed in v2 and how to interpret older documents |
| Document | Description |
|---|---|
| Worked Example: Core Model | The v2 model applied to a real system — metadata, classification, traceability |
| Seat Reservation API | Full end-to-end walkthrough: specs, tests, implementation, regeneration |
| Order Cancellation | Complete standalone feature: spec, tests, traceability, implementation |
| Short Examples | Single-feature STDD examples |
| Resource | Description |
|---|---|
| Templates | Copy-paste starter files for new STDD features |
| Tools | CSI scripts (fingerprint, traceability) + acceptance-case test generator |
| CI Workflow | GitHub Actions reference workflow for CSI |
This repository contains the STDD methodology documentation and applies STDD to its own tools. The features/ and tests/ directories specify and verify the three Python tools — the CI workflow enforces all three CSI gates on every push.
stdd/
├── README.md
├── manifesto.md
├── .fingerprint ← specification fingerprint
│
├── features/ ← STDD applied to its own tools
│ ├── compute-fingerprint/
│ │ ├── specification.md
│ │ └── acceptance-cases.yaml
│ ├── validate-traceability/
│ │ ├── specification.md
│ │ └── acceptance-cases.yaml
│ ├── yaml-to-pytests/
│ │ ├── specification.md
│ │ └── acceptance-cases.yaml
│ └── traceability-matrix.md
│
├── tests/ ← 52 tests, 100% spec coverage
│ ├── test_compute_fingerprint.py
│ ├── test_validate_traceability.py
│ └── test_yaml_to_pytests.py
│
├── tools/ ← reference CSI scripts
│ ├── compute_fingerprint.py
│ ├── validate_traceability.py
│ └── yaml_to_pytests.py
│
├── docs/
│ ├── quick-start.md ← start here
│ ├── stdd-core-model.md ← v2 structural model
│ ├── worked-example-core-model.md
│ ├── stdd-v2-transition-notes.md
│ ├── method.md
│ ├── writing-specifications.md
│ ├── architecture.md
│ ├── nfr-framework.md
│ ├── engineering-playbook.md
│ ├── prompt-engineering.md
│ ├── metrics.md
│ ├── system-level-stdd.md
│ ├── adoption-guide.md
│ ├── versioning-the-knowledge-layer.md
│ ├── features-vs-implementations.md
│ └── glossary.md
│
├── reference/
│ ├── anti-patterns.md
│ └── vs-existing-methods.md
│
├── examples/
│ ├── seat-reservation.md
│ ├── examples.md
│ └── order-cancellation/ ← complete standalone feature
│ ├── specification.md
│ ├── acceptance-cases.yaml
│ ├── traceability-matrix.md
│ └── implementations/python/
│
├── templates/ ← copy-paste starters
│ ├── specification.md
│ ├── acceptance-cases.yaml
│ ├── traceability-matrix.md
│ └── tfp-prompt.md
│
├── .github/workflows/stdd.yml ← CI workflow (runs on every push)
│
└── diagrams/
├── stdd_development_loop.md
├── stdd_control_loop.md
├── stdd_vs_traditional.md
├── stdd_architecture_layers.md
└── stdd_regeneration_model.md
Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
You are free to share and adapt this work, provided you give appropriate credit to the original author.
Author: Frank Heikens