Go Microservice Kit with Zap and Prometheus — Cursor Rules Template

Overview

The Cursor rules configuration for Go microservices with Zap logging and Prometheus metrics provides a ready-to-paste .cursorrules template that configures Cursor AI to follow production-grade patterns for a Go-based microservice stack. It covers logging, metrics, tracing-ready structure, and safe AI-assisted development for this stack. Direct answer: use this Cursor Rules Template to consistently produce Go microservices with observable metrics and structured logging, guided by Cursor AI rules.

When to Use These Cursor Rules

• When building new Go microservices that expose REST APIs or gRPC endpoints and require structured logging (Zap) and metrics (Prometheus).
• When you want Cursor AI to enforce a clean architecture with Go module layout and a recommended project structure.
• When you need consistent authentication patterns (JWT/mTLS) and security guardrails across services.
• When you integrate tests and linting into CI/CD pipelines using GitHub Actions or similar tooling.
• When you want to avoid anti-patterns like global state, unsafe reflection, or direct SQL string concatenation.

Copyable .cursorrules Configuration

# Cursor Rules for Go Microservice with Zap & Prometheus
framework: go
stack: go-microservice
template: cursor-rules
version: 1.0

# Framework Role & Context
role: "Produce production-grade Go microservices with Zap logging and Prometheus metrics. Follow Clean Architecture, REST via net/http, and safe AI-assisted development patterns."

# Code Style and Style Guides
style: "gofmt, golangci-lint, error wrapping with fmt.Errorf/%w, use of errors.Is"

# Architecture & Directory Rules
architecture: "Conforms to Go clean architecture: cmd/app, internal/app, internal/persistence, pkg/, configs, deploy"

# Authentication & Security Rules
security: "JWT-based authentication (RS256), token validation, no logging of sensitive payloads; mTLS in Kubernetes environments"

# Database and ORM patterns
db: "database/sql with pgx driver; repository pattern; parameterized queries; prepared statements; migrations via migrate"

# Testing & Linting Workflows
testing: "unit tests with go test ./...; integration tests in ./internal; CI with GitHub Actions; code coverage goals"

# Prohibited Actions and Anti-patterns for the AI
prohibited: "do not log secrets; do not bypass tests; do not rely on global mutable state; avoid unsafe reflection; avoid string-concatenated SQL"

Recommended Project Structure

.
├── cmd/
│   └── service/
│       └── main.go
├── internal/
│   ├── app/
│   │   ├── handlers/
│   │   └── usecase/
│   ├── domain/
│   └── persistence/
│       ├── repository/
│       └── migrations/
├── pkg/
│   ├── config/
│   ├── logging/
│   └── metrics/
├── configs/
├── deploy/
├── go.mod
├── go.sum

Core Engineering Principles

• Adopt a clean architecture with clear boundaries between transport, use-cases, and persistence layers.
• Use Go modules and semantic versioning; minimize dependencies; prefer standard library where practical.
• Ensure observable behavior with Zap-based logging and Prometheus metrics; guard against leaking sensitive data in logs.
• Idempotent deployment and reliable rollbacks; deterministic builds; reproducible environments.
• Automate tests, linting, and security checks in CI/CD; require test coverage and fail on critical issues.

Code Construction Rules

• Follow Go formatting (gofmt) and linting (golangci-lint).
• Structure code by domain, not by feature; prefer dependency injection for testability.
• Use the repository pattern for data access; parameterize SQL queries to prevent injection.
• Expose metrics on a /metrics endpoint; export common Prometheus metrics (requests_total, request_duration_seconds).
• Handle errors with proper wrapping and context; avoid leaking internal error details to clients.
• Do not instantiate global state for config; load from environment/config files during startup.

Security and Production Rules

• Require JWT-based authentication for protected endpoints; validate claims and expiry; avoid logging sensitive tokens.
• Use mTLS for service-to-service calls in Kubernetes; enforce TLS; rotate credentials regularly.
• Store secrets in a dedicated vault or environment-specific configs; never commit credentials to VCS.
• Enable structured logging with correlation IDs; redact PII and sensitive data from logs.
• Audit dependencies for known vulnerabilities; run dependency scans in CI.

Testing Checklist

• Unit tests for all handlers and use-cases; aim for high coupling decoupling and testability.
• Integration tests covering database access and external adapters with mocks or test doubles.
• End-to-end tests simulating request flows; verify metrics and logs are emitted as expected.
• CI checks: go fmt, go vet, staticcheck, and test coverage thresholds.
• Deployment validation: smoke tests post-deploy and health checks.

Common Mistakes to Avoid

• Coupling transport to domain; ignore clean architecture boundaries.
• Hard-coding secrets or configs; neglecting environment-based configuration.
• Neglecting metrics exposure or logging to the wrong verbosity level in production.
• Skipping tests or relying on flaky mocks for critical paths.
• Over-optimizing for performance prematurely, causing complex and brittle code.

FAQ

What is the Cursor Rules Template for Go microservices?

This template provides a ready-to-paste .cursorrules configuration for a Go microservice stack with Zap logging and Prometheus metrics, along with architecture and security guidelines to guide Cursor AI.

Which folders should I mirror in my Go project?

Use cmd/, internal/, pkg/, configs/, and deploy/ to reflect a clean Go microservice layout suitable for production, as shown in the recommended project structure.

How does this template handle authentication?

The rules prescribe JWT-based auth with RS256, token validation, and no logging of token values; mTLS in Kubernetes is recommended for service-to-service calls to enhance security.

How do I validate Prometheus metrics exposure?

Expose /metrics from your service using the Prometheus client and ensure metrics are scrappable by the Prometheus server; include useful counters and histograms for request metrics.

Can I adapt this template to a gRPC service?

Yes. The Cursor Rules Template is stack-aware; you can adjust the transport layer to gRPC while preserving logging, metrics, and security patterns, ensuring consistent architecture and observability across you services.