coding-isolated-domains

Overview

This is the ultimate architectural defense skill. It explicitly forbids the generation of "Anemic Domain Models" (data bags with only getters/setters) and enforces Hexagonal Architecture. The Domain Core MUST be completely isolated from infrastructure, containing pure business logic (Rich Models) protected by strict unit tests.

Foundational Principle: All rules are mandatory constraints, not aspirational guidelines. No "temporarily" or "just for now."

When to Use

• When writing implementation of business rules, Entities, or Aggregates; when you detect an Entity with only properties and no behavior; when ORM tags or HTTP logic leak into the domain layer.

Do NOT use when: Working on Generic Subdomains with simple CRUD; writing adapter code without completing domain TDD first; dealing with legacy non-DDD code interfaces (use mapping-legacy-landscape to understand the legacy structure first); or when context boundaries and contracts are not yet defined (REQUIRED PREREQUISITES: defining-schemas and spec-driven-development — Phase 5 schema files and Phase 6 behavior contracts must exist before domain code is written). Exception: when invoked by full-ddd in simplified mode (workflow_mode: simplified in ddd-progress.md), Phase 5 and Phase 6 artifacts do not exist — proceed using the Minimal Technical Checklist from decisions-log.md. The checklist MUST contain: (1) persistence type (SQL/NoSQL/file), (2) interface type (REST/gRPC/CLI), (3) error handling strategy (error codes/exceptions/result types). If any item is missing from decisions-log.md → STOP and ask the user.

Quick Reference

| Step | Action | Output | |:---|:---|:---| | 1 | Load Blueprint from Phase 6 | Directory structure + file skeletons created per Blueprint | | 2 | Zero Infrastructure Dependencies | No ORM/HTTP in domain structs confirmed | | 3 | Mandatory Rich Domain Models | Behavior methods defined, no public setters | | 4 | Eric Evans 4 Aggregate Rules | Consistency boundaries validated | | 5 | Domain TDD (MAP→ITERATE→DIFF) — delegates to test-driven-development | test-map.md + test-coverage.md + test files + domain code | | 6 | App TDD + Adapter Implementation | App use case TDD (category 8) + Converter + Repo + Server + integration tests | | 7 | Persist Design Decisions | docs/ddd/decisions-log.md updated, ddd-progress.md Phase 7 = complete |

Architecture red lines for the GREEN step: see domain-architecture-reference.md

Ambiguity Handling

Follow the Ambiguity Handling Protocol throughout this phase.

Phase 7 STOP triggers — confirm immediately:

| Ambiguity | Why STOP | |:----------|:---------| | Aggregate root boundary (what belongs inside vs outside the aggregate) | Wrong boundary = wrong consistency scope → aggregate design must redo | | Business invariant interpretation | Wrong invariant = wrong behavior methods → implementation must redo | | Entity vs Value Object classification | Wrong classification = wrong identity semantics → aggregate design must redo |

Phase 7 ASSUME & RECORD — proceed with explicit assumption:

| Ambiguity | Default assumption | |:----------|:------------------| | Internal helper method structure | Extract to private method when logic exceeds 3 lines | | Test data specific values | Use realistic but minimal values (e.g. price=100, quantity=1) | | Value Object internal representation | Use the simplest representation that satisfies the invariant |

Orchestrator Mode Exception

When dispatched as a subagent by an orchestrator (full-ddd, iterating-ddd, piloting-ddd, restructuring-ddd, importing-technical-solution), the interactive Q&A steps are replaced by autonomous execution:

• Skip all interactive "Ask:" prompts (Steps 1, 5, 6 approval gate). Instead, execute each step autonomously using the Phase 6 behavior contract as the sole source of truth.
• Apply STOP/ASSUME protocol: STOP for Phase 7 STOP triggers (above), ASSUME & RECORD for Phase 7 ASSUME items (above).
• Domain TDD: Runs autonomously per the test-driven-development Orchestrator Mode Exception.
• Adapter approval gate (Step 6 prerequisite check 3): In orchestrated mode, the orchestrator manages the per-BC human checkpoint. Do NOT block waiting for a human "yes" inside the subagent — the orchestrator presents the checkpoint.
• Persist decisions-log.md and ddd-progress.md updates immediately (Step 7). Do NOT wait for human approval — the orchestrator manages the approval gate.
• Return the Step 7 completion status (test-map summary, test-coverage summary) to the orchestrator. If STOP was triggered, return the STOP reason instead.

