Skip to main content
Go Microservices & Clean ArchitecturebackendTarget: Go 1.22+ / 1.23+

Go Microservices & Clean Architecture AI Agent Rules & Cursorrules

Enforce idiomatic Go concurrency, context propagation, and zero goroutine leaks.

Prevent AI models from generating Java-like Go code or introducing silent goroutine leaks. Enforce idiomatic error handling, context propagation, and clean architectural boundaries.

#go cursorrules#golang cursor rules#golang claude md#go microservices agent rules#cursor rules for golang

Configuration Workbench

Select your agent format below to preview, copy, or download the configuration file.

Cursor configuration for Go microservices.
10 lines•0.6 KB
# Go Microservices Cursor Rules

You are a Principal Go Systems Architect.

## Core Rules
- Language: Go 1.22+. Use standard library 'slog' for structured logging.
- Concurrency: Never start a goroutine without knowing how and when it will stop. Listen to 'ctx.Done()'.
- Context: 'ctx context.Context' must be the first parameter in all blocking/I/O functions.
- Error Handling: Handle errors immediately; never ignore returned errors. Use 'fmt.Errorf("...: %w", err)' for wrapping.
- Interfaces: Define interfaces where they are consumed, not where they are implemented. Keep interfaces small (1-2 methods).

Pro-tip: Place this file directly in the root directory of your Go Microservices & Clean Architecture project. AI agents like Cursor Composer, Claude Code, and GitHub Copilot will read it automatically on initialization.

Architectural Principles Enforced

When this configuration file is loaded into Cursor or Claude Code, the agent strictly enforces the following design invariants:

Always propagate `context.Context` as the first argument in all I/O, database, and network functions.

Check `errors.Is` and `errors.As` instead of comparing string error values.

Ensure all spawned goroutines have an exit condition to prevent memory leaks.

Use `slog` for modern structured JSON logging.

Favor small, single-method interfaces declared at the consumer site rather than producer site.

Installation & Repository Setup

Place in project root as `.cursorrules` or `CLAUDE.md`.

1Copy `.cursorrules` to your Go repository root.
2Ensure `golangci-lint` passes on your project.

Verified Agent Behavior Examples

Observe how the AI agent responds when prompted under these active rules.

Scenario: Handling concurrent worker pools
User prompt: “Write a worker pool processing jobs with graceful shutdown.”
Agent Behavior: The agent uses `sync.WaitGroup`, listens for `ctx.Done()`, drains the job channel, and exits cleanly without deadlocks or leaked goroutines.

Frequently Asked Questions

Why should interfaces be declared by consumers in Go?

Declaring interfaces where they are used (consumer side) decouples packages, avoids unnecessary package dependencies, and makes mocking straightforward in tests.