| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 2 | 21 | 4 | 7% |
| Commands | 5 | 8 | 1 | 36% |
| Section tags | 6 | 6 | 0 | 50% |
What each file covers
Sections
2 shared · 21 only in A · 4 only in B- − Humanlog Project Rules
- − Shared Guidelines Reference
- − Project Management & Build Requirements
- − Task Completion Criteria
- − Build System Requirements
- − Project Validation
- − Go-Specific Guidelines
- − Code Formatting & Quality
- − Library Preferences
- − Function Analysis
- − Project-Specific Rules for `humanlog`
- − Overview & Architecture
- − Integration & Dependencies
- − Patterns & Examples
- − Development Workflow
- − Code Analysis
- − CI/CD Requirements
- − Git Management
- − Templates & References
- − Available Templates
- − Project Structure
- + CLAUDE.md for humanlog
- + Project Overview
- + Integration Points
- + Development Guidelines
- Developer Workflows
- Project-Specific Conventions
Commands
5 shared · 8 only in A · 1 only in B- − go run llm-shared/utils/validate-docs/validate-docs.go
- − go run llm-shared/utils/gofuncs/gofuncs.go -dir /path/to/project
- − task test
- − task lint
- − go fmt ./...
- − go vet ./...
- − go install
- − go test -tags=ci -cover -v ./...
- + go run llm-shared/utils/gofuncs/gofuncs.go -dir .
- task build
- go build
- go test ./...
- go run example/main.go
- go.mod
Section tags
6 shared · 6 only in A · 0 only in B- − setup
- − testing-strategy
- − git-pr
- − dependencies
- − deployment
- − do-not
- build
- test
- lint-format
- code-style
- architecture
- agent-behaviour
Line diff
lepinkainen/humanlog · .clinerules/project-rules.md
@@ −1 @@
1# Humanlog Project Rules
2
3## Shared Guidelines Reference
4
5**This project follows the shared LLM assistant guidelines in [`llm-shared/`](../llm-shared/):**
6
7- **[`llm-shared/project_tech_stack.md`](../llm-shared/project_tech_stack.md)**: Project management, validation, build/test/lint workflows, and universal conventions for all projects.
8- **[`llm-shared/languages/go.md`](../llm-shared/languages/go.md)**: Go-specific best practices, library choices, and code formatting/testing standards.
9- **[`llm-shared/utils/`](../llm-shared/utils/)**: Tools for code analysis and validation (e.g., `gofuncs`, `validate-docs`).
10- **[`llm-shared/templates/`](../llm-shared/templates/)**: Example `.gitignore`, `Taskfile.yml`, and CI workflow templates.
11
12> **Always consult the above files for baseline rules. This file documents project-specific conventions and architectural notes for `humanlog`.**
13
14---
15
16## Project Management & Build Requirements
17
18### Task Completion Criteria
19
20- Task is not complete until `task build` succeeds, which includes:
21 - Running tests (`task test`)
22 - Linting the code (`task lint`)
23 - Building the project (if applicable)
24- Task is not complete until it has even basic unit tests, even if they are not comprehensive
25 - No need to mock external dependencies, just test the logic of the code
26- When working from a markdown checklist of tasks, check off the tasks as you complete them
27
28### Build System Requirements
29
30- Use `task build` over `go build` to ensure all tasks are run
31- All build artifacts should be placed in the `build/` directory
32- Build tasks must depend on test and lint tasks
33- Reference `llm-shared/templates/Taskfile.yml` for comprehensive task structure
34
35### Project Validation
36
37- Use the `validate-docs` tool to check if projects follow standard structure conventions:
38 ```bash
39 go run llm-shared/utils/validate-docs/validate-docs.go
40 ```
41
42---
43
44## Go-Specific Guidelines
45
46### Code Formatting & Quality
47
48- Always run `gofmt -w .` on Go code files after making changes
49- Use `go fmt ./...` and `go vet ./...` for linting
50- Functions that are easily unit-testable should have tests
51- Don't go for 100% test coverage, test the critical parts of the code
52
53### Library Preferences
54
55- Prefer using standard library packages when possible
56- Provide justification when adding new third-party dependencies
57- Keep dependencies updated
58- If SQLite is used, use "modernc.org/sqlite" as the library (no dependency on cgo)
59- Logging in applications run from cron: "log/slog" (standard library)
60- Logging in applications run from CLI: "fmt.Println" (standard library, use emojis for better UX)
61- Configuration management: "github.com/spf13/viper"
62- Command-line arguments: "github.com/alecthomas/kong" (only if the project requires complex CLI)
63
64### Function Analysis
65
66- When looking for functions, use the `gofuncs` tool to list all functions in a Go project:
67 ```bash
68 go run llm-shared/utils/gofuncs/gofuncs.go -dir /path/to/project
69 ```
70
71---
72
73## Project-Specific Rules for `humanlog`
74
75### Overview & Architecture
76
77- This package provides a human-readable formatter for Go's `log/slog` output.
78- Main components:
79 - `Handler` (`handler.go`): Implements `slog.Handler` with custom formatting.
80 - `Options` (`options.go`): Configures handler behavior.
81 - `NewHandler` (`humanlog.go`): Entry point for handler creation.
82- Example usage: `example/main.go`. Tests: `handler_test.go`.
83
84### Developer Workflows
85
86- **Build**: Use `task build` (or standard Go tools `go build`, `go install` if no Taskfile exists yet).
87- **Test**: `go test ./...` (see `handler_test.go`).
88- **Example**: `go run example/main.go` to see formatted log output.
89
90### Project-Specific Conventions
91
92- No global state; all config via `Options` or method params.
93- `NewHandler` panics if given a nil writer (enforced contract).
94- All exported types/functions must have doc comments.
95- Formatting helpers are unexported and colocated with usage.
96- Log messages are padded/truncated to a fixed width (see `messageWidth` in `handler.go`).
97- Color output for log levels unless `DisableColor` is set.
98
99### Integration & Dependencies
100
101- Only standard library and `log/slog` are used (following the minimal dependency principle).
102- Go module path: `github.com/lepinkainen/humanlog` (see `go.mod`).
103- When doing HTTP requests, use a custom user agent that includes the project name and version, e.g. `humanlog/1.0.0`
104
105### Patterns & Examples
106
107- See `example/main.go` for idiomatic usage patterns.
108- See `handler_test.go` for test structure and coverage.
109
110---
111
112## Development Workflow
113
114### Code Analysis
115
116- When analyzing large codebases that might exceed context limits, use the Gemini CLI:
117 ```bash
118 gemini -p "@src/main.go Explain this file's purpose and functionality"
119 gemini -p "@src/ Summarise the architecture of this codebase"
120 gemini -p "@src/ Is the project test coverage on par with industry standards?"
121 ```
122
123### CI/CD Requirements
124
125- Projects should have a basic GitHub Actions setup that uses the build-ci task
126- Use `llm-shared/templates/github/workflows/go-ci.yml` as a template
127- CI should run tests and linting on push and pull requests
128- Use `go test -tags=ci -cover -v ./...` for CI tests
129- Allow skipping tests with `//go:build !ci`
130
131### Git Management
132
133- Keep `.gitignore` up to date with Go-specific ignores
134- Use `llm-shared/templates/gitignore-go` as a reference
135- Ensure build artifacts and temporary files are not committed
136
137---
138
139## Templates & References
140
141### Available Templates
142
143- **Taskfile**: `llm-shared/templates/Taskfile.yml` - Comprehensive task management
144- **CI Workflow**: `llm-shared/templates/github/workflows/go-ci.yml` - GitHub Actions for Go
145- **Gitignore**: `llm-shared/templates/gitignore-go` - Go-specific ignore patterns
146- **Documentation**: `llm-shared/templates/README.md` and `llm-shared/templates/CHANGELOG.md`
147
148### Project Structure
149
150This project follows a simple Go library structure:
151
152```
153humanlog/
154├── go.mod # Go module definition
155├── *.go # Main library files (handler.go, options.go, humanlog.go)
156├── *_test.go # Test files
157├── example/ # Usage examples
158├── llm-shared/ # Shared development guidelines (submodule)
159├── docs/ # Project documentation (if needed)
160└── build/ # Build artifacts (when using Taskfile)
161```
162
163---
164
165_If any section is unclear or missing important project-specific details, please provide feedback or point to additional documentation to improve these rules._
166
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−# Humanlog Project Rules
1+# CLAUDE.md for humanlog
22
3−## Shared Guidelines Reference
3+Essential guide for AI coding agents working on the `humanlog` Go project.
44
5−**This project follows the shared LLM assistant guidelines in [`llm-shared/`](../llm-shared/):**
5+## Project Overview
66
7−- **[`llm-shared/project_tech_stack.md`](../llm-shared/project_tech_stack.md)**: Project management, validation, build/test/lint workflows, and universal conventions for all projects.
8−- **[`llm-shared/languages/go.md`](../llm-shared/languages/go.md)**: Go-specific best practices, library choices, and code formatting/testing standards.
9−- **[`llm-shared/utils/`](../llm-shared/utils/)**: Tools for code analysis and validation (e.g., `gofuncs`, `validate-docs`).
10−- **[`llm-shared/templates/`](../llm-shared/templates/)**: Example `.gitignore`, `Taskfile.yml`, and CI workflow templates.
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.
118
12−> **Always consult the above files for baseline rules. This file documents project-specific conventions and architectural notes for `humanlog`.**
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
1314
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`)
1520
16−## Project Management & Build Requirements
21+## Developer Workflows
1722
18−### Task Completion Criteria
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
1928
20−- Task is not complete until `task build` succeeds, which includes:
21− - Running tests (`task test`)
22− - Linting the code (`task lint`)
23− - Building the project (if applicable)
24−- Task is not complete until it has even basic unit tests, even if they are not comprehensive
25− - No need to mock external dependencies, just test the logic of the code
26−- When working from a markdown checklist of tasks, check off the tasks as you complete them
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)
2733
28−### Build System Requirements
34+## Project-Specific Conventions
2935
30−- Use `task build` over `go build` to ensure all tasks are run
31−- All build artifacts should be placed in the `build/` directory
32−- Build tasks must depend on test and lint tasks
33−- Reference `llm-shared/templates/Taskfile.yml` for comprehensive task structure
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`
3441
35−### Project Validation
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
3647
37−- Use the `validate-docs` tool to check if projects follow standard structure conventions:
38− ```bash
39− go run llm-shared/utils/validate-docs/validate-docs.go
40− ```
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
4153
42−---
54+## Integration Points
4355
44−## Go-Specific Guidelines
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
4560
46−### Code Formatting & Quality
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`
4765
48−- Always run `gofmt -w .` on Go code files after making changes
49−- Use `go fmt ./...` and `go vet ./...` for linting
50−- Functions that are easily unit-testable should have tests
51−- Don't go for 100% test coverage, test the critical parts of the code
66+## Development Guidelines
5267
53−### Library Preferences
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
5473
55−- Prefer using standard library packages when possible
56−- Provide justification when adding new third-party dependencies
57−- Keep dependencies updated
58−- If SQLite is used, use "modernc.org/sqlite" as the library (no dependency on cgo)
59−- Logging in applications run from cron: "log/slog" (standard library)
60−- Logging in applications run from CLI: "fmt.Println" (standard library, use emojis for better UX)
61−- Configuration management: "github.com/spf13/viper"
62−- Command-line arguments: "github.com/alecthomas/kong" (only if the project requires complex CLI)
63−
64−### Function Analysis
65−
66−- When looking for functions, use the `gofuncs` tool to list all functions in a Go project:
67− ```bash
68− go run llm-shared/utils/gofuncs/gofuncs.go -dir /path/to/project
69− ```
70−
71−---
72−
73−## Project-Specific Rules for `humanlog`
74−
75−### Overview & Architecture
76−
77−- This package provides a human-readable formatter for Go's `log/slog` output.
78−- Main components:
79− - `Handler` (`handler.go`): Implements `slog.Handler` with custom formatting.
80− - `Options` (`options.go`): Configures handler behavior.
81− - `NewHandler` (`humanlog.go`): Entry point for handler creation.
82−- Example usage: `example/main.go`. Tests: `handler_test.go`.
83−
84−### Developer Workflows
85−
86−- **Build**: Use `task build` (or standard Go tools `go build`, `go install` if no Taskfile exists yet).
87−- **Test**: `go test ./...` (see `handler_test.go`).
88−- **Example**: `go run example/main.go` to see formatted log output.
89−
90−### Project-Specific Conventions
91−
92−- No global state; all config via `Options` or method params.
93−- `NewHandler` panics if given a nil writer (enforced contract).
94−- All exported types/functions must have doc comments.
95−- Formatting helpers are unexported and colocated with usage.
96−- Log messages are padded/truncated to a fixed width (see `messageWidth` in `handler.go`).
97−- Color output for log levels unless `DisableColor` is set.
98−
99−### Integration & Dependencies
100−
101−- Only standard library and `log/slog` are used (following the minimal dependency principle).
102−- Go module path: `github.com/lepinkainen/humanlog` (see `go.mod`).
103−- When doing HTTP requests, use a custom user agent that includes the project name and version, e.g. `humanlog/1.0.0`
104−
105−### Patterns & Examples
106−
107−- See `example/main.go` for idiomatic usage patterns.
108−- See `handler_test.go` for test structure and coverage.
109−
110−---
111−
112−## Development Workflow
113−
114−### Code Analysis
115−
116−- When analyzing large codebases that might exceed context limits, use the Gemini CLI:
117− ```bash
118− gemini -p "@src/main.go Explain this file's purpose and functionality"
119− gemini -p "@src/ Summarise the architecture of this codebase"
120− gemini -p "@src/ Is the project test coverage on par with industry standards?"
121− ```
122−
123−### CI/CD Requirements
124−
125−- Projects should have a basic GitHub Actions setup that uses the build-ci task
126−- Use `llm-shared/templates/github/workflows/go-ci.yml` as a template
127−- CI should run tests and linting on push and pull requests
128−- Use `go test -tags=ci -cover -v ./...` for CI tests
129−- Allow skipping tests with `//go:build !ci`
130−
131−### Git Management
132−
133−- Keep `.gitignore` up to date with Go-specific ignores
134−- Use `llm-shared/templates/gitignore-go` as a reference
135−- Ensure build artifacts and temporary files are not committed
136−
137−---
138−
139−## Templates & References
140−
141−### Available Templates
142−
143−- **Taskfile**: `llm-shared/templates/Taskfile.yml` - Comprehensive task management
144−- **CI Workflow**: `llm-shared/templates/github/workflows/go-ci.yml` - GitHub Actions for Go
145−- **Gitignore**: `llm-shared/templates/gitignore-go` - Go-specific ignore patterns
146−- **Documentation**: `llm-shared/templates/README.md` and `llm-shared/templates/CHANGELOG.md`
147−
148−### Project Structure
149−
150−This project follows a simple Go library structure:
151−
74+**Formatting Examples:**
15275 ```
153−humanlog/
154−├── go.mod # Go module definition
155−├── *.go # Main library files (handler.go, options.go, humanlog.go)
156−├── *_test.go # Test files
157−├── example/ # Usage examples
158−├── llm-shared/ # Shared development guidelines (submodule)
159−├── docs/ # Project documentation (if needed)
160−└── build/ # Build artifacts (when using Taskfile)
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
16178 ```
162−
163−---
164−
165−_If any section is unclear or missing important project-specific details, please provide feedback or point to additional documentation to improve these rules._
166−
