Mapping Bounded Contexts

Mapping Bounded Contexts

Overview

This skill forces the physical and cognitive isolation of different domain areas. It translates extracted domain events into high-cohesion Bounded Contexts, determines their strategic importance, maps their relationships, and establishes a strict Ubiquitous Language to prevent AI hallucination and vocabulary drift.

Foundational Principle: All rules in this skill are mandatory constraints. All deliverables — boundaries, classifications, relationships, dictionaries, AND constraint files — are mandatory outputs, not optional documentation. Skipping any deliverable causes vocabulary drift and context contamination. "Add later" means "never add."

When to Use

• After identifying Domain Events from a PRD, or when setting up a new module.
• When terms are used inconsistently (e.g., User/Account interchangeably) or code leaks across domains.
• When a shared God-object model exists (e.g., a 25-field User struct across multiple domains).

Do NOT use when: boundaries are already defined, or working within a single context (use [coding-isolated-domains](../coding-isolated-domains/SKILL.md)), or domain events have not yet been extracted (REQUIRED PREREQUISITE: [extracting-domain-events](../extracting-domain-events/SKILL.md)).

Quick Reference

| Step | Action | Output | |:---|:---|:---| | 1 | Partitioning & Proposal | Proposed Bounded Contexts | | 2 | Refine Boundaries | Human-approved boundaries | | 3 | Strategic Classification | Core / Supporting / Generic | | 4 | Context Mapping | Relationship pattern diagram | | 5 | Ubiquitous Language Dictionary | Term dictionary + prohibited synonyms | | 6 | Constraint File Generation | Per-context rules files + CLAUDE.md DDD Architecture section | | 7 | Persist to Filesystem | docs/ddd/phase-2-context-map.md |

Ambiguity Handling

Follow the [Ambiguity Handling Protocol](../ddd-protocol/ambiguity-handling-reference.md) throughout this phase.

Phase 2 STOP triggers — confirm immediately:

| Ambiguity | Why STOP | |:----------|:---------| | Which bounded context an event belongs to | Wrong assignment redraws boundaries → Phase 3-7 must redo | | Strategic classification (Core/Supporting/Generic) | Determines analysis depth for Phase 4; wrong = misallocated effort | | Context relationship pattern (ACL vs Conformist vs Open Host) | Wrong pattern = wrong coupling model → Phase 3 contract redesign | | Ubiquitous Language term with unclear business meaning | Vocabulary drift propagates to constraint files and all downstream phases |

Phase 2 ASSUME & RECORD — proceed with explicit assumption:

| Ambiguity | Default assumption | |:----------|:------------------| | Bounded context naming | Choose the primary business capability the context owns | | Prohibited synonym list completeness | Start with obvious synonyms; add more as they surface | | Constraint file format details | Follow existing files in same project; use platform default |

Orchestrator Mode Exception

When invoked by an orchestrator (full-ddd, iterating-ddd, piloting-ddd, restructuring-ddd, importing-technical-solution) in Autonomous Mode, the interactive Q&A steps (1, 2, 3, 4, 5) are replaced by autonomous execution:

• Skip iterative human Q&A (boundary confirmation, strategic classification explanation, context map confirmation, terminology review). Instead, derive the complete context map — including Strategic Classification (Core/Supporting/Generic) — and ubiquitous language glossary in a single pass from the Phase 1 events table.
• Apply STOP/ASSUME protocol: STOP for Phase 2 STOP triggers (above), ASSUME & RECORD for Phase 2 ASSUME items (above).
• Generate constraint artifacts autonomously (Step 6): detect platform, write per-context constraint files (6a) without file-scoping, and append the DDD Architecture section to CLAUDE.md (6b). Record generated file paths for inclusion in the persist step.
• Persist the context map and ubiquitous language glossary immediately (Step 7). Do NOT wait for human approval — the orchestrator manages the approval gate.
• Return the context mapping 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 asks for context mapping), the full interactive Q&A session is mandatory.

Implementation (Interactive Q&A Session)

CRITICAL RULE: Do NOT just generate the context files and stop. You must guide the user through an interactive, step-by-step design process.

1. Partitioning & Proposal: Group the provided Domain Events into high-cohesion clusters (Bounded Contexts). Pause here. Present these proposed boundaries to the user and ask: "Do these boundaries align with the business organization and teams? Should any events be moved?"

Clustering Heuristic: Group events by business capability (not by technical layer or data table). Validation: events within the same cluster share a consistent Ubiquitous Language; events in different clusters use the same term with different meanings (e.g., 'Order' in Sales vs Fulfillment). If two events share the same Actor AND the same aggregate state — they likely belong to the same context.