This exception applies ONLY when dispatched as a subagent by an orchestrator. When invoked standalone (user directly runs domain coding), the full interactive session is mandatory.

Context-per-Session Execution Model

Phase 7 processes one bounded context per subagent (sequential, not parallel). This prevents context window pollution from accumulating code and tests across multiple contexts.

Orchestrator dispatches per context (Core Domain first, then Supporting, then Generic):

1. Read docs/ddd/phase-6-behavior-contracts.md (index) to get the context list.

2. For each context, dispatch a subagent with precisely scoped inputs:

   • docs/ddd/phase-6-behavior-contracts.md (index — scope awareness)
   • docs/ddd/phase-6/{this-context}.md (behavior contract for this context only)
   • Relevant schema files (located via docs/ddd/schema-manifest.md)
   • This skill (coding-isolated-domains) + test-driven-development skill instructions

   On-demand reads (not preloaded — subagent reads during execution to avoid context window bloat):

   • docs/ddd/phase-4-technical-solution.md — Step 1 (persistence strategy, architectural style)
   • docs/ddd/phase-3-contracts.md — Step 6 adapter implementation (port interfaces the adapters must implement)
   • docs/ddd/phase-1-domain-events.md + docs/ddd/phase-2-context-map.md — TDD MAP step (enrich test derivation)
   • skills/ddd-protocol/domain-architecture-reference.md — TDD GREEN step (red line checklist)
   • Language convention skill (skills/language-conventions/) — Step 6 adapter implementation (naming, structure)

3. Subagent executes Steps 1-7 for its context, commits, returns.

4. Orchestrator checks docs/ddd/test-map.md for completion status, dispatches next context.

Why sequential: Multiple subagents writing code simultaneously causes git conflicts, shared artifact races (test-map.md, ddd-progress.md), and build/test interference. One context at a time is safe.

Recovery: If a subagent crashes mid-context, the orchestrator re-dispatches — test-map.md records per-aggregate progress, so the new subagent resumes from the last completed aggregate.

Phase 7 Execution Order (per bounded context)

| Stage | Scope | Steps | Gate (must pass before next stage) | |:------|:------|:------|:------------------------------------| | 1. Structure | Directory scaffolding | Steps 1-4 | Files exist on disk | | 2. Domain TDD | All aggregates in context | Step 5 | test-coverage.md exists + all aggregates pass in test-map.md + explicit user approval | | 3. App TDD + Adapter (per aggregate) | App use case TDD (category 8) → Converter → Repo | Step 6.1-6.3 | App use case + adapter code exists per aggregate | | 4. Server handlers | All handlers for this context (batch) | Step 6.4 | All aggregates have completed Stage 3 | | 5. Wiring | DI assembly (cmd/main.go) | Step 6.5 | Compiles | | 6. Integration test | End-to-end verification | Step 6.6 | Tests pass. If fail → fix, do not proceed to Stage 7 | | 7. Completion | Persist decisions, update progress | Step 7 | User approval received + artifacts on disk |

Stage vs Step: Stages are execution phases with gates between them. Steps are the numbered instruction sections below. Step 6 spans Stages 3-6 (it contains sub-steps 6.1-6.6). Do NOT execute Step 6 as a monolithic pass — pause at each Stage gate to verify the gate condition before continuing to the next sub-step range.

Domain first, adapters second. Stage 2 completes ALL domain aggregates before ANY adapter code is written. Do not write Aggregate A's adapter while Aggregate B's domain TDD is pending — "parallelizing" domain and adapter work is a rationalization, not an optimization.

