TanStack DB Agent Rules

A reactive client database for collections, live queries, and optimistic mutations.

Overview

TanStack DB turns recurring review problems into rules illustrated with good and bad code. Query and test guidance requires independent expected results, counterexamples for contract changes, and tests that fail for plausible wrong designs.

Behavioral framing Hard prohibitions Good and bad pairs Router files Contribution etiquette

Documents

├── 
├── docs
│   └── contributing
│       ├── 
│       └── 
└── packages
    └── db
        └── src
            └── query
                └── live
                    └──

Techniques in this file

01 / Behavioral framing

Turn review bugs into missing test dimensions

A confirmed defect should identify the missing law, state transition, generator dimension, adapter boundary, or assertion. The goal is to cover the class of failure rather than only pinning the reported example.

393When a reviewer agent confirms a bug, it must also ask why the existing tests394did not catch it. The finding should name the missing test law, state

02 / Hard prohibitions

Keep the expected result independent of production branches

The guide prohibits copying production classifiers or state machines into a supposed oracle. Expected behavior must come from contracts, mathematical laws, prior documented behavior, or a separately specified model.

403An oracle is useful only when its expected result comes from a source independent404of the implementation under test. Do not translate production branches, state405machines, classifiers, or helper functions into a second implementation and call406that an oracle. Both copies can encode the same wrong assumption.

03 / Good and bad pairs

Show where query intersections stop being intuitive

Two limited-query examples show why combining predicates and taking the smaller limit may not produce the real intersection. The guide connects the failure to ordering, limits, and subsets.

236-- Query 1: WHERE age >= 18 LIMIT 1237-- Query 2: WHERE age >= 20 LIMIT 3238-- Naive intersection: WHERE age >= 20 LIMIT 1239-- Problem: This may not return the actual intersection of results

04 / Router files

Read the coverage map before adding another model

Oracle work begins with both the testing-method guide and a map of existing coverage owners. The guide explicitly does not grant permission to redefine product behavior or discard existing laws.

367Use the [coverage map](docs/contributing/oracle-coverage.md) to find an existing368owner and its limits before adding another model. The guide explains testing

05 / Contribution etiquette

Treat published history as shared state

The Git section distinguishes a local commit from a branch others can already see. It provides normal follow-up commits as the alternative to amending or force-pushing, including force-with-lease.

647Once a branch is visible to others, treat its history as shared. If CI fails or follow-up changes are needed, add a normal follow-up commit and push normally.

Ideas for your repo

Require a review finding to explain the coverage gap that let it survive.
Derive expected behavior independently from the implementation being tested.
Use small counterexamples to explain domain semantics.
Document the existing coverage owner before adding another test model.