Domain-driven and behavior-driven foundations

SpecsGraph does not invent a new method. Its model follows two established ones: Domain-Driven Design (DDD) for the structure and language of a system, and Behavior-Driven Development (BDD) for describing what the system does. You can use SpecsGraph without studying either, but the ideas help you model well and write prompts that agents follow.

Strategic domain-driven design#

Eric Evans introduced Domain-Driven Design in his 2003 book. Its strategic part is about dividing a large system into pieces and agreeing on how to talk about each one. SpecsGraph models that part directly.

Subdomains#

A subdomain is an area of the business. DDD sorts subdomains into three types, which tell you where to spend design effort:

• Core: what sets the business apart and deserves your most careful modeling. In Northwind Commerce, Orders is core.
• Supporting: specific to the business and necessary, but not what customers choose you for. Billing, with its own capture rules, fits here.
• Generic: a solved problem that most businesses share, often bought or taken from a library. Identity and Notifications are generic.

Each context in SpecsGraph records the subdomain type it serves, so reviewers and agents can see where a change deserves the most care.

Bounded contexts#

A bounded context is a boundary inside which one model and one vocabulary apply. "Order" can mean a customer's purchase in Orders and a line in a revenue report in Analytics. Each context keeps its own meaning, and neither leaks into the other. In SpecsGraph contexts are the main nodes of the graph, and each has a short key, such as ORD, that prefixes its requirement IDs.

Ubiquitous language#

Inside a context, the team uses the same words in conversation, in the spec and in the code. If the business says Reservation, the code has a Reservation, not a Hold. SpecsGraph keeps this language in the domain glossary: one definition per term, linked from every place in the model that uses it.

Context maps#

A context map shows how contexts depend on each other. DDD names recurring patterns for these relationships:

• Partnership: two teams plan and ship related changes together.
• Customer/supplier: the upstream team plans its work around what the downstream context needs.
• Conformist: the downstream context adopts the upstream model as it is.
• Anticorruption layer: the downstream context translates the upstream model at its edge so it does not leak in.
• Open host service with a published language: the upstream context offers one documented protocol for all its consumers.
• Shared kernel: two contexts share a small part of the model and change it only together.
• Separate ways: two contexts do not integrate at all.

SpecsGraph stores these as context relationships on the graph, for example Catalog as the upstream supplier to Orders.

Behavior-driven development#

Behavior-Driven Development grew out of test-driven development in the mid-2000s. It describes behavior through concrete examples that the business and the engineers agree on before building, written in a shared format.

Features and scenarios#

A feature is a piece of behavior the system offers. Scenarios illustrate it: short, concrete examples of one situation and its outcome. Gherkin can also group scenarios under a Rule inside a larger feature. In SpecsGraph each requirement is one feature, tagged with its ID, and its acceptance scenarios are the examples. A service groups related requirements, the way a larger feature groups its rules; Requirements and scenarios explains the mapping.

Given, When, Then#

Each scenario has three kinds of step. Given sets up the starting state, When describes the action or event, and Then states the outcome you expect. And and But continue the step before them. Gherkin, the plain-text format read by Cucumber and similar tools, defines these keywords.

@ORD-13
Feature: Release reservations after 15 minutes idle

  Scenario: Reservations lapse after 15 minutes idle
    Given a Customer has started checkout with 2 line items
    And the Customer has been idle for 15 minutes
    When the reservations are released
    Then the stock for both line items is available again
    And the Customer is asked to confirm the cart before paying

  Scenario: A Customer who returns in time keeps the reservations
    Given a Customer has started checkout with 2 line items
    And the Customer has been idle for 14 minutes
    When the Customer continues checkout
    Then the reservations for both line items are kept

Examples with several cases#

When one rule has several input combinations, a scenario outline with an examples table keeps them together instead of repeating the same steps:

Scenario Outline: Capture waits for the reservation
  Given an order whose reservation is <reservation>
  When Billing tries to capture payment
  Then the capture is <result>

  Examples:
    | reservation | result   |
    | confirmed   | accepted |
    | pending     | deferred |
    | released    | refused  |

Why agents do better with explicit boundaries#

A coding agent sees your code and whatever else you put in its context. Without a model, it guesses boundaries from folder names and meaning from whichever words the code happens to use. Explicit contexts, terms and scenarios replace those guesses:

• Boundaries show where a change belongs. Asked to reserve stock at checkout, an agent that knows the Orders context and its link to Billing proposes changes in both, instead of editing whichever file mentions stock.
• A glossary stops synonyms from spreading. Once Reservation is defined, the agent uses that word in requirements and code, instead of hold, lock and allocation in three different files.
• Scenarios give it a target it can test. Given, When, Then steps translate into tests, so the agent can check its implementation against approved behavior.
• Stable IDs make references precise. A commit message or code comment that cites ORD-12 points at exactly one requirement.
• Relationships show what else a change touches. Fulfilment and Analytics sit downstream of Orders, so the agent can list them in its proposal before a reviewer has to ask.

Where each idea lives in SpecsGraph#

Further reading#

• Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software, Addison-Wesley, 2003. The original book; Part IV covers strategic design.
• Gherkin reference↗ (opens in a new tab) from the Cucumber project, with every keyword, including Rule, Background and Scenario Outline.

Next steps#

• Bounded contexts and subdomains: draw the boundaries of your own system.
• Requirements and scenarios: write requirements with acceptance scenarios.
• Domain glossary: build the shared vocabulary.
• Working well with agents: turn the model into better agent output.