App use cases ARE TDD-driven (category 8). Use case orchestration has real wiring logic (load→command→save→publish) that domain tests cannot cover. Category 8 tests drive app code into existence at the start of Stage 3 via RED→GREEN→REFACTOR, mocking repo ports and event publisher ports while using real domain objects. See test-driven-development § Use Case Orchestration TDD. Remaining adapters (converter, repo, server handler) are NOT TDD-driven — they are mechanical mapping with quality enforced via integration tests + ddd-review.

Implementation: The Iron Laws of the Domain Core

CRITICAL RULE (standalone mode): Do NOT just generate the final code and stop. You must guide the user through an interactive, step-by-step domain implementation process. When dispatched by an orchestrator, see § Orchestrator Mode Exception — interactive prompts are skipped.

Step 1: Load Blueprint from Phase 6

1. Read docs/ddd/phase-6-behavior-contracts.md (index) — the Context Summary table lists all available contexts and their file paths. Identify the context to implement. 1b. Read docs/ddd/phase-6/{context}.md — the behavior contract for this bounded context.
2. Create directory structure per the Directory Layout section of the Blueprint.
3. Create file skeletons per the Schema → Domain Mapping table (file names + type signatures, no implementation).
4. Do NOT create domain files not in the Blueprint — if a new file is needed, STOP, return to Phase 6 to add it.
5. Reference the Technical Solution artifact (docs/ddd/phase-4-technical-solution.md) for persistence strategy and architectural style.

Architecture Red Lines

The complete checklist of architecture and domain modeling constraints is in domain-architecture-reference.md. Check every RED line from that reference during implementation — especially in the GREEN step of each TDD cycle. If a violation is detected, stop immediately, delete the violating code, and rewrite.

Architecture Constraints (hexagonal boundary — 7 red lines): domain layer has no infrastructure dependencies · no ORM/JSON tags on domain structs · no cross-aggregate direct imports · business logic in entities not services · ports are interfaces not implementations · no magic literals for business enums (use named constants from contract enums or domain consts) · adapter handlers do protocol conversion only (one handler → one app method call; no switch/if on business conditions in adapter)

Domain Modeling Constraints (DDD discipline — 4 red lines): value objects are immutable · no public setters on entities · domain events named in past tense · aggregates reference other aggregates by ID only

Step 2: Zero Infrastructure Dependencies

• NO ORM/HTTP/framework dependencies in domain structs. See Architecture Constraints in domain-architecture-reference.md.

Step 3: Mandatory Rich Domain Models

• Entities MUST have behavior methods. No public setters — expose shipOrder() not setStatus(). See Domain Modeling Constraints in domain-architecture-reference.md.

Step 4: Eric Evans 4 Aggregate Rules

• Consistency boundary: Model true invariants together — only place in one aggregate the data that must be consistent in a single transaction.
• Small aggregates: Keep aggregates small. Large aggregates cause lock contention and slow loads. When in doubt, make it smaller.
• Reference by ID: Reference other aggregates by identity only (a stored ID), never by direct object reference. This enforces loose coupling and allows separate persistence.
• Invariants in root: Only the Aggregate Root may enforce consistency rules across the entire aggregate. External code calls methods on the root; it never mutates child entities directly.

Step 5: Domain TDD

• Mandatory TDD: Execute test-driven-development — run the MAP→ITERATE→DIFF cycle driven by the Phase 6 behavior contract for this Bounded Context.
• In the GREEN step of each TDD cycle, verify every Architecture Red Line from domain-architecture-reference.md. If a violation is detected, stop immediately, delete the violating code, and rewrite.
• Ask: "Do these tests cover all expected behaviors and edge cases? Shall I proceed to implement the logic to make these tests pass?"
• Note: The TDD skill drives a per-test RED→GREEN→REFACTOR cycle. Do NOT batch-write all tests before implementing — follow the TDD skill's own pacing.

Step 6: Adapter Implementation (post Domain TDD)

Hard prerequisite — verify ALL before writing any adapter code:

1. docs/ddd/test-coverage.md exists (DIFF completed)
2. Read docs/ddd/test-map.md — enumerate every aggregate for this context, confirm ALL show status pass
3. User has explicitly approved — ask: "Domain TDD for this context is complete. All aggregates pass. Shall I proceed to adapter implementation?" Do not interpret silence, brief acknowledgment, or topic change as approval. Wait for an explicit yes.

