| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 2 | 21 | 4 | 7% |
| Commands | 4 | 9 | 1 | 29% |
| 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
- + GEMINI.md for humanlog
- + Project Overview
- + Integration Points
- + General AI Agent Guidance
- Developer Workflows
- Project-Specific Conventions
Commands
4 shared · 9 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.mod
- − 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
Section tags
6 shared · 6 only in A · 0 only in B- − setup
- − lint-format
- − git-pr
- − dependencies
- − deployment
- − do-not
- build
- test
- code-style
- architecture
- testing-strategy
- 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 · 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
@@ −1 +1 @@
1−# Humanlog Project Rules
1+# GEMINI.md for humanlog
22
3−## Shared Guidelines Reference
3+This document provides essential guidelines for AI 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 `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.
1113
12−> **Always consult the above files for baseline rules. This file documents project-specific conventions and architectural notes for `humanlog`.**
14+## Developer Workflows
1315
14−---
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.
1520
16−## Project Management & Build Requirements
21+## Project-Specific Conventions
1722
18−### Task Completion Criteria
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.
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+## Integration Points
2730
28−### Build System Requirements
31+- `humanlog` integrates directly with Go's standard `log/slog` package by implementing the `slog.Handler` interface.
2932
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
33+## General AI Agent Guidance
3434
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−
150−This project follows a simple Go library structure:
151−
152−```
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)
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._
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.
16640
