GEMINI.md

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