opentrace: Instructions file for Claude Code

CLAUDE.md

Build & Test

go build -o opentrace ./cmd/opentrace
go test -short -race ./...          # unit tests (no Docker)
go test -race ./...                 # full suite (needs Docker)
go vet ./...                        # linting
go mod tidy                         # after adding new imports

Do

• Use store.ErrNotFound sentinel for 404 responses
• Use server.WriteJSON(w, status, data) / server.WriteError(w, status, msg) for HTTP responses
• Use log/slog with structured key-value fields — always include "error" key on errors
• Guard integration tests with testing.Short() skip
• Use ? placeholders in SQLite queries — never string interpolation
• Store booleans as INTEGER 0/1, timestamps as RFC3339 TEXT, UUIDs as TEXT
• Cast MCP tool args from float64 (JSON default) before using as int
• When adding a store interface method, update ALL mock implementations (internal/testutil/mocks/, internal/api/mock_test.go, and any package-local test doubles — grep the method name)
• When adding a new store, add to pkg/store/ (interface + model) and internal/adapter/sqlite/ (implementation, wired in internal/adapter/sqlite/stores.go)
• Use the server.Module pattern for new HTTP features — see internal/routes/<name>/module.go for examples
• Run go mod tidy after adding new imports
• Cap all pagination limit params to a reasonable maximum (100-500)
• Validate and sanitize all user input at handler boundaries

Don't

• Don't use fmt.Println or the old log package — use slog.* only
• Don't shadow an imported package name with a local variable (e.g. a local watcher in a file that imports internal/watcher)
• Don't use CGO — all dependencies must be pure Go for cross-compilation
• Don't leak internal error details (SQL, file paths, stack traces) in HTTP responses
• Don't add store fields directly to server.Deps — embed them in store.Stores instead
• Don't skip testing.Short() guards on tests that need Docker or network
• Don't hardcode magic numbers — use named constants
• Don't write functions longer than ~100 lines — extract helpers