Skip to content

CLAUDE.md

Latest commit

 

History

History
197 lines (145 loc) · 6.94 KB

CLAUDE.md

File metadata and controls

197 lines (145 loc) · 6.94 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

go-logger is a lightweight Go library that wraps zerolog with automatic log rotation via lumberjack. It's designed as a reusable package, not a standalone application.

Architecture

Core Components

  • logger.go: Main library implementation
    • Logger struct: Wraps zerolog.Logger to provide enhanced functionality
    • Config struct: Configuration for log level, directory, filename, rotation settings, and console output
    • New(): Factory function that creates a logger with multi-writer support (file + optional console)
    • Context methods: WithField(), WithFields(), WithError() - all return new logger instances preserving immutability

Key Design Patterns

  1. Wrapper Pattern: The Logger struct embeds zerolog.Logger, inheriting all its methods while adding custom functionality
  2. Immutability: Context methods (WithField, WithFields, WithError) create new logger instances rather than modifying the original
  3. Multi-Writer: Logs can be written to both file and console simultaneously using io.MultiWriter
  4. Graceful Fallback: If log directory creation fails, the logger falls back to stderr instead of failing

Log Rotation Behavior

  • Log files are written to {LogDir}/{Filename} (default: ./logs/go.log)
  • Automatic rotation when file reaches MaxSizeMB (default: 10MB)
  • Keeps MaxBackups old files (default: 5)
  • Automatically deletes logs older than 30 days (hardcoded in logger.go:86)
  • Old logs are NOT compressed (Compress: false in logger.go:87)

Claude Code Extensions

This project includes specialized Claude Code agents and commands for Go development. Some are shared via a git submodule from claude-code-support-tools.

Submodule Setup

Shared tools are located in .claude/shared/ as a git submodule. When cloning:

# Clone with submodules
git clone --recurse-submodules <repo-url>

# Or initialize after clone
git submodule update --init --recursive

To update the submodule to latest:

git submodule update --remote .claude/shared
git add .claude/shared
git commit -m "Update claude-code-support-tools submodule"

Agents

Invoke agents with @agent-name in your message:

  • @go-test-runner - Run tests, analyze coverage, debug failures, write new tests
  • @go-code-quality - Run linters/formatters, fix code quality issues, enforce best practices
  • @go-dependency-manager - Update dependencies, check for vulnerabilities, manage versions
  • @security-auditor - Comprehensive security audits, vulnerability assessments, CVE analysis (shared)
  • @project-architect - Analyze project and generate tailored Claude Code agents/commands (shared)
  • @code-quality-auditor - Scan for code quality issues and fix warnings

Slash Commands

Quick commands for common workflows:

  • /test - Run all tests with verbose output
  • /test-coverage - Generate coverage report and HTML visualization
  • /test-race - Run tests with race detector
  • /lint - Check code quality with gofmt, go vet, and golangci-lint
  • /fmt - Format all Go files with gofmt
  • /mod-tidy - Clean up go.mod and verify dependencies
  • /deps-update - Check for and update dependencies
  • /benchmark - Run performance benchmarks
  • /security-audit - Comprehensive security audit with govulncheck and CVE analysis
  • /commit-prepare - Review changes and prepare a commit message
  • /commit-do - Create a git commit with the prepared message (shared)
  • /setup-project-tools - Generate tailored Claude Code agents/commands for this project (shared)

Development Commands

Testing

# Run all tests
go test -v

# Run tests with coverage
go test -cover

# Generate coverage report
go test -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html

# Run with race detection
go test -race -v

# Run a specific test
go test -v -run TestNew

# Run tests matching a pattern
go test -v -run TestWith

Building

# Build the module (verify compilation)
go build

# Download/update dependencies
go mod download

# Tidy dependencies
go mod tidy

# Verify dependencies
go mod verify

Code Quality

# Format code
go fmt ./...

# Run static analysis
go vet ./...

# Run golangci-lint (if installed)
golangci-lint run

Security Auditing

# Run comprehensive security audit
# Uses govulncheck and generates reports in .audit/ directory
govulncheck ./...

# Check dependencies for vulnerabilities
go list -m all | grep -v "go-logger"

Security Audit Reports: Generated by the /security-audit command or @security-auditor agent. All reports are saved to .audit/ directory (gitignored) and include:

  • Application code security analysis
  • Dependency CVE scanning
  • Configuration security review
  • Executive summary with prioritized remediation

CI/CD

This project uses GitHub Actions for automated checks:

  • CodeQL: Runs on push/PR to master, plus weekly schedule
  • Dependency Review: Runs on PRs to detect vulnerable dependencies

Testing Philosophy

Tests use t.TempDir() to create isolated temporary directories for each test case, ensuring no test pollution. The test suite covers:

  • Configuration defaults and validation
  • Log level parsing (case-insensitive, handles "warn"/"warning")
  • File and directory creation (including nested directories)
  • Multi-writer scenarios (file + console)
  • Context preservation (WithField/WithFields/WithError return new instances)
  • Fallback behavior when directory creation fails

Configuration Defaults

When creating a logger, these defaults apply:

  • Level: "info" if empty or unrecognized
  • LogDir: "./logs" if empty
  • Filename: "go.log" if empty
  • MaxSizeMB: 10 if zero
  • MaxBackups: 5 if zero
  • Console: false by default
  • DirMode: 0750 if zero
  • DisableCaller: false by default (caller info included)
  • MaxAge: 30 days (hardcoded, not configurable)

Important Implementation Details

  1. Per-Instance Level: New() sets the log level per logger instance via .Level() — no global state pollution
  2. Caller Information: Optional, controlled by DisableCaller config field (logger.go:114). Enabled by default for debugging; disable for privacy/security
  3. Timestamp Format: File logs use Unix timestamp; console uses "2006-01-02 15:04:05" format
  4. No Compression: Log rotation doesn't compress old files (set Compress: false)
  5. Close(): Closes the underlying file writer to flush buffered logs (logger.go:154-159). Always call Close() when done

Dependencies

  • Go 1.25.6
  • github.com/rs/zerolog v1.35.0 - Zero-allocation JSON logger
  • gopkg.in/natefinch/lumberjack.v2 v2.2.1 - Log file rotation

License

MIT License - Copyright (c) 2025 Oleg Ivanchenko