| name | write-discoverable-code |
| description | Rules for writing code that coding agents (and humans) can find and understand through
plain-text search. Apply whenever writing or renaming code: functions, types, constants,
files, error messages, doc comments.
Grounded in measurement: agents navigate by plain-text search, not by AST or
language server, so every identifier is a search query and every search miss
costs wasted reads.
|
| license | MIT |
Write discoverable code
Coding agents discover code by searching for strings and reading small windows around the
hits. They have no hover text, no jump-to-definition, and no memory between sessions. These
rules make code resolvable in one search instead of five.
1. Names are search queries
- Exported symbols get 2–4 word names, at least one of them a domain word.
diffUserObjects, not diff. queueEventForDispatch, not queue.
Measured on a ~700k-line monorepo: 1-word exported names are globally unique 61% of
the time; 3-word names 96%; 4+ words 98%. Three words is the knee of the curve.
Use the shortest name that greps uniquely; put the rest in the doc comment.
- Give generic verbs their object.
sanitizeEmailHtml, not sanitize;
validateSmtpConfig, not validateConfig. Qualify only as far as uniqueness
requires, then stop.
- One definition site per symbol. Never copy a function between files; move it and
delete the original in the same change. Shared helpers get one concept-named home
and are imported everywhere else.
- Do not rely on the module path to disambiguate a generic name. The import that
disambiguates from sits at the top of the file; the
search hit is at line 300. Put the context in the symbol (), not the
folder. Exception: rigid, absolute conventions where the path carries the meaning
(e.g. every contract file exporting /).
