diff --git a/CLAUDE.md b/CLAUDE.md
index 995e7c74..c88029c2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -266,6 +266,7 @@ Conventions:
 - Suite naming: `*_public_test.go` → `{Name}PublicTestSuite`,
   `*_test.go` → `{Name}TestSuite`
 - Table-driven structure with `validateFunc` callbacks
+- One suite method per function under test — all scenarios (success, errors, edge cases) as rows in one table
 - Avoid generic file names like `helpers.go` or `utils.go` — name
   files after what they contain
 
diff --git a/docs/docs/sidebar/development/development.md b/docs/docs/sidebar/development/development.md
index 462e8d10..97fe0dbe 100644
--- a/docs/docs/sidebar/development/development.md
+++ b/docs/docs/sidebar/development/development.md
@@ -97,6 +97,12 @@ Unit tests should follow the Go convention of being located in a file named
 located in `test/integration/` and use a `//go:build integration` tag. They
 build and start a real `osapi` binary, so they require no external setup.
 
+Use `testify/suite` with table-driven patterns and `validateFunc` callbacks.
+**One suite method per function under test.** All scenarios for a function
+(success, error codes, transport failures, nil responses) belong as rows in a
+single table — never split into separate `TestFoo`, `TestFooError`,
+`TestFooNilResponse` methods.
+
 ### File naming
 
 Avoid generic file names like `helpers.go` or `utils.go`. Name files after what