Initial commit

2026-05-25 05:47:28 +00:00
commit 4d6495ffda
97 changed files with 13403 additions and 0 deletions
@@ -0,0 +1,43 @@
+# Shared Language
+
+Use this page to keep the repository's ubiquitous language stable.
+It is the project-wide glossary for terms that should mean one thing everywhere in design artifacts, code, tests, and reviews.
+
+## Why this exists
+
+Naming inconsistency creates design inconsistency.
+When the same concept is called three different things, reviewers and LLMs start inventing distinctions that are not real.
+A stable shared language improves design quality, review quality, and implementation consistency.
+
+This file is for **project-wide terms**.
+Feature-specific naming choices should also be recorded in the relevant design artifact.
+
+## How to use it
+
+- Add terms that appear across multiple features or modules.
+- Prefer short domain definitions over implementation detail.
+- Record preferred terms and rejected synonyms.
+- Update this file when the team decides one name should win.
+- Keep the grammar consistent with the naming rules in `../explanation/naming-for-domain-modeling.md`.
+
+## Core grammar
+
+- **Commands**: imperative intents such as `LoadPackage`
+- **Events**: past-tense facts such as `PackageLoaded`
+- **States / Objects**: domain nouns such as `LoadingTruck`
+- **Workflows**: verb-noun names such as `loadPackage`
+- **Policies**: decision-oriented names such as `decideLoadEligibility`
+
+## Project-wide glossary template
+
+| Term | Meaning | Use this, not that | Notes |
+| :--- | :--- | :--- | :--- |
+| `<PreferredTerm>` | `<Short domain meaning>` | `<PreferredTerm>` not `<RejectedSynonym>` | `<Optional note>` |
+| `<PreferredTerm>` | `<Short domain meaning>` | `<PreferredTerm>` not `<RejectedSynonym>` | `<Optional note>` |
+
+## Review questions
+
+- Would a domain expert recognize these terms?
+- Are the same concepts named consistently across story, events, model, code, and tests?
+- Are we accidentally using programmer words where domain words should exist?
+- Have we documented which synonym is preferred when multiple names are plausible?