docs(agents): commits are succinct as well as self-contained

Self-containment was a clause on the end of the commit-straight-to-main
bullet and covered only half of what it should: one coherent change,
green on its own. Nothing said how to split a change that spans layers,
and nothing at all said what the message should contain.

Both halves are now stated. Splitting goes model → store → UI → docs with
each step green by itself, even where that means widening a type in the
model commit that only the UI commit uses — and docs/FEEDBACK.md already
makes the same argument for adapters, so it is cited rather than repeated.
Succinct is about the message: a one-line subject and a body saying why,
which a diff cannot show, rather than a list of files it can. The
no-stray-reformatting line is there because a formatter this project does
not run once buried a 100-line change in a 550-line diff.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
This commit is contained in:
Lucas Winther
2026-08-17 22:55:17 +02:00
co-authored by Claude Opus 5
parent 5bbc9a2759
commit 414dc840fd
+10 -2
View File
@@ -374,8 +374,16 @@ to an open page). Four things hold it up:
## Conventions ## Conventions
- **Commit straight to `main`.** This is a solo repo and its history is a single line; do not open a - **Commit straight to `main`.** This is a solo repo and its history is a single line; do not open a
branch for a change unless asked for one. Committing still waits to be asked, and each commit is branch for a change unless asked for one. Committing still waits to be asked.
self-contained — one coherent change, typechecking and passing tests on its own. - **Commits are self-contained and succinct.** One coherent change per commit, typechecking and
passing tests on its own — a feature spanning layers splits as model → store → UI → docs, each
step green by itself, even when that means widening a type in the model commit that only the UI
commit uses. `docs/FEEDBACK.md` makes the same argument for adapters specifically: do not batch
six games into one commit, because each one is a fixture and a test that has to prove itself.
Succinct is about the message, not the change: a one-line subject in plain English, and a body
that says *why* — the reasoning a diff cannot show — rather than listing the files it touched.
Never reformat code the change did not touch; a formatter the project does not run buries a
100-line change in a 550-line diff.
- **Zod schemas are the single source of truth for types.** Derive with `z.infer<>`; never - **Zod schemas are the single source of truth for types.** Derive with `z.infer<>`; never
hand-write an interface that duplicates a schema. hand-write an interface that duplicates a schema.
- Every adapter ships a fixture in `fixtures/<game>/` and a test asserting parsed output. This is - Every adapter ships a fixture in `fixtures/<game>/` and a test asserting parsed output. This is