From 3e3bcf302056c8509e3804c2a84a8dff9c5a21fb Mon Sep 17 00:00:00 2001 From: Roberto Cano <3525807+robercano@users.noreply.github.com> Date: Wed, 1 Jul 2026 21:28:03 +0200 Subject: [PATCH] docs(getting-started): add per-stack test_affected guidance (#4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a "Choosing test_affected per stack" subsection to Step 3 — turbo/nx/pnpm/ cargo/go/Foundry/gradle options, "full suite is a fine default", and the worktree base-ref caveat (ties to #9). Docs-module slice of #4; the optional _test_affected_note in .claude/gates.json is a separate module:harness follow-up. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_011HosUeuSvhetARboEfDW6K --- docs/GETTING_STARTED.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 9b77b70..554c79d 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -54,6 +54,25 @@ Each should run the right command (or say "not configured — skipping"). > Either way, don't point a gate at a command that can't pass yet — a red `test_affected` will block the > `Stop` hook and every agent's "done". +### Choosing `test_affected` per stack +`test_affected` runs on the `Stop` hook after every change, so it should be *fast* — ideally only the tests +touched by the diff. But "test only what changed" isn't free in every stack. Sensible options: + +| Stack | Cheap `test_affected` | Notes | +|---|---|---| +| turbo | `turbo run test --filter='...[origin/main]'` | needs turbo | +| nx | `nx affected -t test --base=origin/main` | needs nx | +| pnpm (no turbo/nx) | `pnpm --filter '...[origin/main]' test` | flaky in worktrees unless `origin/main` is fetched first — see #9 | +| cargo | `cargo test` (or `cargo nextest run`) | no cheap since-base; full suite is fine | +| go | `go test ./...` | already fast; no filter needed | +| Foundry | `forge test` | **no** native since-base — run all | +| gradle | `./gradlew test` | full suite | + +**`test_affected` = your full `test` command is a perfectly good default** whenever the suite is fast — only +reach for affected-filtering when the full run is too slow to gate on every `Stop`. And note the worktree +gotcha: any filter that diffs against `origin/main` needs that ref present in the worktree, so `git fetch +origin main` first (or fall back to the full suite) — the per-worktree setup hook in #9 is the place for that. + ## Step 4 — Review the agents (usually no change needed) Skim `.claude/agents/*.md`. They're generic and read `gates.json`, so they typically need no edits. Adjust `model:` per agent if your routing differs, or add project review skills (e.g. a security/audit skill) and