Build features by driving design from the outside in. Every feature starts with a failing acceptance test. Design emerges through disciplined Red-Green-Refactor cycles. Infrastructure is deferred until the domain API is proven.
Unlike inside-out TDD with mocks, this approach tests behavior at the boundary — not implementation details — making the suite refactor-friendly by design. See methodology.md.
Outer loop (Acceptance test): Write a failing test scoped at the service/system boundary. This test exercises integration across Bounded Contexts using in-memory adapters. It defines "done."
Inner loop (Red-Green-Refactor): Cycles inside a Bounded Context to make the outer test pass. Drop into this loop only to implement what the acceptance test demands.
Every feature starts from the outside in. The acceptance test drives the process.
Test Priorities
Acceptance and component tests are the primary instruments. Unit tests are the exception.
Component tests — single Bounded Context; drives internal module design via in-memory adapters
Unit tests — exception only: well isolated ,genuinely complex, algorithmic, or combinatorial logic
See testing-strategy.md for full definitions, the testing matrix, and contract test patterns.
The Testing Matrix
Fast
Slow
Large Scope
Acceptance & Component — daily driver
E2E — minimize
Small Scope
Unit — use sparingly
Contract — CI only
Sub-second feedback is non-negotiable. If tests take seconds, the team stops refactoring and the system decays.
Emergent Design Workflow
Follow this sequence strictly within each Bounded Context:
Inline — implement logic naively inside business code; use local variables, lists, maps; no abstractions
In-Memory adapter — once behavior is verified, extract logic into a dedicated in-memory adapter implementation
Interface — extract the adapter interface from what actually emerged (not theoretical guesses)
Checkpoint: all types in the interface must live inside the hexagon
I/O Checkpoint: if no I/O and not out-of-process → keep inside hexagon; do not create a port
Deferred I/O — implement the real adapter (database, network, file system) only after the API is mature
Refactor the inline code inside the hexagon
The sequence is non-negotiable. Each step collects evidence about what the adapter actually needs. See methodology.md for detailed rationale and the walking skeleton.
Hexagonal Architecture
The Domain Layer is the center. All I/O lives behind adapter interfaces at the boundary.
Dependency Rule:Infrastructure(adapters) → Application(ports) → Domain (outer depends on inner, never reverse)
I/O Classification Rule: if it does not do I/O and does not run out-of-process → belongs inside the hexagon; otherwise → adapter.
Port-referenced types must live inside the hexagon. If a port signature references a type in the adapter layer, the hexagon depends outward — a violation.
See folder-structure.md for full folder structure, private/public hexagon split, cross-hexagon dependency rule, adapter design patterns, and test seams.
In-Memory Fakes, Not Mocks
Use in-memory fakes for all adapter boundaries. Never mocks or stubs for domain-level testing.
Fakes are real implementations backed by simple data structures (maps, lists). They have actual behavior. Mocks only verify call sequences — they couple tests to implementation details and break on every refactor.
Contract tests verify the real adapter matches the fake's behavior. See testing-strategy.md.
Walking Skeleton
For new projects or major new components: build a minimal end-to-end implementation first to pay integration cost upfront. Once upright, pivot to the emergent design workflow. See methodology.md.
Composition Root (Configurator)
Wires all adapter interfaces at startup. Used in two contexts:
Production: real adapter implementations (database, network, file system)
Tests: in-memory adapter implementations → fast, deterministic test harness
The same business logic runs in both contexts — only the adapters differ.
