write-discoverable-code
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
- 最近更新
- 2026-11-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- write-discoverable-code
- license
- MIT
- 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.
03 SKILL.md 正文
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, notdiff.queueEventForDispatch, notqueue. 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, notsanitize;validateSmtpConfig, notvalidateConfig. 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
users/diff.tsfromorders/diff.tssits at the top of the file; the search hit is at line 300. Put the context in the symbol (formatDurationMs), not the folder. Exception: rigid, absolute conventions where the path carries the meaning (e.g. every contract file exportingInput/Output). - One concept, one spelling. Pick
organizationIdororgIdand use it everywhere; every synonym splits every future search in half. Reuse existing vocabulary in the codebase you are editing rather than introducing near-synonyms. - When behavior or audience changes, rename in the same commit. A stale name is
misinformation with a 100% open rate — that includes visibility markers: a
_privatehelper that other modules now import needs a public name. - Filenames are names too — never use bare-role filenames.
config.ts,types.ts,utils.ts,helpers.ts,handlers.tssay nothing in a search result and collide with every other module's config/types/utils in the repo. Prefix the domain:billing-plan-config.ts, notconfig.ts. (index.tsis acceptable only as a thin re-export entry point.)
2. Types are the documentation agents can't skip
- Brand your primitive IDs.
z.string().brand<'UserId'>()(TS) or newtypes (Rust). AtransferOwnership(userId: string, orgId: string)signature makes argument transposition invisible; branded types make it a compile error that names the concepts. - Use capability-token parameter types for privileged operations (e.g. requiring an
OrgScopedDbinstead of a raw connection). A comment is a request; a required type is physics. - Model state with discriminated unions, not clusters of nullable fields with implicit rules.
- Name types like they'll be quoted back — they will be, in compiler errors the agent
uses to self-correct.
OrgScopedDbexplains itself;Ctx2does not. Avoidany: everyanyis a spot where the compiler goes silent and the agent is back to guessing.
3. Say it where the search lands
- One-line doc comment on every export, stating the sharpest constraint the code itself can't show (units, timezone, "source time, not insert time", ownership). The definition is where a name search lands; that line is your whole message.
- Write the plain-words phrase in the doc comment. Searches arrive as natural language
("rate limit", "retry delay"), and camelCase identifiers don't match phrase greps —
RateLimiteris invisible to a search for "rate limit". The doc comment above each export should contain, in ordinary spaced-out words, the phrase someone would search for: aSessionExpiryCheckershould say /*_ Checks whether the user session has expired. _/ so that a grep for "session expired" or "session has expired" lands here. - A module should make sense with its imports unread. Each imported name plus its doc line should say enough that the reader never has to open the source module. If they do, the import's name is failing, not the reader.
- Keep strings whole. Never build event names, flags, or error codes with template
interpolation (
`github.${entity}.${action}`makesgithub.pr.mergedunsearchable). Write the full literal even when a loop feels DRYer. - Error messages start with a unique literal prefix, so a message seen in a log greps
straight back to the throw site.
throw new Error(`Webhook signature mismatch for ${id}`), neverthrow new Error(`${prefix}: mismatch`). - One searchable concept per file, and keep orchestrators thin. The code that answers "where is X done?" should live in a module named after X — the thing a reader would ask about, not the mechanism inside — not inline in a coordinator, pipeline, or service class. An orchestrator should read as a sequence of calls into well-named modules; if a reader lands in it from a search, every line should point them one hop from the real implementation. Burying the implementation of several concepts in one large file makes every search for any of them land on the same wall of code. Split until each question-sized concept has one named home, then stop: a helper meaningful only inside one concept belongs inline, and a file per tiny function fragments one answer across several reads. The test runs both ways: a module that answers many unrelated questions is holding more than one concept.
- Colocate tests (
foo.test.tsnext tofoo.ts) so one search finds behavior and its specification together. - Mark dead ends.
@deprecatedon the old path, with a pointer to the new one.
Quick checklist before committing
- Would one search for each new exported name be enough to find its implementation?
- Would swapping two arguments of the new function fail the build?
- Is the one thing a caller must know but the signature can't say (units, timezone, ownership, ordering) written right at the definition?
- Do all log/error strings exist verbatim in the source?
- Did anything change behavior without changing its name?
- When code moved, is it gone from where it came from?
04 同仓库更多 Skills
typesafe-ai
Build AI-powered software with TypeSafe: small units of AI intelligence you can use like programming primitives. Its System One models, including Jev, turn natural language and application state into typed judgments and probabilities that code can combine. Use when a feature needs programmable common sense, when brainstorming what AI could make possible in an app, or when an LLM prompt-and-parse step could become a structured decision. Applications include routing, ranking, extraction, verification, and interactive experiences; these are starting points, not the limits. Read live docs and cookbooks to find useful patterns and discover new combinations.
noodle
Operate the Noodle CLI — explain commands, find flags, create/edit .noodle.toml config. Also covers writing skills for Noodle: the orders pipeline, task-type schedule fields, stage composition, and the orders-next.json schema. Use when running noodle commands, editing .noodle.toml, writing or updating a skill's schedule field, authoring new task-type skills, or asking "how to run noodle", "noodle help", "configure noodle".
how
Explain how something works in this codebase by exploring code and producing a clear architectural explanation. Optionally critique the architecture for issues.
decision-models
Classifier models (Jev, Clef) that answer typed questions about state with calibrated probabilities. Use when calling `models.classify` in pi codemode; when building or debugging code that calls Jev or Clef; or when replacing an LLM prompt-and-parse step, keyword match, or heuristic with typed questions.
cua-driver
Drive a native GUI app (macOS, Windows, Linux) via the cua-driver CLI (default) or MCP server; snapshot its accessibility tree, act through snapshot-bound element tokens, native menu paths, exact window geometry, or pixel coordinates, and verify from fresh state. Use when the user asks you to operate, drive, automate, or perform a GUI task in a real application on the host, or to continue, resume, or recall recent Cua activity.