regex-friendly codebase

treat a codebase as an agent's searchable map: every capability discoverable by one stable English domain keyword, traceable by one canonical symbol. an rg search for that keyword or symbol returns definition, callers, tests, contract, and owning documentation with little noise.

agents and humans navigate by exact-text search first. one keyword + one symbol makes a single rg query return the full concept; a second spelling for the same concept makes every query untrustworthy. the invariant: one live name per concept, so search results are a reliable map of ownership and blast radius rather than a sample.

• choose the shortest exact English word unique in the project scope.
• put the domain word in the glossary before introducing the concept.
• use that exact spelling in folders, files, exported symbols, schemas, API operation IDs, query keys, database prefixes, slice names, documentation.
• on collision, prefer a precise two-word public symbol: readWorkflowRun, not read; createChannelInvite, not create.
• write error codes and structured diagnostic fields with the same domain words.

workflow and step are valid short names when unique in the project; they stay independently searchable. do not expand them for style, do not shorten to wf, stp, or an opaque initialism.

no aliases, re-exports, abbreviation layers, duplicate names, or const A = B.x bindings — import the canonical symbol directly. mapper functions only for a real, named translation between boundaries; they are not renames.

order when adding or changing a capability:

1. search the glossary and rg for the shortest exact domain word.
2. select one canonical term or record a new glossary entry.
3. name the boundary files and exported symbols from that term.
4. update every old caller, import, test, API contract, query key, and document in the same forward-only change.
5. prove the old name has no live matches and the new one has expected matches.

find the canonical surface, then exported landmarks, then confirm the obsolete alias is gone:

rg -n --glob '*.{ts,tsx,md,mdx}' '\bworkflowRun\b' .
rg -n --glob '*.{ts,tsx}' 'export (async )?(function|const|class).*Workflow' .
rg -n --glob '*.{ts,tsx,md,mdx}' '\bcurrentRun\b' .

regex is a retrieval tool, not a parser. use typed parsers, AST tools, schemas, and structured APIs to understand or transform syntax and data; use rg to locate exact ownership, duplicated terminology, stale references, and the full blast radius of a rename.

• before a material rename, save the exact search query and result count as baseline evidence.
• after the change, rerun searches for the new canonical term and every retired spelling.
• unexpectedly broad matches = a naming collision to resolve, not search noise.
• zero expected matches = incomplete registration, documentation, or test coverage until proven otherwise.
• rebuild the MDX index after doc changes; use FTS5 for concept discovery, normalized frontmatter joins for ownership and status.

mdxquery index ./data
mdxquery query "SELECT path FROM document_search WHERE document_search MATCH 'workflow'"
mdxquery query "SELECT document.path FROM documents AS document JOIN frontmatter AS kind ON kind.document_id = document.id WHERE kind.key = 'kind' AND kind.value_json = '\"standard\"'"

• can an agent find the owning implementation with one domain keyword?
• does every exported symbol describe its capability without reading its body?
• exactly one live spelling per domain concept?
• do file and folder names make tree output a useful capability map?
• did the change remove retired terms instead of preserving aliases?

bad

export const get = readWorkflowRun;
const currentRun = get(runId);

searching workflowRun misses the alias; searching get returns unrelated collection methods everywhere. one-query navigation becomes archaeology, agents editing get elsewhere silently change behavior under an alias they cannot see, and no search result set shows who is affected by renaming the real symbol — blast radius stops being measurable.

good

export const readWorkflowRun = (workflowRunId: string) => {
  return workflowRunRepository.readWorkflowRun(workflowRunId);
};

one exact symbol gives rg workflowRun a small, meaningful result set: definition, callers, tests, contract, and owning documentation together, so humans and agents reach the owner in one query and renames update a countable, complete list. kept up across a codebase, search becomes a reliable map of ownership and blast radius rather than a noisy suggestion.

domain glossary · shortest exact names · one symbol per thing · domain-keyword organization · mdxquery