CLAUDE.md Template: Go (Fiber) + Turso LibSQL + Custom Cookie Session + SQLC Compiler Engine

Overview

CLAUDE.md Template for a Go Fiber API backed by Turso LibSQL with a custom cookie session and an SQLC compiler engine. This page provides a copyable CLAUDE.md block and stack-specific guidance to reproduce a secure, typed Go stack with edge-ready LibSQL storage.

Direct answer: You can paste the included CLAUDE.md block to bootstrap a Go Fiber + Turso LibSQL + SQLC project with cookie-based sessions and a production-ready developer workflow.

When to Use This CLAUDE.md Template

• When building a Go Fiber API using Turso LibSQL as the database and SQLC for typed queries.
• When you require a custom HttpOnly cookie-based session mechanism for authentication.
• When you want a complete, copyable CLAUDE.md template to reproduce the project structure and rules exactly.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code. Produce a complete, executable CLAUDE.md template for a Go Fiber API backed by Turso LibSQL, using SQLC for query compilation, and a custom cookie-based session. The output must be copyable and paste-ready.

Architecture rules:
- Go Fiber API with clear separation: routing, business logic, data access.
- Turso LibSQL as the database layer; access via SQLC-generated queries for type safety.
- Stateless services with a dedicated session manager for cookies.
- Build for a containerized deployment with a small, single-binary app.

File structure rules:
- Place sources under a minimal, stack-focused layout: cmd/app, internal/, sqlc/, db/, migrations/.
- Include sqlc.yaml and an initial set of queries under sqlc/.
- Do not include irrelevant tech stacks; keep Fiber, Turso LibSQL, SQLC, and cookie sessions in scope.

Authentication rules:
- Use a cookie-based session stored in an HttpOnly, Secure, SameSite=Lax cookie.
- Validate the session on protected endpoints by verifying a session payload (user_id) exists in a signed cookie.
- Never expose sensitive session data in API responses.

Database rules:
- Use Turso LibSQL with prepared statements and parameter binding.
- Avoid raw string interpolation in SQL; always bind inputs.
- Do not perform cross-database migrations outside Turso LibSQL migrations.

Validation rules:
- Validate all input payloads with strict types and JSON tags.
- Normalize inputs (trim, canonicalize) before binding to SQL.

Security rules:
- Enforce TLS; disable verbose error details in production.
- Do not log sensitive data (passwords, tokens).
- Sanitize responses to avoid leaking internal identifiers.

Testing rules:
- Unit tests for services and data access; integration tests against a test LibSQL instance.
- Use table-driven tests for SQLC-generated queries.
- Include a simple end-to-end test harness that exercises authentication and a sample endpoint.

Deployment rules:
- Build a small, static Go binary; containerize with a minimal image; use a lightweight entrypoint.
- Configure DB URIs, session keys, and secrets via environment variables.

Things Claude must not do:
- Do not generate code that bypasses authentication.
- Do not embed secrets in code.
- Do not introduce non-deterministic behavior or unsafe pointers.

Recommended Project Structure

go-fiber-turso-libsql-claude/
├── cmd/
│   └── app/
│       └── main.go
├── internal/
│   ├── config/
│   │   └── config.go
│   ├── router/
│   │   └── router.go
│   ├── server/
│   │   └── server.go
│   ├── db/
│   │   ├── turso.go
│   │   └── models.go
│   ├── sessions/
│   │   └── cookie.go
│   └── storage/
│       └── sqlc_queries.go
├── migrations/
│   └── 001_init.sql
├── db/
│   └── schema.sql
├── sqlc/
│   ├── sqlc.yaml
│   └── queries.sql
└── go.mod

Core Engineering Principles

• Type safety: SQLC provides compile-time type safety for DB queries.
• Clear separation of concerns: routing, business logic, and data access are modular.
• Security by design: HttpOnly cookies, TLS, and sanitized outputs.
• Reproducibility: CLAUDE.md blocks enable consistent project replication.
• Observability: structured logging and minimal, deterministic behavior.

Code Construction Rules

• Use Go 1.20+ and the Fiber web framework; keep dependencies scoped to the stack.
• Generate and commit SQLC query scaffolding; run sqlc generate during development and CI.
• Store session data in a signed, HttpOnly cookie; validate on protected routes.
• Bind all user inputs to SQL parameters; avoid string interpolation in SQL.
• Organize code with cmd/app for the entrypoint and internal/* packages for modules.
• Keep migrations in migrations/ and reflect them in startup logic prior to accepting requests.

Security and Production Rules

• Enable TLS and enforce Secure, HttpOnly cookies with SameSite=Lax.
• Do not log sensitive payloads; mask secrets in logs.
• Protect against CSRF in write endpoints via token checks or cookie-based mitigations.
• Rotate API keys and database credentials; store them in environment variables or secret managers.

Testing Checklist

• Unit tests for services and data access layers; mock the DB where appropriate.
• Integration tests exercising SQLC-generated queries against a test LibSQL instance.
• End-to-end tests for authentication flow and a sample protected endpoint.
• CI should run sqlc generate, go test ./..., and a lightweight integration test against a test DB.

Common Mistakes to Avoid

• Skipping SQL parameter binding and interpolating user input in SQL.
• Storing large session payloads in cookies; keep only essential identifiers.
• Using non-deterministic defaults for timeouts or session lifetimes.
• Deploying without migrations in production or hot-reloading schemas during runtime.

FAQ