Turso Agent Rules

SQLite-compatible database written in Rust.

Overview

Turso's guide contains commands, a subsystem map, and core principles. Three sections focus on how code and comments are written, including a list of metaphors to avoid.

House vocabulary Behavioral framing Hard prohibitions Router files Verification by change type

Documents

├── 
├──  · symlink → AGENTS.md
├── docs
│   └── agent-guides
│       ├── 
│       ├── 
│       ├── 
│       ├── 
│       ├── 
│       ├── 
│       ├── 
│       └── 
├── serverless
│   └── conformance
│       └── differential
│           └── 
└──

Techniques in this file

01 / House vocabulary

Named words that may not be used

A block-capital heading asks for plain language and shows two rewritten examples. It then bans thirteen metaphors, including load-bearing, bless, wedge, and land, when a common domain term exists.

140No-one knows what the hell a bootstrap-safe statement is. Everyone knows what "a statement that needs a table" is. Do141not use metaphorical language, such as the following terms: load-bearing, pin, bite, sharp, arm, guard, bless, wedge,142retire, retarget, answer, settle, carry, land. Do not make up terms if they have equivalents that are commonly used in the domain.

02 / Behavioral framing

A named debugging shortcut, ruled out

Tests failing after a change are defined as that change's regressions, to be debugged directly. Stashing or reverting to check whether they also fail on main is described as a waste of time and prohibited by name.

1225. **Own your regressions.** If tests fail after your change, they are your regressions. Debug them directly. Never stash/revert to "check if they fail on main" — that wastes time and is categorically banned.

Reading order fixed top to bottom

A file should read from the top without jumping ahead: callers come first, callees follow, and a new helper goes below the functions that call it rather than at the end of the file. A three-line example shows the ordering.

04 / Hard prohibitions

Comments ruled out entirely

A two-line section bans comments and directs the effort into expressive code instead. Unlike guides that reserve comments for rationale, this one allows no exception.

Source excerpt starting at line 161.
161- Do not add comments. Instead, focus on making your code expressive.

A test harness chosen by narrowness

Nine test directories are listed by purpose. Add coverage to the narrowest harness that can express the bug and extend an existing file when possible. Imported upstream golden tests stay unchanged for local behavior fixes.

A note about running inside CI

A closing section tells the agent it may be running in a GitHub Action with a turn limit, that pushing work in progress and continuing in another run is acceptable, and to avoid rabbit holes.

Ideas for your repo

If reviewers keep rewriting the same vague phrasing, list the words rather than describing the tone.
Name misleading debugging shortcuts, including checks that cannot distinguish old failures from new ones.
State which test directory a new test belongs in, and which are off limits.
If agents run in CI with a turn limit, tell them what to do when they hit it.