The rules a change is held to
What is open and what is settled is status and roadmap, the ones deliberately not moving are accepted limits, testing your backend is the split these rules assume, and getting help is where to ask first.
One Zod object is a table’s whole definition. The app shape on one side, the SQLite row on the other, every conversion through a codec, and every field described.
Validate at every boundary — including the ones people forget are boundaries. A model’s response is one: a text model will always produce a plausible-sounding label, and an invented one silently poisons every filter downstream.
Guards before validators. A validator ahead of a guard turns a 401 into a 400 and tells an unauthenticated caller which requests were well-formed.
A capability’s name is one segment doing five jobs — the add argument, the migration namespace, the table prefix, the error domain, the audit domain. Never invent a sixth spelling.
No secret is ever printed, logged, or put in an audit event.
Bindings first, REST second. The REST client needs an account token, which a Worker has neither of and should not.
Errors carry a code and params
Never a message alone.
"That board does not exist: weekly." is one string a client can only print. leaderboard/board_not_found with { board: "weekly" } is a sentence any client can rewrite in any language — and the English still arrives on the wire.
message is English permanently, and detail is stripped by the HTTP codec.
Tests are split by runtime, and that split is the argument
Worker tests run inside workerd against a real D1 and a real KV through Miniflare. Everything else runs in Node.
A test that mocks D1 proves the mock works.
Keep the harness’s compatibility date with the Worker’s. A harness pinned older than the Worker it is evidence about is not evidence — that cost a full day on a phantom failure only the harness could produce.
Documentation is part of the change
Every CLI command page carries the same six sections, and a gate holds each page to naming every key its --json payload emits.
Every declared admin route is checked against the router that actually mounted, in both directions, by the capability’s own contract test.
The rule about comments
Write the limits down
A limit nobody recorded reads as a limit nobody saw.
The races that cannot be closed, the platform constraints, the things a vendor does not expose — those sentences are the useful ones, and they belong beside the code rather than in somebody’s memory.
The prose rule
American English, including in comments. Not a style preference: the site ships en-us metadata, so a page using a British spelling contradicts its own header.
A catalog file written in another language declares itself in its head, within the first 25 lines, in one published spelling — and that marker exempts the file’s quoted values, not the file.
Before you commit
Run the checks and gate on the exit code, never on grepping the output.