Domain Modeling
Use Traditional Chinese throughout the conversation. Write GLOSSARY.md and ADR documents in Traditional Chinese; terms themselves can appear in both Chinese and English (e.g., 「替代料（Alternate Part）」), because naming in code is usually in English.
During the design process, actively establish and sharpen the project's domain model. This is an active discipline: challenge words, invent edge cases, and write things down as soon as terms and decisions take shape. (Simply reading GLOSSARY.md to align vocabulary is not this skill — that is a small habit any skill should have. This skill is used when you are changing the model, not just using it.)
File Structure
Most repos have a single context:
/
├── GLOSSARY.md
├── docs/
│ └── adr/
│ ├── 0001-cost-rollup-uses-moq-price-break.md
│ └── 0002-sqlite-for-part-cache.md
└── src/
If the repo root contains GLOSSARY-MAP.md, it means the repo has multiple contexts, and this map indicates the location of each context:
/
├── GLOSSARY-MAP.md
├── docs/
│ └── adr/ ← system-wide decisions
├── src/
│ ├── sourcing/
│ │ ├── GLOSSARY.md
│ │ └── docs/adr/ ← context-specific decisions
│ └── costing/
│ ├── GLOSSARY.md
│ └── docs/adr/
Files are created lazily: only when there is something to write. If GLOSSARY.md does not exist yet, create it when the first term is finalized. If docs/adr/ does not exist, create it when the first ADR is needed.
What to Do While Working
Challenge Terminology in the Glossary
When the words used by the user conflict with existing definitions in GLOSSARY.md, point it out immediately. For example: "The glossary defines '替代料' as X, but your current meaning seems to be Y. Which one is it?"
Sharpen Vague Terms
When the user uses a vague or polysemous word, propose a precise standard term. For example: "When you say '料號', do you mean our internal part number, or the manufacturer's part number (MPN)? These are different things."
Test with Concrete Scenarios
When discussing relationships between domain concepts, stress-test them with concrete scenarios. Invent scenarios that explore boundaries, forcing the user to clarify the lines between concepts. For example: "If the manufacturer part number is the same but the package is different, is it considered the same part or an alternate part?"
Cross-Reference with Code
When the user describes how something works, check the code for consistency. If you find contradictions, raise them: "Your code calculates cost by only looking at the first price break, but you said you want to use the corresponding break based on MOQ. Which is correct?"
Update GLOSSARY.md on the Spot
Once a term is finalized, update GLOSSARY.md immediately. Do not accumulate terms to write them all at once; record them as they occur. See format in GLOSSARY-FORMAT.md.
GLOSSARY.md must not contain any implementation details. Do not treat it as a spec, draft notebook, or a place to store implementation decisions. It is just a glossary, and nothing more.
Propose ADRs Judiciously
Only propose creating an ADR when all three of the following conditions are simultaneously true:
- Hard to undo: The cost of changing your mind later is high
- Seems odd without context: Future readers will wonder "Why was this done?"
- Result of a genuine trade-off: There were indeed other feasible options at the time, and you chose one for specific reasons
Skip if any one of the three is missing. See format in ADR-FORMAT.md.