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.

Go Microservice Kit with Zap and Prometheus — Cursor Rules Template

Target User

Use Cases