Codebase glossary

Codebase Glossary

Extract the domain vocabulary of a codebase. The output answers: "What words in this code mean something specific in this project that an outsider wouldn't recognise?"

Scope

This skill is narrow by design. It covers ONLY:

• Domain-specific nouns (entity names, business concepts, custom abstractions)
• Acronyms and abbreviations used in code
• Status / enum values (e.g., 'trialing', 'completed', 'pending_review')
• Scope strings, role names, permission tokens
• Terms that shadow common words but have a project-specific meaning (e.g., "Sheet" in a banking app, "Account" in a ledger app)

It does NOT cover:

• Generic programming terms (function, class, callback, promise)
• Library/framework terms (component, hook, middleware, decorator) — unless the project repurposes them with a non-standard meaning
• Architecture, naming conventions, testing, error handling — sister skills cover those

What to Produce

A Markdown file with the structure below. Every term must include where it's used — at least one file path or module reference. Single-line definitions only; this is a glossary, not an explainer.

# {Project Name} — Glossary

> Generated by codebase-glossary on {YYYY-MM-DD}

## Domain Terms

| Term | Meaning | Where Used |
|------|---------|------------|
| {Term 1} | {One-line definition based on actual code usage. If you're not sure, mark with [?]} | `{file 1}`, `{file 2}` |
| ... | ... | ... |

Aim for 8–20 terms for a typical project. Include only words that are non-obvious — a generic concept like "user" doesn't need a glossary entry unless it has a non-standard meaning here.

## Acronyms & Abbreviations

| Abbreviation | Full Form | Context |
|--------------|-----------|---------|
| {ACR} | {Full meaning} | {Where it appears, what it refers to} |

## Status & Enum Values

These are the literal string/number values used as state markers throughout the codebase. New code should use these exact values rather than inventing variants.

### {Domain area 1 — e.g., "Subscription"}
| Value | Meaning | Where Defined |
|-------|---------|---------------|
| `'trialing'` | ... | `{file}` |
| `'active'` | ... | `{file}` |
| ... | ... | ... |

### {Domain area 2}
...

## Scopes / Roles / Permissions

If the codebase has explicit permission strings, role names, or scope tokens, list them here.

| Token | Grants | Where Defined |
|-------|--------|---------------|
| `'data:read'` | ... | `{file}` |
| ... | ... | ... |

## Domain Boundaries

{Optional. If the codebase is divided by domain via route prefixes (`/api/v1/plaid/*`), package names (`packages/billing`), or module groupings, list the domains here as a quick map. Each domain → one-line description.}

## Notes

{Anything that's worth saying but doesn't fit a table — common confusions, deprecated terms still in code, terms whose meaning has shifted over time, terms that mean different things in different parts of the repo.}

How to Scan

# Type / interface / class names — primary source of domain nouns
grep -rn "^export type\|^export interface\|^class \|^type [A-Z]\|^@dataclass" --include="*.ts" --include="*.tsx" --include="*.py" --include="*.go" --include="*.dart" --include="*.rs" 2>/dev/null | head -50

# Collection / table names
grep -rn "collection(\|\.collection('\|\.table(\|CREATE TABLE\|model(\|class.*Model\|@Entity" --include="*.ts" --include="*.py" --include="*.sql" --include="*.dart" 2>/dev/null | head -30

# String constants in UPPER_SNAKE_CASE — often domain identifiers
grep -rn "^export const [A-Z_]\+ =\|^const [A-Z_]\+ =\|^[A-Z_]\+ = " --include="*.ts" --include="*.py" 2>/dev/null | head -30

# Status / enum values — string literals in unions, enums, or constants
grep -rn "type.*= '\|enum [A-Z]\|Literal\[" --include="*.ts" --include="*.py" 2>/dev/null | head -20
grep -rn "status.*=.*'[a-z_]\+'\|status: '[a-z_]\+'" --include="*.ts" --include="*.tsx" --include="*.py" --include="*.dart" 2>/dev/null | head -20

# Permission / scope strings (heuristic — colon-namespaced strings)
grep -rEn "'[a-z]+:[a-z]+'" --include="*.ts" --include="*.tsx" --include="*.py" 2>/dev/null | head -15

# Route paths — reveal domain boundaries
grep -rn "\.get('\|\.post('\|\.put('\|\.delete('\|\.patch('\|@app\.route\|@router\.\|router\.[a-z]\+(" --include="*.ts" --include="*.tsx" --include="*.py" 2>/dev/null | head -30

# Acronyms in identifiers (sequences of 2+ uppercase letters)
grep -rEon "[A-Z]{2,}[A-Z][a-z]" --include="*.ts" --include="*.tsx" --include="*.py" --include="*.dart" 2>/dev/null | head -30

# Package / module domain names (monorepo signal)
ls packages/ services/ apps/ modules/ 2>/dev/null

# README / docs for terms the team has defined themselves
grep -i "glossary\|terminology\|definitions\|domain" README* docs/*.md 2>/dev/null | head -10

When you find a recurring noun, read the file where it's defined to derive the meaning from how it's used in code — not from your prior knowledge of similar projects. The glossary should reflect this project's specific meaning, not a generic one.

Where to Save

Check for an existing docs location:

• If docs/ exists, save as docs/glossary.md
• If documentation/ exists, save as documentation/glossary.md
• If .claude/ exists, save as .claude/glossary.md
• Otherwise propose docs/glossary.md and ask the user before creating

Principles

Project-specific only. Don't define generic programming terms. "A User is a person who uses the system" is not a glossary entry — that's just English. A glossary entry is when "User" has a specific meaning in this codebase that's different from the generic one (e.g., "User: in this codebase, refers only to authenticated paying customers — see User schema in users.schema.ts. Free-tier users are Visitors.").

Read the code to define. When you encounter Sheet or Token or Cycle or any other domain noun, read where it's defined and used to derive what it means here. Don't import prior assumptions. A "Sheet" might be a Google Sheet, a billing report, a config file, or an internal domain object — only the code tells you which.

Mark uncertainty. If you can identify a term as project-specific but can't confidently define it, include it with [?] and a best-guess definition. Better to flag uncertainty than skip the term entirely.

Cite locations always. Every glossary entry must include at least one file path. The user should be able to follow the reference back to the code.

Don't pad. If the codebase genuinely doesn't have much domain vocabulary (small utility libraries, generic CLI tools), don't invent terms. A glossary with 3 real entries is more useful than one with 20 padded ones. State the size honestly: "This project has limited domain-specific vocabulary; most terms are standard."

Surface terminology drift. If the same concept is referred to by different names in different parts of the code (User here, Account there, Member elsewhere — all meaning the same thing), flag it in the Notes section.

Don't drift in scope. Don't document architecture, naming patterns, error handling, or tests. If a term has a structural pattern attached to it (e.g., every Service follows the static-class pattern), that's codebase-conventions territory — just define the term here and move on.

After Producing

1. Save the file to the chosen location.
2. In chat, surface the 2–3 most non-obvious terms — the ones an outsider would most likely misinterpret without the glossary.
3. If you found terminology drift (multiple names for the same concept), call it out — that's almost always worth flagging to the team.
4. Provide a path or link to the saved file.