Menü
Project glossary for consistent domain terminology. Invoke whenever task involves creating, updating, or referencing a glossary, defining domain terms, establishing ubiquitous language, or when inconsistent naming causes confusion in code or planning artifacts.
| name | glossary |
| description | Project glossary for consistent domain terminology. Invoke whenever task involves creating, updating, or referencing a glossary, defining domain terms, establishing ubiquitous language, or when inconsistent naming causes confusion in code or planning artifacts. |
A glossary prevents naming drift on the small set of terms where drift is likely. It is not a project dictionary —
not every domain concept belongs. The highest-leverage element of each entry is the rationale on the Avoid line:
what plausible-but-wrong name would a reviewer or agent reach for, and why is it a trap? Without that rationale, the
entry teaches nothing.
LLMs are amplifiers — give them a clear vocabulary and they generate coherent structure; give them a codebase where the same concept has four names, and they'll invent a fifth. The glossary makes the choice for them.
A glossary's real failure mode is disuse. If it isn't the document a reviewer reaches for during naming disagreements,
no amount of format polish saves it. Every rule below — the trap test, rationale-bearing Avoid lines, the CLAUDE.md
pointer — exists to make the glossary worth opening.
Decide how many glossaries the project needs:
Order in
billing vs fulfillment). In DDD terms, each bounded context speaks its own dialect of the ubiquitous language; one
glossary per dialect. Create one file per context; name each context explicitly.A per-context glossary defines terms within its dialect, but the relationships between contexts — which context
emits an event another consumes, which value types they share — live in no single glossary. When a project has several
context glossaries, an optional docs/ubiquitous-language/context-map.md names each context with a one-line purpose and
the directional flows between them:
## Contexts
- **Ordering** — places and tracks customer orders.
- **Fulfillment** — picks, packs, ships.
## Relationships
- Ordering emits `OrderPlaced`; Fulfillment consumes it.
- Ordering and Billing share `CustomerId` and `Money`.
Add it only when multiple contexts genuinely exist and the cross-talk is not obvious from the names. It is prose, not a
table, and it complements — does not replace — a context-map diagram (see the diagramming skill).
For each candidate term, apply the trap test: would a reviewer or agent plausibly reach for a wrong name here? If the only name anyone would use is the canonical one, omit the entry. The glossary's job is naming-drift prevention, not domain documentation.
Where to look — discovery is evidence-driven, not enumeration-driven:
gerrit-events-consumer").Job vs project Task)."Find every entity, event, and value object" reliably produces overcollection — most candidates won't pass the trap test anyway. Start from evidence of confusion, then filter.
Worth including:
Source, but everyone says Gerrit.Re-release reads as Retry to anyone not steeped in it.Job,
the project calls it Task).Worth omitting:
The selectivity rule is load-bearing. A glossary that lists everything trains the next pass to add more "for completeness," and the bloat compounds. Restraint at creation defends against bloat at maintenance.
Every glossary opens with a 2–3 sentence scope statement. This deflects "why isn't X here?" from readers and calibrates
the Avoid criterion for downstream consumers:
# [Project] Glossary
Project vocabulary. Only entries with a real risk of being mis-named are listed; everything else is in
[CLAUDE.md](../CLAUDE.md). For each term, **Avoid** lists the synonyms that are realistic naming traps — names a
reviewer or agent would plausibly reach for and get wrong.
The intro is not boilerplate — it is the contract between the glossary and its readers. Adapt the wording to the
project, but keep the two contractual statements: (1) the selectivity criterion, and (2) what Avoid means.
### TermName
1–3 sentences defining what the term **is**, not what it does. Carry nuance — three kinds, four phases, an "and not"
clarification. No need to compress to one line.
**Avoid:** WrongName₁ (one-phrase rationale — what trap this name sets); WrongName₂ (rationale).
Definition rules:
(source, chat, project, actor)
tuple" — not "the thing created when events are aggregated."Avoid rules:
Avoid line must carry rationale in parentheses. Bare synonym lists ("Purchase, Transaction,
Sale") rarely teach — the reader still doesn't know which trap is worth worrying about. With rationale ("Retry —
implies error recovery, which this is not"), the entry becomes a calibration anchor.Avoid entries), question whether the term belongs in the
glossary at all. Most "no-trap" entries should be deleted, not entered without Avoid.Include only when the project genuinely benefits. Each one earns its place; don't bolt them on by default.
When entries cluster naturally — Pipeline Concepts, Subscription Model, External Boundaries — use H2 headings to group them. A flat list works for small glossaries. Don't force groupings on five entries.
When the conversation or codebase actually uses one word for two concepts, call it out:
## Flagged ambiguities
- "Account" is used in code for both **Customer** (places orders) and **User** (auth identity). These are distinct
concepts; new code should not introduce `Account` without a disambiguating suffix.
Include only when a live conflict exists. Do not add an empty section as a placeholder.
For terms with non-obvious cardinality:
## Relationships
- An **Invoice** belongs to exactly one **Customer**.
- A single **Order** can produce many **Invoices** — one per **Shipment**.
Narrative sentences, not a column. Skip when relationships are obvious from the entries themselves.
A short dialogue or 2–4 sentence narrative showing terms in natural use. Calibrates the register and exposes boundary cases the definitions missed — especially useful when two concepts could plausibly be confused:
## Example usage
> **Reviewer:** Why is this job re-released on every loop?
> **Author:** That's the **aggregation gate**. **Re-release** is the mechanism — not a retry. The bucket stays open
> while the gate says new events are still arriving.
> **Reviewer:** So flush only happens after `MaxAccumulationTime`?
> **Author:** Or after `ReReleaseInterval` of silence — both conditions matter.
docs/glossary.md or docs/ubiquitous-language/glossary.mddocs/ubiquitous-language/{context}-glossary.md (e.g., billing-glossary.md)docs/ubiquitous-language/context-map.md## Domain Vocabulary
See `docs/glossary.md` for project terminology and prohibited aliases.
When applying terminology (not creating or updating):
docs/glossary.md, docs/ubiquitous-language/, or ask the user.Avoid entries.Maintenance is event-driven, not scheduled:
Avoid rationale — write down which name was reached for, and why it's wrong.**Deprecated:** prefer [NewName] — [one-phrase reason] at the top of the definition. Delete the entry once the
codebase is clean. This is the one acceptable exception to the no-changelog rule — the marker is operational, not
historical.Edit in place. The glossary is single source of truth, not a versioned document.
When invoked again on the same project:
A re-run is not an append. It is a re-derivation that may shrink the glossary as well as grow it.
Avoid lines. Each
entry is independent; KV/heading is the right primitive.Avoid lines carry rationale. Synonyms without "why it's a trap" rarely teach.A well-formed glossary fragment for a Gerrit-event → chat-message notifier:
# Notifier Glossary
Project vocabulary. Only entries with a real risk of being mis-named are listed; everything else is in
[CLAUDE.md](../CLAUDE.md). For each term, **Avoid** lists the synonyms that are realistic naming traps.
## Pipeline Concepts
### Source
A _named_ Gerrit instance — the key under `gerrit.sources` in config. Embedded in the webhook URL and in every cache
key. Multi-tenant isolation is load-bearing: never collapse this axis because "we only have one Gerrit."
**Avoid:** Gerrit (ambiguous with the product — the _instance_ is one of potentially many); Backend (suggests a
storage/persistence layer it isn't).
### Atomic Event
A single Gerrit webhook event carried as one queue job. Lives only long enough to be parsed, matched to subscribers,
and pushed into a Logical Event cache. The atomic/logical split is not optional — collapsing them collapses the
aggregation window.
**Avoid:** Raw event (sounds like an unparsed payload — but it's already parsed); Gerrit event (Gerrit emits many
event _types_; "atomic" names the unit, not the source).
### Re-release
Returning a beanstalkd job to its tube so it is reserved again later. In this project it is the **normal aggregation
mechanism**, not an error path — atomic-job re-releases enforce the per-job delay cycle; logical-job re-releases keep
the bucket open.
**Avoid:** Retry (implies error recovery — the most common and most damaging misnomer here); Requeue (suggests a
separate queue when it's the same tube).
```
Notice what is not in this fragment: MultiClient, EventSampler, BeanstalkJobDelay, Workbench. They are
config or implementation details documented in code and have no plausible-wrong name. They fail the trap test.
Design and iterate Claude Code skills: SKILL.md structure, description formulas, content architecture, and quality evaluation. Invoke whenever task involves any interaction with Claude Code skills — creating, reviewing, evaluating, debugging, or improving skills.
Task creation for issue trackers — structured descriptions, acceptance criteria, field categorization, and tracker linking. Invoke whenever task involves creating work items in any issue tracker — bugs, features, stories, tasks, or any tracked work from standalone requests or decomposition documents.
Coding workflow covering discovery, planning, implementation, and verification. Invoke whenever task involves any interaction with code — writing, modifying, debugging, refactoring, or understanding codebases. Runs discovery protocol before language-specific skills engage.
Structured work handoff across context boundaries: triage decisions, constraints, and remaining work into a prompt-quality transfer document. Invoke whenever task involves handing off work — session restart, teammate delegation, async resumption, or any context boundary crossing.
Rust language conventions, idioms, error handling, concurrency (CPU-bound parallelism with threads/rayon and I/O-bound async with Tokio), the cargo/clippy/rustfmt toolchain, and rustdoc. Invoke whenever task involves any interaction with Rust code — writing, reviewing, refactoring, debugging, or understanding .rs files and Cargo projects.
Rust testing conventions and frameworks: built-in #[test], integration, and doctest layout plus the cargo-nextest runner and the proptest, insta, criterion, mockall, and rstest ecosystem. Invoke whenever task involves any interaction with Rust tests — writing, running, configuring, or debugging tests in .rs files and Cargo projects.