| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 2 | 4 | 21 | 7% |
| Commands | 4 | 1 | 9 | 29% |
| Section tags | 6 | 0 | 6 | 50% |
What each file covers
Sections
2 shared · 4 only in A · 21 only in B- − GEMINI.md for humanlog
- − Project Overview
- − Integration Points
- − General AI Agent Guidance
- + 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
- Developer Workflows
- Project-Specific Conventions
Commands
4 shared · 1 only in A · 9 only in B- − go run llm-shared/utils/gofuncs/gofuncs.go -dir .
- + 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 ./...
- task build
- go test
- go build
- go run example/main.go
Section tags
6 shared · 0 only in A · 6 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 · 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 · .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
@@ −1 +1 @@
1−# GEMINI.md for humanlog
1+# Humanlog Project Rules
22
3−This document provides essential guidelines for AI agents working on the `humanlog` Go project.
3+## Shared Guidelines Reference
44
5−## Project Overview
5+**This project follows the shared LLM assistant guidelines in [`llm-shared/`](../llm-shared/):**
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+- **[`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.
1311
14−## Developer Workflows
12+> **Always consult the above files for baseline rules. This file documents project-specific conventions and architectural notes for `humanlog`.**
1513
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.
14+---
2015
21−## Project-Specific Conventions
16+## Project Management & Build Requirements
2217
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.
18+### Task Completion Criteria
2819
29−## Integration Points
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
3027
31−- `humanlog` integrates directly with Go's standard `log/slog` package by implementing the `slog.Handler` interface.
28+### Build System Requirements
3229
33−## General AI Agent Guidance
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
3434
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.
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._
40166
