Go Cursor Rules Template

Returning an error unchanged preserves its chain but adds no information about the operation that failed. When callers need that context, fmt.Errorf("load configuration: %w", err) can add it while preserving the wrapped error for inspection. Choose wrapping deliberately at package boundaries because callers can depend on errors exposed through the chain.

The %w verb matters as much as the message. Wrapping with %v (or building strings by hand) produces an error that looks fine in logs but breaks errors.Is and errors.As, which is why the rules pair the two: wrap with %w on the way up, inspect with errors.Is/errors.As at the decision point. Without that pairing, Cursor falls back to the pattern it sees everywhere in older training data — strings.Contains(err.Error(), "not found") — a comparison that shatters the moment anyone rewords an error message. Defining custom error types with an Error() method gives errors.As a concrete target for the cases where callers need structured data, not just a sentinel.

Goroutine leaks are the signature failure of AI-written Go. Cursor loves to write `go func() { ... }()` — it looks idiomatic and concurrent — but routinely omits the two things that let that goroutine ever stop: a context.Context to observe cancellation, and a sync.WaitGroup (or errgroup) so the caller knows when work is done. A leaked goroutine costs nothing in tests, then accumulates in production until the process is holding thousands of blocked stacks and open connections. Nothing crashes; memory just climbs.

The concurrency rules attack this at generation time. Requiring context.Context for cancellation and deadline propagation means generated worker functions take ctx as their first parameter and select on ctx.Done() instead of blocking forever. Requiring WaitGroup for completion means "fire and forget" has to be a deliberate choice, not the default shape. And the "prefer channels over mutexes for communication" rule steers Cursor away from its other bad habit: guarding a shared slice with a mutex and hand-rolled signaling where a channel would make ownership obvious. The testing section closes the loop by mandating -race, which turns the data races these mistakes cause into loud test failures instead of once-a-month production mysteries.

Go does not require one directory skeleton for every project. A small module can start with its package or command in the root. For multiple commands, cmd/ separates entry points; internal/ restricts imports to the directory tree rooted at its parent. The template asks Cursor to preserve the existing structure and introduce these directories when useful, without adding pkg/ as a mandatory layer.

The naming rules do double duty here. camelCase for unexported and PascalCase for exported identifiers is not just style — in Go, capitalization is the visibility system. When Cursor generates a helper as PascalCase out of habit, it has silently widened your public API. Making the convention explicit keeps generated identifiers unexported until someone decides otherwise.

Ask Cursor for tests without guidance and you get a stack of near-identical functions — TestParseValid, TestParseEmpty, TestParseUnicode — each repeating the same setup with one value changed. That shape is uniquely bad for AI-assisted work: when you later ask Cursor to add a case, it clones another whole function; when behavior changes, it must edit five functions consistently and usually edits four. A table-driven test with t.Run subtests inverts this — adding a case is appending one struct literal, which is the kind of edit Cursor performs almost perfectly.

The supporting rules are small but load-bearing. t.Helper() keeps failure line numbers pointing at the failing case instead of inside a shared assertion helper; t.TempDir() removes the hand-rolled cleanup code Cursor otherwise invents; and testify is permitted where it genuinely improves readability rather than mandated everywhere, so generated tests still read like Go rather than a ported JUnit suite.