diff --git a/AGENTS.md b/AGENTS.md
index 9048866fd..be52d1f2c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -233,6 +233,7 @@ See [docs/conventions.md](./docs/conventions.md).
 - Unit tests: Vitest.
 - E2E tests: Playwright.
 - Test core/UI services and stores with faked injected dependencies and explicit props.
+- Prefer a parameterised test shape (`it.each`/`test.each`) when several cases exercise the same logic with different inputs and expectations. Keep separate tests when cases differ in setup, assertions, or intent.
 - Colocate tests as `.test.ts` or `.test.tsx`.
 - Put E2E tests in `tests/e2e/`.
 - After touching `@posthog/platform`, rebuild or typecheck its `dist/`.
diff --git a/docs/testing.md b/docs/testing.md
index 0546109ab..bdc6e79b9 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -98,6 +98,22 @@ describe("store", () => {
 });
 ```
 
+## Parameterised Tests
+
+Prefer a parameterised test shape when several cases exercise the same logic with different inputs and expectations. Use Vitest's `it.each` / `test.each` instead of copy-pasting near-identical `it` blocks.
+
+```ts
+it.each([
+  { input: "main", expected: true },
+  { input: "feature/x", expected: false },
+  { input: "", expected: false },
+])("isDefaultBranch($input) === $expected", ({ input, expected }) => {
+  expect(isDefaultBranch(input)).toBe(expected);
+});
+```
+
+Keep cases as separate `it` blocks when they differ in setup, assertions, or intent — parameterise repetition, not distinct behaviors.
+
 ## Mocking
 
 Hoist mocks for modules that must be mocked before import evaluation.