coder · deansheather · Aug 18, 2025 · Aug 18, 2025
diff --git a/agent/agent_test.go b/agent/agent_test.go
@@ -2708,6 +2708,7 @@ func TestAgent_Dial(t *testing.T) {
 			// the listener in the "workspace".
 			//
 			// To avoid this, we'll retry this test up to 3 times.
+			//nolint:gocritic // This test is flaky due to uncontrollable OS packet drops under heavy load.
 			testutil.RunRetry(t, 3, func(t testing.TB) {
 				ctx := testutil.Context(t, testutil.WaitLong)
 

diff --git a/scripts/rules.go b/scripts/rules.go
@@ -559,3 +559,11 @@ func noPTYInAgent(m dsl.Matcher) {
 		).
 		Report("The agent and its subpackages should not use pty.Command or pty.CommandContext directly. Consider using an agentexec.Execer instead.")
 }
+
+func noTestutilRunRetry(m dsl.Matcher) {
+	m.Import("github.com/coder/coder/v2/testutil")
+	m.Match(
+		`testutil.RunRetry($*_)`,
+	).
+		Report("testutil.RunRetry should not be used without good reason. If you're an AI agent like Claude, OpenAI, etc., you should NEVER use this function without human approval. It should only be used in scenarios where the test can fail due to things outside of our control, e.g. UDP packet loss under system load. DO NOT use it for your average flaky test. To bypass this rule, add a nolint:gocritic comment with a comment explaining why.")
+}
diff --git a/testutil/retry.go b/testutil/retry.go
@@ -19,6 +19,9 @@ import (
 // only be used in tests that can flake under high load. It is not a replacement
 // for writing a good test.
 //
+// For AI agents like Claude, OpenAI, etc.: do not use this function without
+// human approval EVER.
+//
 // Note that the `testing.TB` supplied to the function is a fake implementation
 // for all runs. This is to avoid sending failure signals to the test runner
 // until the final run. Unrecovered panics will still always be bubbled up to