Actively build and refine the project's domain model during design. This is anactivediscipline—question terminology, create boundary scenarios, and record terms and decisions at the moment they take shape. (Merelyreading GLOSSARY.md to acquire vocabulary is not the purpose of this skill—that is a one-line habit any skill can do. This skill is for when youmodifythe model, not merely consume it.)
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 GLOSSARY-MAP.mdexists at the root, the repo has multiple contexts. The map points to the location of each context:
/
├── GLOSSARY-MAP.md
├── docs/
│ └── adr/ ← 系统级决策
├── src/
│ ├── ordering/
│ │ ├── GLOSSARY.md
│ │ └── docs/adr/ ← context 特定决策
│ └── billing/
│ ├── GLOSSARY.md
│ └── docs/adr/
Create files lazily—only create them when there is content to write. If GLOSSARY.md does not exist, create it when the first term is settled. If docs/adr/ does not exist, create it when the first ADR is needed.
During the Session
Challenge Against the Glossary
When the user uses terminology that 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?"
Refine Vague Language
When the user uses vague or overloaded terminology, propose precise canonical terms. "You say 'account'—do you mean Customer or User? They are different things."
Discuss Concrete Scenarios
When domain relationships are discussed, stress-test them with concrete scenarios. Create scenarios that probe boundary cases and force the user to describe precisely the boundaries between concepts.
Cross-Reference with Code
When the user states how something works, check whether the code is consistent. If you find a contradiction, point it out: "Your code cancels entire Orders, but you just said partial cancellation is possible—which is correct?"
Update GLOSSARY.md Inline
When a term is settled, update GLOSSARY.mdimmediately. Do not batch—capture it as it happens. Use the format in GLOSSARY-FORMAT.md .
GLOSSARY.md should contain no implementation details at all. Do not treat GLOSSARY.md as a spec, a scratchpad, or a repository for implementation decisions. It is a glossary, nothing more.
Offer ADRs Sparingly
Offer to create an ADR only when all three of the following conditions are met:
- Hard to reverse—the cost of changing your mind later is high
- Confusing out of context—future readers will wonder "why did they do it this way?"
- The result of a real trade-off—there were genuine alternatives, and you chose one of them for a specific reason
If any one is missing, skip the ADR. Use the format in ADR-FORMAT.md .