← Patterns / practice
Identity fields, minted by command
Two IDs per doc, generated by a command and never changed, because filenames move and models invent.
- Authors
- Michael Staton
- Augmented with
- Claude Code on Claude Opus 5.5
- Tags
- Identity · Frontmatter
What it is
Each doc gets
site_uuid
(a lowercase UUID v4) and
hex_code
(six characters of
a-z0-9
), set once at creation.
Why
Filenames get renamed, docs get copied into roll-ups and sites, and
Filename
can resolve to several files. A stable ID is the only thing that says "these eight copies are one document."
hex_code
doubles as the doc's short citation key.
The second lesson was harder:
language models type UUID-shaped strings that aren't valid UUIDs.
We found real ones with letters like
n
and
z
in them. So IDs come from a command, never from a model's head.
How
uuidgen | tr 'A-Z' 'a-z' # site_uuid
LC_ALL=C tr -dc 'a-z0-9' </dev/urandom | head -c6 # hex_code
The name is
site_uuid
, not
uuid
, so a database's own
uuid
field never collides with it.
In the kit
/cv:new
mints both. The hook blocks a malformed ID, or one that changed on edit.