Domain-driven and behavior-driven foundations
How SpecsGraph builds on domain-driven design (subdomains, bounded contexts, aggregates, ubiquitous language) and behavior-driven development.
SpecsGraph does not invent a method. Its kinds follow Domain-Driven Design (DDD) for the structure and language of a system and Behavior-Driven Development (BDD) for what it does. You can use SpecsGraph without studying either, but the ideas help you model well and write prompts agents follow.
Together they make SpecsGraph a tool for spec-driven development: the team agrees on a reviewed specification first, and people and agents build against it.
Strategic domain-driven design
Eric Evans introduced DDD in 2003. Its strategic part divides a system into parts and agrees how to talk about each.
- Subdomains are areas of the business, classified Core (where you compete; model it most carefully), Supporting (specific but not a differentiator) or Generic (solved problems). In SpecsGraph a subdomain carries that classification.
- Bounded contexts are boundaries inside which one model and one vocabulary apply. "Order" can mean a purchase in Orders and a shipment unit in Fulfilment. In SpecsGraph a bounded context implements subdomains and contains its own model, behaviour and terms.
- Context maps say how contexts relate: customer and supplier, conformist, anti-corruption layer, shared kernel and the other patterns. In SpecsGraph a bounded context lists its upstreams with their pattern.
- Ubiquitous language: inside a context the team uses the same words in conversation, the spec and the code. SpecsGraph keeps it in the glossary, per context or project-wide, with the words to avoid.
Tactical domain-driven design
- Aggregates are consistency boundaries, with invariants that hold after every change, the domain events they raise, the entities inside them and their methods.
- Value objects are values without identity; enums name a closed set of cases.
- Integration events and data contracts are what crosses a context's boundary; read models serve queries.
Behavior-driven development
BDD describes behaviour through concrete examples agreed before building. In SpecsGraph a feature has scenarios whose steps use Given (the state), When (the action) and Then (the observable outcome), continued with And and But, as in Gherkin. Use cases complement them from the inside: the command or query, its steps and its outcomes.
Feature: Reserve stock at checkout
Scenario: Checkout stops when a line item cannot be reserved
Given a cart with 2 line items
And the second item is out of stock
When the customer starts checkout
Then checkout stops before payment
And the customer sees which item is unavailableWhy agents do better with explicit boundaries
- Boundaries show where a change belongs. An agent that knows the Orders context and its aggregates stages the change there instead of editing whichever file mentions stock.
- A glossary stops synonyms spreading. Once Reservation is defined, the agent uses that word.
- Scenarios and outcomes give it a target it can test.
- Questions with options let it ask instead of guessing, and the answers become decisions next to the change.
Where each idea lives in SpecsGraph
Further reading
- Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software, Addison-Wesley, 2003.
- Gherkin reference (opens in a new tab) from the Cucumber project.
Next steps
- Subdomains and bounded contexts: draw the boundaries of your own system.
- Features and roles: write features with Given, When, Then scenarios.
- Working well with agents: turn the model into better agent output.