Actively build and sharpen the project's domain model during design. This is the active discipline: challenge terminology, invent edge-case scenarios, and write into the glossary and decisions at the moment concepts take shape.
File structure
Most repos have only one context:
/
|- GLOSSARY.md
|- docs/
| `- adr/
| |- 0001-event-sourced-orders.md
| `- 0002-postgres-for-write-model.md
`- src/
If the root has GLOSSARY-MAP.md, the repo has multiple contexts. The map points to the location of each context:
/
|- GLOSSARY-MAP.md
|- docs/
| `- adr/ -> system-wide decisions
`- src/
|- ordering/
| |- GLOSSARY.md
| `- docs/adr/ -> context-specific decisions
`- billing/
|- GLOSSARY.md
`- docs/adr/
Create files lazily on demand: only create them when there is content to write. If there is no GLOSSARY.md, create it when the first term is resolved. If there is no docs/adr/, create it when the first ADR needs to appear.
During a session
Challenge against the glossary
When the terminology the user uses conflicts with existing language in GLOSSARY.md , point it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y - which is it?"
Sharpen vague wording
When the user uses vague or overloaded terminology, propose a precise canonical term. "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 stress-test. Invent scenarios that probe edge cases and force the user to precisely define the boundaries between concepts.
Cross-check against the code
When the user describes how something works, check whether the code agrees. If you find a contradiction, point it out: "Your code cancels entire Orders, but you just said partial cancellation is possible - which is right?"
Update GLOSSARY.md in place
When a term is resolved, update GLOSSARY.mdimmediately. Don't batch it up until the end; capture it as concepts emerge. Use the format in GLOSSARY-FORMAT.md .
GLOSSARY.md must contain no implementation details at all. Don't treat GLOSSARY.md as a spec, scratch pad, or repository for implementation decisions. It is just a glossary.
Propose ADRs cautiously
Only propose creating an ADR when all three of the following hold:
- Hard to reverse - The cost of changing your mind later is meaningful
- Surprising without context - A future reader would wonder "why did they do it this way?"
- The result of a real trade-off - Alternatives genuinely exist, and you chose one of them for concrete reasons
If any one is missing, skip the ADR. Use the format in ADR-FORMAT.md .