Go 1.24 synctest Virtual Clock Concurrency Standard | AgentRules.org

Rules Stacks Clients Auditor Pruner Self-Heal RFCs Benchmark CLI CI/CD Authors Submit

This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →

backendcritical PriorityID: go-synctest-deterministic-concurrency-testing

Go 1.24 synctest Virtual Clock Concurrency Standard

Enforces deterministic testing of concurrent and time-sensitive Go backend code using Go 1.24's testing/synctest package. Prevents test flakiness, wall-clock sleeps, and unbounded async polling by executing goroutine topologies inside isolated synthetic bubbles with instant virtual time advancement.

Prohibited Anti-Pattern: Relying on arbitrary wall-clock time.Sleep and flaky poll loops for concurrent synchronization

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Go 1.24 synctest Virtual Clock Concurrency Standard - Enforces deterministic testing of concurrent and time-sensitive Go backend code using Go 1.24's testing/synctest package. Prevents test flakiness, wall-clock sleeps, and unbounded async polling by executing goroutine topologies inside isolated synthetic bubbles with instant virtual time advancement.
globs: **/*_test.go
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/go-synctest-deterministic-concurrency-testing"
---

# Go 1.24 synctest Virtual Clock Concurrency Standard

> **Severity**: CRITICAL | **Category**: backend
> **Anti-Pattern Warning**: Relying on arbitrary wall-clock time.Sleep and flaky poll loops for concurrent synchronization

## System Constraints
You are a Principal Go Architect enforcing the Go 1.24 testing/synctest deterministic virtual concurrency standard. Mandate isolated virtual bubbles for time-dependent concurrent workflows, reject non-deterministic wall-clock sleeps, ensure clean bubble isolation, and verify that all goroutines inside bubbles settle durably using synctest.Wait.

## Strict Guidelines
- Engineers MUST ALWAYS encapsulate time-dependent concurrent tests within a synctest.Run(func() { ... }) bubble rather than relying on real-time wall-clock delays.
- Engineers MUST invoke synctest.Wait() to assert that all spawned goroutines within the synthetic bubble have settled into a blocked state before validating side effects.
- Engineers MUST NOT leak background goroutines beyond the lifecycle of synctest.Run; all goroutines inside a bubble must terminate before the test closure exits.
- Code inside a synctest bubble MUST NOT block on synchronization primitives (channels, sync.WaitGroup, sync.Mutex) owned or signaled by goroutines outside the bubble.
- Services verifying retry backoffs, connection heartbeats, and leader election leases MUST assert state at exact virtual time intervals without artificial latency overhead.

## Bad vs Good Implementations
### Async Queue Processing and Backoff Testing

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Relies on real wall-clock delays that slow down test suites and introduce non-deterministic CI failures under CPU throttling or high concurrency loads.
```go
package queue_test

import (
	"sync/atomic"
	"testing"
	"time"
)

func TestRetryWorkerFlaky(t *testing.T) {
	var attempts atomic.Int32
	worker := NewWorker(func() error {
		attempts.Add(1)
		return ErrTemporary
	}, 100*time.Millisecond)

	go worker.Start()
	defer worker.Stop()

	// Flaky anti-pattern: arbitrary wall-clock sleep hoping retry completes
	time.Sleep(250 * time.Millisecond)

	if attempts.Load() < 2 {
		t.Fatalf("expected at least 2 attempts, got %d", attempts.Load())
	}
}
```

#### Production Standard (Correct)
> **Standard**: Executes inside synctest.Run where time.Sleep advances synthetic time instantaneously when all bubble goroutines block. synctest.Wait guarantees durable settling without wall-clock latency or race conditions.
```go
package queue_test

import (
	"sync/atomic"
	"testing"
	"testing/synctest"
	"time"
)

func TestRetryWorkerDeterministic(t *testing.T) {
	synctest.Run(func() {
		var attempts atomic.Int32
		worker := NewWorker(func() error {
			attempts.Add(1)
			return ErrTemporary
		}, 100*time.Millisecond)

		stop := make(chan struct{})
		go worker.StartWithContext(stop)
		defer close(stop)

		// Settle initial dispatch
		synctest.Wait()
		if got := attempts.Load(); got != 1 {
			t.Fatalf("initial attempt = %d, want 1", got)
		}

		// Virtual time advances instantly to trigger the 100ms backoff
		time.Sleep(100 * time.Millisecond)
		synctest.Wait()

		if got := attempts.Load(); got != 2 {
			t.Fatalf("retry attempt = %d, want 2", got)
		}
	})
}
```

Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Go Language Server MCP

Provides Go language intelligence, compilation diagnostics, and test execution directly inside the agent loop.

Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Executes package tests with GOEXPERIMENT=synctest enabled and parses structured test failure reports.

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go 1.24 synctest Virtual Clock Concurrency Standard

Go 1.24 synctest Virtual Clock Concurrency Standard defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic testing of concurrent and time-sensitive Go backend code using Go 1.24's testing/synctest package. Prevents test flakiness, wall-clock sleeps, and unbounded async polling by executing goroutine topologies inside isolated synthetic bubbles with instant virtual time advancement. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Relying on arbitrary wall-clock time.Sleep and flaky poll loops for concurrent synchronization Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Relying on arbitrary wall-clock time.Sleep and flaky poll loops for concurrent synchronization	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

1

Engineers MUST ALWAYS encapsulate time-dependent concurrent tests within a synctest.Run(func() { ... }) bubble rather than relying on real-time wall-clock delays.

Engineers MUST ALWAYS encapsulate time-dependent concurrent tests within a synctest.Run(func() { ... }) bubble rather than relying on real-time wall-clock delays.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

2

Engineers MUST invoke synctest.Wait() to assert that all spawned goroutines within the synthetic bubble have settled into a blocked state before validating side effects.

Engineers MUST invoke synctest.Wait() to assert that all spawned goroutines within the synthetic bubble have settled into a blocked state before validating side effects.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

3

Engineers MUST NOT leak background goroutines beyond the lifecycle of synctest.Run

Engineers MUST NOT leak background goroutines beyond the lifecycle of synctest.Run; all goroutines inside a bubble must terminate before the test closure exits.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

4

Code inside a synctest bubble MUST NOT block on synchronization primitives (channels, sync.WaitGroup, sync.Mutex) owned or signaled by goroutines outside the bubble.

Code inside a synctest bubble MUST NOT block on synchronization primitives (channels, sync.WaitGroup, sync.Mutex) owned or signaled by goroutines outside the bubble.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

5

Services verifying retry backoffs, connection heartbeats, and leader election leases MUST assert state at exact virtual time intervals without artificial latency overhead.

Services verifying retry backoffs, connection heartbeats, and leader election leases MUST assert state at exact virtual time intervals without artificial latency overhead.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Go 1.24 synctest Virtual Clock Concurrency Standard critical for AI coding assistants?

Enforces deterministic testing of concurrent and time-sensitive Go backend code using Go 1.24's testing/synctest package. Prevents test flakiness, wall-clock sleeps, and unbounded async polling by executing goroutine topologies inside isolated synthetic bubbles with instant virtual time advancement. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Relying on arbitrary wall-clock time.Sleep and flaky poll loops for concurrent synchronization) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related BACKEND Rules

View all rules →

Fastify 5 Schema Compilers & Encapsulation Production Standard

Fastify relies on lexical encapsulation contexts to sandbox decorators, hooks, and compiled validation/serialization schemas without memory leaks or cross-tenant bleed. In Fastify 5, misuse of global compilers or failing to encapsulate plugin boundaries causes compiled `fast-json-stringify` serializers and Ajv validators to either crash on duplicate IDs, leak private data across sibling scopes, or bypass JIT compilation optimizations. Production services must enforce strict encapsulation hierarchies and type-safe schema compilation across every routing subtree.

Bun Embedded SQLite WAL Mode & Transaction Synchronization Standard

Production database standard for bun:sqlite. Mandates enabling Write-Ahead Logging (PRAGMA journal_mode = WAL), busy timeouts, and using db.transaction() for atomic operations without lock starvation.

Drizzle ORM Batch API & Interactive Transaction Isolation Standard

Production database standard for Drizzle ORM (PostgreSQL & MySQL). Mandates using db.batch() over HTTP drivers to prevent round-trip waterfalls, explicit db.transaction() with serializable/read-committed isolation, and strictly avoids unawaited query promises.

1 Rule in Stack

Go