code-guidelines-go

Go 1.24–1.27 Coding Guidelines — pi-go

Project: github.com/dimetron/pi-go — Go-native AI coding agent runtime
Layout: cmd/pi/ · internal/ · .pi-go/ · .vibe/compiled/ · scripts/
Min version: Go 1.24 (tool directive support) | Target: Go 1.27

For what Go 1.27 changed — generic methods, struct-literal field selectors, encoding/json/v2, the stdlib uuid package, removals that break a build, and the GOEXPERIMENT=none trap on this machine — see the go-127 skill.

---

1. Style & Naming

Packages

• Short, lowercase, singular, no underscores: config ✓ agentUtils ✗
• No stutter: package agent → type Runner (not AgentRunner)
• Never util, common, types, helpers

Identifiers

• Receivers: 1–2 chars from type name, consistent across all methods, never self/this
• Acronyms full caps: ID, URL, HTTP, LLM — enforced by staticcheck
• Short names in small scopes (i, ctx, err), descriptive in large scopes

// ✓ Correct
func (r *Runner) Execute(ctx context.Context) error { ... }
func (r *Runner) Stop()                             { ... }

// ✗ Wrong
func (self *Runner) Execute(ctx context.Context) error { ... }
func (runner *Runner) Stop()                           { ... }

Interfaces

• Define at the consumer, not producer
• 1–3 methods; single-method uses -er suffix (Reader, Handler, Closer)
• Accept interfaces, return concrete structs

// consumer defines what it needs (internal/agent/)
type LLMClient interface {
    Complete(ctx context.Context, prompt string) (string, error)
}

// producer returns concrete struct (internal/llm/)
func NewOpenAIClient(apiKey string) *OpenAIClient { ... }

Godoc

Every exported name starts its comment with the name itself:

// Package agent provides the core AI agent runtime for pi-go.
package agent

// Runner orchestrates tool calls and LLM interactions.
type Runner struct { ... }

// Execute runs the agent loop until completion or context cancellation.
func (r *Runner) Execute(ctx context.Context, task string) error { ... }