If any check fails → STOP. Finish Domain TDD (Step 5) first. Do NOT write adapter code for Aggregate A while Aggregate B's domain TDD is pending.

Per-aggregate cycle (app use case TDD → converter → repo → server → wiring → integration test): app use case is driven by category 8 TDD (RED→GREEN→REFACTOR, mocking ports, using real domain objects) — see test-driven-development § Use Case Orchestration TDD. Then see adapter-implementation-reference.md for remaining adapter sub-steps. Key rules: one handler → one app method, no business logic in adapters, integration tests use real DB + mock external services, each test cleans own data only.

Step 7: Persist Design Decisions

Persist to Filesystem: After user approval of domain + adapter implementation, append architectural design decisions to docs/ddd/decisions-log.md. Record: the proposed Aggregate Root structure, user feedback, and any invariants added or modified. (TDD-specific decisions — test coverage summary, traceability gaps — are already recorded by TDD DIFF; do NOT duplicate them here.) Update docs/ddd/ddd-progress.md Phase 7 status to complete.

Verify CLAUDE.md DDD Architecture section: If CLAUDE.md does not exist, create it with the DDD Architecture section (using the template from mapping-bounded-contexts Step 6b). If CLAUDE.md exists but does not contain a ## DDD Architecture section (e.g., pipeline started before this feature existed, or the file was reset), append the section. Generate it using the context list from docs/ddd/phase-2-context-map.md and the Architecture Red Lines template from mapping-bounded-contexts Step 6b. Also verify the ### Mandatory Skill Loading subsection exists — if missing (e.g., generated before the mandatory enforcement update), add it per the template. This section is REQUIRED when DDD skills are installed.

This step is mandatory — do not skip even if decisions were discussed in the conversation.

PIPELINE COMPLETE. When used standalone, repeat from Step 1 for remaining contexts (Core Domain first, then Supporting, then Generic). When invoked via an orchestrator (full-ddd, iterating-ddd, piloting-ddd, restructuring-ddd, importing-technical-solution), the orchestrator drives the per-context loop — see § Context-per-Session Execution Model. For a new project or module, return to full-ddd. For iterating on this project after archival, use iterating-ddd.

Archive this iteration (when all contexts are complete):

sh skills/full-ddd/scripts/archive-artifacts.sh

This moves all phase artifacts into docs/ddd/archive/v{N}/. The archive is a human-readable record — it is NOT loaded by the agent on the next session.

NEXT STEP: → Archive (sh skills/full-ddd/scripts/archive-artifacts.sh) then → full-ddd (new project) or → iterating-ddd (next iteration)

语言约定: 本技能的目录结构和命名建议是语言无关的。语言专属的项目结构、包命名、测试文件放置等惯用约定请参阅 language-conventions。

Loading Guidance

This skill references supporting files on demand — do not preload them all:

• Before Step 1: read docs/ddd/phase-6-behavior-contracts.md (index — discover available contexts), then read docs/ddd/phase-6/{context}.md (behavior contract for this context).
• During Step 1: read docs/ddd/phase-4-technical-solution.md (persistence strategy, architectural style). Language conventions (Go): read ../language-conventions/go-conventions.md (for directory layout during scaffold).
• During Step 5 (TDD MAP): read docs/ddd/phase-1-domain-events.md + docs/ddd/phase-2-context-map.md (enrich test derivation with event names and ubiquitous language). Read test-driven-development for the full MAP→ITERATE→DIFF cycle.
• During Step 5 GREEN: reference domain-architecture-reference for the full red line checklist.
• During Step 6 (Adapters): read docs/ddd/phase-3-contracts.md (port interfaces the adapters must implement). Language conventions (Go): read ../language-conventions/go-conventions.md + ../language-conventions/go-wire-di-reference.md (DI conventions) + ../language-conventions/go-proto-integration-reference.md (if gRPC — proto isolation, pb access rules).
• Schema files: locate via docs/ddd/schema-manifest.md — read the relevant schema files for this context's aggregates.

