Glossary

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.

Scope

Decide how many glossaries the project needs: