| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 4 | 2 | 2 | 50% |
| Commands | 5 | 0 | 1 | 83% |
| Section tags | 5 | 1 | 1 | 71% |
What each file covers
Sections
4 shared · 2 only in A · 2 only in B- − GEMINI.md for humanlog
- − General AI Agent Guidance
- + CLAUDE.md for humanlog
- + Development Guidelines
- Project Overview
- Developer Workflows
- Project-Specific Conventions
- Integration Points
Commands
5 shared · 0 only in A · 1 only in B- + go.mod
- task build
- go test
- go build
- go run example/main.go
- go run llm-shared/utils/gofuncs/gofuncs.go -dir .
Section tags
5 shared · 1 only in A · 1 only in B- − testing-strategy
- + lint-format
- build
- test
- code-style
- architecture
- agent-behaviour
Line diff
lepinkainen/humanlog · GEMINI.md
@@ −1 @@
1# GEMINI.md for humanlog
2
3This document provides essential guidelines for AI 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 `log/slog` output.
8- **Core Components**:
9 - `handler.go`: Implements the custom `slog.Handler` for formatting.
10 - `options.go`: Defines configuration options for the handler.
11 - `humanlog.go`: Entry point for creating new `humanlog` handlers.
12- **Example Usage**: Refer to `example/main.go` for idiomatic usage patterns.
13
14## Developer Workflows
15
16- **Build, Test, Lint**: Always use `task build`. This command orchestrates testing (`go test ./...`), linting, and formatting (`goimports -w .`).
17 - **Do NOT** use `go build` or `go test` directly for general tasks, as `task build` ensures all quality checks are performed.
18- **Run Example**: To see the formatted log output, execute `go run example/main.go`.
19- **Function Analysis**: Use `go run llm-shared/utils/gofuncs/gofuncs.go -dir .` to list functions in the project.
20
21## Project-Specific Conventions
22
23- **Configuration**: All handler configuration is managed via the `Options` struct in `options.go`. No global state is used.
24- **Writer Contract**: `humanlog.NewHandler` panics if a `nil` `io.Writer` is provided.
25- **Documentation**: All exported types and functions must have doc comments.
26- **Formatting**: Log messages are padded/truncated to a fixed width (`messageWidth` in `handler.go`). Color output is enabled by default.
27- **Dependencies**: The project prioritizes the Go standard library and `log/slog`. Avoid adding new third-party dependencies without strong justification.
28
29## Integration Points
30
31- `humanlog` integrates directly with Go's standard `log/slog` package by implementing the `slog.Handler` interface.
32
33## General AI Agent Guidance
34
35- **Task Completion**: A task is not complete until `task build` succeeds and basic unit tests are in place.
36- **Code Formatting**: Always run `goimports -w .` on Go code files after making changes.
37- **Testing**: Focus on testing critical parts of the code; 100% test coverage is not required.
38- **CI/CD**: Refer to `llm-shared/templates/github/workflows/go-ci.yml` for CI setup.
39- **Git**: Keep `.gitignore` updated using `llm-shared/templates/gitignore-go` as a reference.
40
lepinkainen/humanlog · CLAUDE.md
@@ +1 @@
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```
@@ −1 +1 @@
1−# GEMINI.md for humanlog
1+# CLAUDE.md for humanlog
22
3−This document provides essential guidelines for AI agents working on the `humanlog` Go project.
3+Essential guide for AI coding agents working on the `humanlog` Go project.
44
55 ## Project Overview
66
7−`humanlog` is a Go package that provides a human-readable formatter for `log/slog` output.
8−- **Core Components**:
9− - `handler.go`: Implements the custom `slog.Handler` for formatting.
10− - `options.go`: Defines configuration options for the handler.
11− - `humanlog.go`: Entry point for creating new `humanlog` handlers.
12−- **Example Usage**: Refer to `example/main.go` for idiomatic usage patterns.
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.
138
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+
1421 ## Developer Workflows
1522
16−- **Build, Test, Lint**: Always use `task build`. This command orchestrates testing (`go test ./...`), linting, and formatting (`goimports -w .`).
17− - **Do NOT** use `go build` or `go test` directly for general tasks, as `task build` ensures all quality checks are performed.
18−- **Run Example**: To see the formatted log output, execute `go run example/main.go`.
19−- **Function Analysis**: Use `go run llm-shared/utils/gofuncs/gofuncs.go -dir .` to list functions in the project.
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
2028
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+
2134 ## Project-Specific Conventions
2235
23−- **Configuration**: All handler configuration is managed via the `Options` struct in `options.go`. No global state is used.
24−- **Writer Contract**: `humanlog.NewHandler` panics if a `nil` `io.Writer` is provided.
25−- **Documentation**: All exported types and functions must have doc comments.
26−- **Formatting**: Log messages are padded/truncated to a fixed width (`messageWidth` in `handler.go`). Color output is enabled by default.
27−- **Dependencies**: The project prioritizes the Go standard library and `log/slog`. Avoid adding new third-party dependencies without strong justification.
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`
2841
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+
2954 ## Integration Points
3055
31−- `humanlog` integrates directly with Go's standard `log/slog` package by implementing the `slog.Handler` interface.
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
3260
33−## General AI Agent Guidance
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`
3465
35−- **Task Completion**: A task is not complete until `task build` succeeds and basic unit tests are in place.
36−- **Code Formatting**: Always run `goimports -w .` on Go code files after making changes.
37−- **Testing**: Focus on testing critical parts of the code; 100% test coverage is not required.
38−- **CI/CD**: Refer to `llm-shared/templates/github/workflows/go-ci.yml` for CI setup.
39−- **Git**: Keep `.gitignore` updated using `llm-shared/templates/gitignore-go` as a reference.
66+## Development Guidelines
4067
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+```
