From 414dc840fd781c53ec910c23dd2ca3de0dc0149c Mon Sep 17 00:00:00 2001 From: Lucas Winther Date: Mon, 17 Aug 2026 22:55:17 +0200 Subject: [PATCH] docs(agents): commits are succinct as well as self-contained MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- AGENTS.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9b0269a..cf89dbc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -374,8 +374,16 @@ to an open page). Four things hold it up: ## Conventions - **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 - self-contained — one coherent change, typechecking and passing tests on its own. + branch for a change unless asked for one. Committing still waits to be asked. +- **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 hand-write an interface that duplicates a schema. - Every adapter ships a fixture in `fixtures//` and a test asserting parsed output. This is