System Definition

A system is a composition of lawful behaviours where each behaviour is complete, bounded, and owned. That's the core principle behind Specify - and the system definition is the artefact that captures it.

More than documentation

A system definition built in Specify isn't a document sitting alongside the project. It IS the project's source of truth. It serves three distinct purposes that traditional documentation approaches keep separate.

A record of intent. The system definition captures not just what the system does, but what it was designed to do. When a test fails six months from now, you can trace back to the original specification and determine whether the system is behaving incorrectly or the test is wrong. Intent survives personnel changes, shifting priorities, and fading memories.

A contractual basis. The system definition becomes the benchmark against which validation and acceptance of deliveries can be measured. When an outsourced component is delivered, you compare it to the specification. When acceptance testing runs, the results map to requirements. There's no ambiguity about what "done" means because the definition is explicit.

A knowledge base. Your system definition is the intellectual property associated with your product. New team members onboard by reading the feature hierarchy rather than reverse-engineering code. When someone leaves, the knowledge doesn't leave with them. When you build product variants, the feature sets define what's included or excluded.

Feature sets as components

Feature sets aren't just organisational labels - they're the logical components of your system. Each feature set represents a coherent piece of capability that can be reasoned about independently.

This has practical implications. A feature set can be:

• Worked on independently - one team takes Clock Domains, another takes User Features
• Outsourced as a unit - contract out the Comms Protocol feature set with its complete specification
• Included or excluded from product variants - the base product has 15 feature sets, the premium version has 19
• Tested as a component - every feature in the set has requirements that define its acceptance criteria

In the Reference Project, you can see this at work. The Oven Project's 20 feature sets each represent a distinct system concern - from Clock Domains and Memory Management at the infrastructure level to User Features and Oven Control at the product level.

Why this matters

Traditional approaches produce systems where individual requirements are "correct" but behaviour is wrong. Requirements get ticked off as "done" while the system still misbehaves, because the requirements were captured as a flat list disconnected from the features they belong to.

When requirements define behaviours - when they live inside features, attached to use cases, governing specific scenarios - the definition stays connected to reality. Architecture emerges from feature boundaries rather than being guessed upfront. Debugging is tracing back through a feature's specification rather than archaeological excavation through code.

The system definition doesn't just help you build faster. It helps you define correctly.

Related

• Features & Feature Sets - what features are and how sets organise them
• Requirements Hierarchy - how requirements attach to features
• From Definition to Code - the path from specification to implementation