docs-ssot go.instructions.md

Go File Rules

Go version

This project uses Go 1.26. Prefer modern language and standard library features:

• for range over integers (for i := range n) — available since Go 1.22
• slices and maps packages from the standard library
• any instead of interface{}
• t.Context() in tests instead of context.Background()
• errors.New for static error strings; fmt.Errorf("...: %w", err) for error wrapping
• new(expr) for pointer literals — available since Go 1.26

Pointer literals

Go 1.26 allows passing expressions directly to new, eliminating the need for a temporary variable or helper functions like ToPtr():

// Before Go 1.26 — create a temp variable first
n := int64(300)
ptr := &n

// Also before — helper function workaround
func ToPtr[T any](v T) *T { return &v }
ptr := ToPtr(int64(300))

// Go 1.26+ — pass the expression directly
ptr := new(int64(300))

Rules:

• Do not define or use ToPtr, Ptr, or similar pointer-helper functions.
• Do not create a temporary variable solely to take its address.
• Use new(expr) for all pointer literals to optional/nullable fields.

Toolchain setup

All Go commands run from mcp-server/. The module lives at github.com/hiromaily/claude-forge/mcp-server.

To set up the dev environment (installs lefthook hooks and pins golangci-lint as a tool in go.mod):

cd mcp-server && make install

golangci-lint is pinned as a Go tool dependency (go get -tool — available since Go 1.24). Run it via go tool golangci-lint, not a globally installed binary. The version is locked in go.mod under the tool directive.

Running tests

cd mcp-server && go test ./...

Git hooks (lefthook)

Lefthook runs automatically on git operations. Both hooks only trigger when **/*.go files are staged/pushed, and both run from mcp-server/.

Hook	Command	Behaviour
pre-commit	make go-fmt	Formats staged .go files and re-stages the fixes (stage_fixed: true)
pre-push	make go-lint	Lints and auto-fixes .go files before push