# CLAUDE.md

## Project

Go project. Customize this section with your own description, layout, and conventions.

**Typical layout:**
- `main.go` or `cmd/<name>/main.go` — entry points
- `internal/` — packages private to this module
- `pkg/` — packages intended for external import (only if you publish them)
- `<package>/<file>_test.go` — tests beside the code they exercise
- `testdata/` — fixtures (ignored by the build tool)

## Build & Test Commands

If the project has a Makefile, document targets here. Common pattern:

```bash
make test                 # go test ./...
make test -- -run Pattern # match test names
make coverage             # suite under -coverprofile + go tool cover -func
make coverage-summary     # file-weighted total + files absent from the profile
make lint                 # gofmt check + go vet (+ staticcheck/golangci-lint if used)
make build                # go build ./...
```

Direct equivalents: `go test ./...`, `go test -race ./...`, `go vet ./...`,
`go build ./...`, `gofmt -l .`.

## Language Rules

See rule files in `.claude/rules/`:
- `go.md` — code style and patterns
- `go-testing.md` — testing conventions (table-driven, `-race`, coverage)
- `verification.md` — verify-before-claim-done discipline

## Git Workflow

Commit conventions: see `.claude/rules/commits.md` (author identity,
no AI attribution, message format).

Pre-commit hook in `githooks/` scans for secrets and runs `gofmt -l` on staged
`.go` files. Activate on a fresh clone with `git config core.hooksPath githooks`.

## Problem-Solving Approach

Investigate before fixing. When diagnosing a bug:
1. Read the relevant package and trace what actually happens
2. Identify the root cause, not a surface symptom
3. Write a failing test (a table row) that captures the correct behavior
4. Fix, then re-run tests with `go test -race ./...`

## Testing Discipline

TDD is the default: write a failing test before any implementation. If you
can't write the test, you don't yet understand the change. Table-driven tests
express the Normal/Boundary/Error categories; details in
`.claude/rules/go-testing.md`.

## Editing Discipline

A PostToolUse hook runs `gofmt` and `go vet` on every `.go` file after
Edit/Write/MultiEdit. `go vet` type-checks, so compile errors and suspicious
constructs surface at edit time — read them. Tests aren't auto-run on edit
(a package's tests can be slow or integration-tagged); run them with `make
coverage` or `go test`.

## What Not to Do

- Don't add features beyond what was asked
- Don't refactor surrounding code when fixing a bug
- Don't ignore a returned error to shorten a line
- Don't add comments to code you didn't change
- Don't create an interface or abstraction for a single implementation
- Don't commit credentials or API keys — the pre-commit hook catches common patterns but isn't a substitute for care