Example: Anemic vs Rich Model

// ❌ Anemic — GORM tags leak into domain; public setter destroys invariants
type Order struct {
	ID     string      `gorm:"column:id;primaryKey"`
	Status OrderStatus `gorm:"column:status"`
}
func (o *Order) SetStatus(s OrderStatus) { o.Status = s }

// ✅ Rich — No tags, private fields, behavior enforces invariants
type Order struct {
	id     string
	status OrderStatus
}
func (o *Order) Pay() error {
	if o.status != StatusPending { return errors.New("only pending orders can be paid") }
	o.status = StatusPaid
	return nil
}

Session Recovery

If a Phase 7 coding session is interrupted mid-context:

1. Check if docs/ddd/test-map.md exists — it records per-aggregate progress (pass/pending status), written by test-driven-development.
2. If it exists: Read it to determine which aggregates completed. Resume from the first incomplete aggregate. Do NOT re-implement completed aggregates — the test files and domain code are authoritative.
3. If it does not exist: Check if any domain code files exist in the context directory. If they do, the session was interrupted before MAP completed — restart from Step 1 (Load Blueprint) for this context.

Run sh skills/full-ddd/scripts/session-recovery.sh for a quick status report.

Self-Check Protocol

Follow the Persistence Defense Reference after Step 7, with these context-specific items:

4. Domain Code + Tests Exist: Verify the aggregate root file, domain entity files, and corresponding test files exist in the context directory.
5. Adapter Code Exists: Verify converter files, repository implementation files, application use case files, and server handler files exist for each aggregate. Verify integration test file exists. If the project uses a DI framework, verify DI wiring files are up to date per language-conventions § DI & Startup. If any check fails → STOP. Write the missing files before claiming PIPELINE COMPLETE.

Post-implementation verification is handled by ddd-review — a separate skill that runs with fresh context after this skill returns. The orchestrator dispatches ddd-review automatically. Do NOT self-verify — the review skill's fresh attention is more reliable than self-checking with degraded attention.

Note: This skill has no platform hooks. When invoked by an orchestrator (full-ddd, iterating-ddd, piloting-ddd, restructuring-ddd, importing-technical-solution), the orchestrator's hooks provide Layer 1 defense. When invoked standalone, this Self-Check Protocol (Layer 2) is the primary defense.

Rationalization Table

If you catch yourself thinking any excuse in the left column — STOP and re-read the Reality column.

| Excuse | Reality | |:---|:---| | "Adapter field mapping is trivial — I'll eyeball it without a verification table" | Adapter converters are the #1 source of silently dropped fields. After writing each converter/repo/handler, produce a Field Mapping Verification table (source field → target field). Every field must appear. No table = not verified. | | "I'll write the repo implementation from memory of the entity struct" | Entity structs evolve during TDD. Read the CURRENT entity file before writing the repo — stale mental models silently drop new fields or use old types. | | "The app layer needs a switch/if to route to different domain methods" | Business-condition dispatch belongs in the domain aggregate, not the app layer. App orchestrates: validate → call ONE domain method → persist. If routing is needed, the domain exposes the routing decision. | | "I'll add this helper to the domain package — it's used by domain code" | Helpers that don't represent business concepts don't belong in domain. Structural mapping, string formatting, time utilities → separate package. Domain contains only business concepts. | | "I can start the adapter before all aggregate TDD is complete — the ports are stable enough" | Ports are NOT stable until all aggregate TDD passes (Stage 2 → Stage 3 gate). A late TDD cycle on Aggregate B can change a shared port interface, breaking Aggregate A's adapter. Wait for the gate. | | "App use case is just wiring — skip TDD and write it directly" | Use case orchestration has real failure modes: forgotten save, missing event publish, swallowed domain errors. Category 8 TDD catches these before adapter code is written. "Just wiring" is not "trivially correct." | | "Integration test setup is too complex — unit tests are sufficient" | Integration tests verify the adapter layer against real infrastructure. Unit tests verify d

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->