CLAUDE.md

1# CLAUDE.md for humanlog
2 
3Essential guide for AI coding agents working on the `humanlog` Go project.
4 
5## Project Overview
6 
7`humanlog` is a Go package that provides a human-readable formatter for Go's `log/slog` output. It implements the `slog.Handler` interface to format logs with fixed-width messages, colored levels, and structured attributes.
8 
9**Core Architecture:**
10- `handler.go`: Main `Handler` type implementing `slog.Handler` with custom formatting (234 lines)
11- `options.go`: `Options` struct for handler configuration 
12- `humanlog.go`: Entry point `NewHandler()` function with nil writer panic contract
13- `example/main.go`: Comprehensive usage patterns and API demonstration
14 
15**Key Design Patterns:**
16- Fixed-width message formatting (40 chars) with truncation/padding in `handler.go:57-64`
17- No global state - all configuration via `Options` struct or method parameters
18- Immutable handler creation via `WithAttrs()` and `WithGroup()` methods
19- Structured attribute grouping with dot notation (e.g., `request.method=GET`)
20 
21## Developer Workflows
22 
23**Build & Test Commands:**
24- **Primary**: `task build` - runs tests, linting, and formatting (`goimports -w .`)
25- **Fallback**: Standard Go tools (`go test ./...`, `go build`) if no Taskfile exists
26- **Example**: `go run example/main.go` to see formatted output
27- **Analysis**: `go run llm-shared/utils/gofuncs/gofuncs.go -dir .` for function listing
28 
29**Task Completion Criteria:**
30- Must run `gofmt -w` on changed Go files before build attempts
31- Task incomplete until `task build` succeeds
32- Basic unit tests required (see `handler_test.go` for patterns)
33 
34## Project-Specific Conventions
35 
36**Handler Contract:**
37- `NewHandler(nil, opts)` panics - enforced in `humanlog.go:16-18`
38- All exported functions require doc comments
39- Message width fixed at 40 characters with ellipsis truncation
40- Color output enabled by default unless `DisableColor: true`
41 
42**Attribute Formatting:**
43- Strings with spaces/special chars are quoted: `key="value with spaces"`
44- Time values use RFC3339 format
45- Error values are quoted: `error="connection refused"`
46- Go keywords (`true`, `false`, `nil`) are quoted when used as string values
47 
48**Testing Patterns:**
49- Use `bytes.Buffer` for output capture in tests
50- Set `DisableColor: true` for predictable test assertions
51- Test both grouped and ungrouped attribute scenarios
52- Cover time formatting and attribute quoting edge cases
53 
54## Integration Points
55 
56**slog Integration:**
57- Implements `slog.Handler` interface (Enable, Handle, WithAttrs, WithGroup)
58- Uses embedded `slog.TextHandler` for level filtering and source location
59- Compatible with `slog.SetDefault()` for global logger replacement
60 
61**Dependencies:**
62- Standard library only (no external dependencies in `go.mod`)
63- Go 1.24.5+ required
64- Module path: `github.com/lepinkainen/humanlog`
65 
66## Development Guidelines
67 
68**Code Quality:**
69- Follow `llm-shared/` conventions for build, lint, and test standards
70- Prefer standard library over third-party dependencies
71- Use `llm-shared/utils/validate-docs/` to verify project structure
72- Reference `llm-shared/templates/` for CI, gitignore, and build templates
73 
74**Formatting Examples:**
75```
76[15:04:05] INFO  User logged in successfully        user_id=123 session="abc-def" request.ip=192.168.1.1
77[15:04:05] ERROR Connection failed                  error="timeout after 30s" retries=3 source=main.go:42
78```