Domain Modeling
Proactively build and refine the project's domain model during the design process. This is an
active discipline: challenge terminology, invent edge-case scenarios, and document them in the glossary and decisions as concepts take shape. (Simply reading
to obtain vocabulary is not this skill; that's just a basic practice any skill can perform. This skill is for modifying the model, not consuming it.)
File structure
Most repos have only one context:
text
/
|- CONTEXT.md
|- docs/
| `- adr/
| |- 0001-event-sourced-orders.md
| `- 0002-postgres-for-write-model.md
`- src/
If there is a
in the root, it means the repo has multiple contexts. The map points to the location of each context:
text
/
|- CONTEXT-MAP.md
|- docs/
| `- adr/ -> system-wide decisions
`- src/
|- ordering/
| |- CONTEXT.md
| `- docs/adr/ -> context-specific decisions
`- billing/
|- CONTEXT.md
`- docs/adr/
Create files lazily as needed: only create a file when there is content to write. If there is no
, create it when the first term is resolved. If there is no
, create it when the first ADR needs to be documented.
During the session
Challenge against the glossary
Immediately point out when the terminology used by the user conflicts with the existing language in
. For example: "Your glossary defines 'cancellation' as X, but you seem to mean Y - which is it?"
Sharpen fuzzy language
When the user uses vague or overloaded terminology, propose a precise canonical term. For example: "You're saying 'account' - do you mean the Customer or the User? Those are different things."
Discuss concrete scenarios
When discussing domain relationships, use concrete scenarios to conduct stress tests. Invent scenarios that probe edge cases to force the user to precisely define the boundaries between concepts.
Cross-reference with code
When the user describes how something works, check if the code aligns with the description. If a contradiction is found, point it out: "Your code cancels entire Orders, but you just said partial cancellation is possible - which is right?"
Update CONTEXT.md inline
Immediately update
when a term is resolved. Don't batch updates until the end; capture concepts as they emerge. Follow the format in
CONTEXT-FORMAT.md.
must contain no implementation details at all. Do not use
as a spec, scratch pad, or repository for implementation decisions. It is only a glossary.
Offer ADRs sparingly
Propose creating an ADR only when all three of the following conditions are met:
- Hard to reverse - The cost of changing your mind later is significant
- Surprising without context - Future readers will wonder "why did they do it this way?"
- The result of a real trade-off - There are actual alternatives, and you chose one based on specific reasons
Skip creating an ADR if any of the conditions are not met. Follow the format in ADR-FORMAT.md.