1. Refine Boundaries: Adjust the boundaries based on user feedback.
2. Strategic Classification: Classify each context as Core / Supporting / Generic and explain rationale to the user.
3. Context Mapping: Propose a Context Map with relationship patterns (ACL, Conformist, Customer-Supplier, Open Host). Ask user to confirm.
4. Ubiquitous Language Dictionary: Generate a terminology dictionary for each context. Clearly define exact terms and list prohibited synonyms. Ask the user: "Are there any company-specific terms we should add or forbid?"
5. Constraint File Generation (Crucial): You MUST generate two types of constraint artifacts:

6a. Per-context constraint files — one per Bounded Context. Detect the user's Agent platform and generate in the appropriate location using the Platform Detection Table in [../ddd-protocol/platform-detection-reference.md](../ddd-protocol/platform-detection-reference.md). That file defines platform detection rules, constraint file paths per platform, fallback behavior, and content requirements (context definition, relationship pattern, UL dictionary, bidirectional dependency prohibitions).

Do NOT use file-scoping (globs/glob patterns) on these files. They must be loaded regardless of which file the agent is editing, because cross-context violations happen in the caller's code, not the callee's.

6b. DDD Architecture section in CLAUDE.md — append a single section to the project's CLAUDE.md (create the file if it doesn't exist). This section provides architecture-level rules visible to both humans and agents:

```markdown ## DDD Architecture (auto-generated by mapping-bounded-contexts)

### Bounded Contexts

• {context} ({classification}): {directory}

...

### Architecture Red Lines

• domain layer MUST NOT import infrastructure or adapter packages
• Cross-context direct imports are PROHIBITED — use port interfaces
• Entity state changes MUST go through domain methods, not public setters
• server/handler layer does protocol conversion ONLY — no business logic

### Before Modifying Domain Code Read the relevant behavior contract: docs/ddd/phase-6/{context}.md Read the context constraint file: .claude/rules/{context}.md (or platform equivalent)

### Mandatory Skill Loading Before modifying ANY file under a bounded context directory, you MUST load and follow the corresponding skill. Modifying domain code WITHOUT loading the required skill first is PROHIBITED.

• Modifying domain layer code → MUST use /coding-isolated-domains
• Writing or updating tests → MUST use /test-driven-development
• Adding cross-context interaction → MUST use /designing-contracts-first
• New feature (full pipeline) → MUST use /iterating-ddd
• Reviewing DDD compliance → MUST use /ddd-review

```

Adapt the Bounded Contexts list from the context mapping produced in Steps 1-5. The Architecture Red Lines are fixed — do not omit or weaken them. The Mandatory Skill Loading section is required when the project has DDD skills installed — do not omit it. Detection: Check if a skills/ directory exists at the project root containing DDD skill files, OR check if CLAUDE.md already references any DDD skills (e.g., coding-isolated-domains, extracting-domain-events). If DDD skills are detected, the Mandatory Skill Loading section MUST be included. If neither condition is met, omit the section.

1. Persist to Filesystem: After user approval, write the COMPLETE context mapping record to docs/ddd/phase-2-context-map.md. This MUST include: event clustering, boundary decisions, strategic classification (Core/Supporting/Generic), context map diagram, ALL Ubiquitous Language dictionaries, and a list of generated constraint files. Use the template from ../full-ddd/templates/phase-2-context-map.md (read the template file; populate fields from session output). Update docs/ddd/ddd-progress.md Phase 2 status to complete. Append key decisions to docs/ddd/decisions-log.md. Write the full record even though constraint files contain partial information — they serve different purposes (AI enforcement vs human traceability). This step is mandatory — do not skip even if the context map is already visible in the conversation.

Example Output

Context: Inventory (Core Domain) Relationship: Upstream to Order (Open Host Service). Downstream to Payment (ACL). Dictionary:

• StockLevel: The available quantity of a product. (Prohibited: Quantity, Amount).
• Reservation: A time-boxed lock on inventory. (Prohibited: Hold, Lock).

(Agent detects Cursor is in use) Generated Constraint File: .cursor/rules/inventory.mdc

---
description: Context mapping rules and ubiquitous language for the Inventory Bounded Context.
---

# Inventory Context (Core Domain)
... (Includes Dictionary, Relationship Pattern, and Bidirectional Import Prohibitions) ...

NEXT STEP: → [designing-contracts-first](../designing-contracts-first/SKILL.md)

Loading Guidance

Do not preload — load on demand:

