code-style
Code style for zgeoff TypeScript repos: file layout, names, state, unions, types, structure, errors, comments, and the function-name verb table. Load it before you write, review or rename TypeScript, with the repo's project-code-style skill beside it, for its stricter rules and its departures.
- License 许可
- MIT
- 所属仓库
- zgeoff/hq
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- code-style
- metadata
- { "kind": "rule-set" }
- description
- Code style for zgeoff TypeScript repos: file layout, names, state, unions, types, structure, errors, comments, and the function-name verb table. Load it before you write, review or rename TypeScript, with the repo's project-code-style skill beside it, for its stricter rules and its departures.
03 SKILL.md 正文
Code style
Files and modules
- Give each file one main export, and name the file after it:
parse-cli-args.tsexportsparseCLIArgs.index.ts,types.tsandconstants.tshave no main export. When a module has only a side effect, name it for what it does:augment-bun-test.ts. - Order a file as imports, the main export, then its helpers in the order it calls them. Put each type or constant just above its first use.
- Make objects with factory functions, and never write a class. The one exception is a custom error,
such as
class QuotaError extends Error.
Names
- Write an acronym in capitals:
parseCLIArgs,userID,packageURL. At the start of a camelCase name, write it in lowercase:cliPath,idToken. - Name a value for what it holds, in full words:
session, nots;manager, notmgr. - Use a short name only from this list:
xandyfor coordinates,zfor zod,$for Bun's shell,_for an unused value;ctx,id,db,args,params,repoandinfo.
- End a name with its unit:
timeoutMs, nevermsalone.
State
- When a status is saved outside the process or sent to another process, write a transition table for it: its states, the moves allowed between them, and one function that checks a move. Keep all three in the only module that writes the status.
- Build a long-lived object whose states live only in memory, such as a reconnecting client, as an xstate machine.
Waiting
- Sleep with
Bun.sleepin Bun-only code, and withsetTimeoutfromnode:timers/promisesin code that ships to Node. - Wait for one event with
events.once. When code outside the promise's executor settles the promise, make it withPromise.withResolvers(). - Write
new Promiseby hand only when none of these fits.
Unions
- Branch on a union with
match(value)…exhaustive()fromts-pattern, neverswitch, so a new member fails the type check. - End with
.otherwise()only when the value comes from outside the program, such as a string read from input that no schema has parsed.
Types
- Use a type guard, an annotation,
satisfiesor a schema parse, and never a type assertion. The one exception isas const. - When an assertion has to stay, get the maintainer's approval in the PR, and add a lint disable comment that gives the reason. In review, flag every new assertion, approved or not.
- Never let
anyreach a typed value. Make itunknownand narrow it, or parse it.JSON.parsereturnsany.
Structure
- Send data between processes or packages through the repo's typed interface: its RPC layer, a shared schema, or its CLI parser. Never match a route, parse a body or read arguments by hand.
- Split a function in two when it reads something, branches on what it read, and then writes,
removes or runs something:
- a pure function that takes the values read and returns what to do. Give it a verb from a no-I/O
row of the verb table, such as
collectorpick, so thezgeoff/verb-contractrule in@zgeoff/oxlint-configkeeps I/O out of it; - a thin function that does the reads, calls the pure one, and acts on its result. Give it the I/O
verb that fits, such as
run,writeorremove, and no decision of its own.
- a pure function that takes the values read and returns what to do. Give it a verb from a no-I/O
row of the verb table, such as
- Write the pure function first, from the values you will read, then the thin one around it. You
then test each edge case with one
test.eachrow of plain data. In one combined function, each case needs a stand-in for every read and write, so the edges go untested. - Lock a file across processes only with
withFileLockfrom@zgeoff/std/with-file-lock, imported directly in the thin function. Read, decide and write in its callback, so the lock spans all three. Write your own lock only for a need it can't meet, such as a lock readers share, and name the need in a comment. - Reach I/O through dependencies the caller passes in. Create real clients only in the entry point.
- Never write a wrapper that only passes its arguments on.
- Never add an option, a parameter or an extension point before a caller passes it.
export function collectDueReminders(tasks: readonly Task[], now: number): Task[] {
return tasks.filter((task) => task.dueAt < now && task.remindedAt === null);
}
export async function runReminders(dependencies: ReminderDependencies): Promise<void> {
const tasks = await dependencies.db.readOpenTasks();
for (const task of collectDueReminders(tasks, dependencies.clock.now())) {
await dependencies.mail.writeReminder(task.owner, task.id);
}
}
Errors and logs
- Return an expected outcome, such as a miss or bad input from outside, as a value of the return type. Throw only what the caller can't plan for.
- Never check again what the value's source already guarantees, such as its type, a schema parse or
a library's documented behaviour. An example is a
nullcheck on a field the schema requires. - Call
invariant()fromtiny-invarianton a state that only a bug can reach. - Log failures, state changes and slow calls. Never log each call of code that runs once per request or per item.
Comments
- Write a
//comment only to say why the obvious alternative is wrong, when the cause sits outside the file: a library bug, a runtime quirk, a measured number. Put it at the line, in three lines at most. - Never restate what the code or a test shows.
- Never write history or project state in a comment, such as "previously", an issue number or "not wired yet". Put it in the commit.
- Put what callers rely on in a test name, such as
it returns null for an unknown ID, not in a comment. When code in another package depends on an invariant of yours, also state it in the doc underdocs/for that part of the system. - Don't name another declaration in a comment; state the fact, so a rename can't leave it stale.
One-off codemods
- Put a one-off codemod in the PR description, in a
<details>block with the command that ran it, never in the repo.
Function names
When a function's job has a row, start its name with that row's verb, and keep the row's guarantee.
Give any other function any verb that fits, except a banned verb from the last bullet of this
section, such as fetch or process.
| Job | Verb | Guarantee |
|---|---|---|
| yes/no answer | is, has, can, should |
returns a boolean; no I/O |
| yes/no answer that needs I/O | probe |
returns a boolean; may do I/O |
| value from arguments, test data factories included | build |
no I/O |
| text or raw input → structure | parse |
no I/O |
| value → text or markup | format, render |
no I/O |
| choice among known alternatives | pick |
no I/O |
| lookup that can miss | find |
no I/O; can return null or undefined |
| lookup that can't miss | get |
no I/O; never returns null or undefined |
| many values gathered from a traversal | collect |
no I/O |
| cheap change of representation | to |
no I/O |
| content in from outside the process | read |
may do I/O |
| content out to outside the process | write |
may do I/O |
| subprocess or task | run |
may do I/O |
| resource brought into existence | create |
may do I/O |
| resource taken away | remove |
may do I/O |
| function that returns a function | make |
returns a function |
| higher-order wrapper | with |
runs a callback inside a context |
| React hook | use |
follows the rules of hooks |
| prop or parameter that takes an event callback | on |
follows the framework's callback convention |
function passed to an on prop, or a function that handles a framework lifecycle event such as a request |
handle |
follows the framework's callback convention |
| a test file's per-test fixture | setupTest |
as the testing skill's setupTest section says |
| stored state put in place for a test, through the production module when the module can make that state | seed |
may do I/O; test code only (seeding rules) |
- Keep a pure function pure all the way down: a
buildthat calls areaddoes I/O. Thezgeoff/verb-contractrule in@zgeoff/oxlint-configchecks the verbs, but it can't see I/O inside an npm package or behind a helper whose name hides it. Check those by hand. - Start a boolean function with
is,has,canorshouldeven when another verb reads well. Two kinds of boolean function keep their own verb:- a function with an I/O verb that returns a success flag, such as
removeFile; - a function whose name starts with
use,onorhandle.
- a function with an I/O verb that returns a success flag, such as
- Never use
make,with,use,onortoas a whole name. Follow it with a noun, such astoPosixPath. - You may start a name with
resolvewhether or not it does I/O, such as for a pure lookup or a filesystem search. - Never start a name with one of these verbs. They say nothing about I/O or a miss:
process,manage,do,perform,executeorcompute;fetch,save,store,delete,searchorlookup. For a database read that can miss, usereadand returnnull;handle, outside a callback.
04 同仓库更多 Skills
tickets
What a good Linear issue is in team GEO - its sections, when it is Ready, its fields, the Actions an agent may take, cross-repo and umbrella work, and how to save it. Load it before you write, rewrite, groom, split or save an issue, or judge whether one is Ready.
release
How z-release takes merged work to live across the zgeoff repos - release PRs, the nightly batch, cloud deploys, bump PRs, host switches, the nixie memory-store backup check, recovery and the hard timing rules. Load it in z-release's session, and before any release, deploy, host switch, atc upgrade or rollback.
preview-qa
Runs live checks for the owner's issues, on a PR's preview environment before the merge and read-only on production once the release ships, records the evidence on the issue, closes it, and hands back only the checks that need the owner. Use when z-review sends a preview check with an issue, its PR and the items to check, or when hq or z-release messages "Shipped, now live-check".
pr-review
How z-review reviews and merges every PR in the zgeoff repos, and files the only follow-up issues a PR may leave. Load it when hq messages "Final: GEO-n (repo#n at <sha>)", when an agent answers a finding, when a session sends z-review a PR to merge, or before an issue is filed from a PR.
owner-calls
What only the owner decides, how a session puts something to the owner, how the owner's answers count, and the fleet's shared terms. Load it before you flag an issue for the owner, send a decision or a hands-on step for the owner, decide something under a grant, or act on an answer of the owner's.
linear-triage
How z-triage keeps the owner's Linear workspace accurate: grooming every open issue, moving it to Ready once it meets the criteria, acting on hq's alerts, and queuing the owner's questions as calls. Load it for each scheduled pass and check, when a session asks for a check now, when hq sends an alert, and before an issue is written or rewritten.