• Before Step 1: read docs/ddd/phase-1-domain-events.md (events to cluster).
• Step 1-2 (clustering): read [context-mapping-reference.md](./context-mapping-reference.md) § Clustering Heuristic and § Boundary Decision Criteria.
• Step 3-4 (relationships + UL): read [context-mapping-reference.md](./context-mapping-reference.md) § Ubiquitous Language Rules and § Relationship Pattern Selection.
• Step 5 (worked example): read [context-mapping-reference.md](./context-mapping-reference.md) § Worked Example only if first time applying this skill.
• On first STOP/ASSUME decision: read ../ddd-protocol/ambiguity-handling-reference.md.
• Step 6 constraint files: read ../ddd-protocol/platform-detection-reference.md for platform detection and constraint file paths.
• Step 7 persist: read template from ../full-ddd/templates/phase-2-context-map.md.

Self-Check Protocol

Follow the [Persistence Defense Reference](../ddd-protocol/persistence-defense-reference.md) after Step 7, with this context-specific item 4:

1. Phase 2 Artifact Exists: Verify docs/ddd/phase-2-context-map.md exists and contains event clustering, strategic classifications, relationship map, UL dictionaries, and constraint file references.

If the check fails → STOP. Write the missing file. Do NOT proceed to Phase 3.

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

Session Recovery

If a Phase 2 session is interrupted:

1. Check docs/ddd/ddd-progress.md — read Phase 2 status.
2. If docs/ddd/phase-2-context-map.md exists and is complete (contains event clustering, strategic classifications, relationship map, UL dictionaries, and constraint file references): Phase 2 is done. Proceed to Phase 3.
3. If phase-2-context-map.md exists but is partial (missing sections): Read the file to determine which steps completed. Resume from the first incomplete step.
4. If phase-2-context-map.md does not exist: Check for constraint files (.claude/rules/*.md or platform equivalent). If constraint files exist, Step 6 completed but Step 7 did not — write the context map file from constraint file content + conversation context. If no constraint files exist, restart from Step 1.
5. Always re-read docs/ddd/phase-1-domain-events.md before resuming — it is the input artifact and may have been updated.

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

Rationalization Table

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

| Excuse | Reality | |:---|:---| | "Launch deadline overrides context splitting" | Splitting is cheaper now than retrofitting. A 25-field God-object across 40+ files costs 10x more to refactor post-launch. | | "Document ideal boundaries, implement later" | "Later" never comes. Only enforced boundaries (code + constraint files) prevent drift. | | "Shared model is fine — sunk cost too high" | Sunk cost grows daily. Every new import adds another dependency to refactor. The cost curve only goes up. | | "Dictionaries are documentation overhead" | Dictionaries enforce Ubiquitous Language. Without them, User/Customer/Account/Member blur your boundaries. | | "Constraint files are optional / team won't read" | Constraint files are for AI agents to enforce, not humans to read. Skipping = zero runtime enforcement. | | "Split directories but share the model" | Directories without separate models are fake boundaries — just organizational theater. | | "Team voted against splitting" | Team votes cannot override mandatory deliverables. A 4-1 vote does not make a God-object maintainable. | | "This term ambiguity is minor, skip it" | Vocabulary ambiguity grows into Ubiquitous Language violations. Every unclear term must be STOP-confirmed or ASSUME-recorded. | | "I'll decide the classification myself, it's obvious" | Strategic classification is a business judgment, not a technical one. Agent defaults to Core Domain when uncertain — always confirm. | | "Constraint files should include file-scoping globs for precise targeting" | File-scoping creates a false sense of completeness — constraint rules apply to concepts (bounded context boundaries, ubiquitous language), not file paths. When files move, glob-scoped rules silently stop enforcing. Generate without file-scoping globs. | | "Each constraint file only needs to prohibit its OWN imports" | Bidirectional prohibitions mandatory; unidirectional leaves third contexts unprotected against importing through the gap. | | "CLAUDE.md section is nice-to-have — constraint files cover it" | Different audiences, different enforcement scopes; skipping leaves a human-visible gap where AI-visible enforcement exists. | | "Agent can modify domain code without loading the skill — it already knows the rules" | Skills enforce discipline through structured steps (TDD cycles, red line checks, self-check protocols). An agent that "knows the rules" still skips steps when not structurally constrained. Mandatory skill loading prevents ad-hoc shortcuts that erode architecture over time. | | "Mandatory Skill Loading section is too aggre

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lockp111
• Source: lockp111/agent-ddd-engineering
• License: MIT

Install and usage instructions live in the source repository linked above.