go

Idiomatic Go

Write Go that is boring in the best way - direct, predictable, obvious on the first read. Clear is better than clever. The common failure mode (and the LLM default) is importing Java/Spring habits - deep layer trees, generic repositories, heavy frameworks, manual worker pools - into a language built for flat, simple, discoverable APIs. When in doubt, delete the abstraction.

Core principles

Clear is better than clever. If a function's control flow takes three reads to follow, rewrite it. Keep the happy path un-indented: handle errors and edge cases first and return.

func GetUser(id string) (*User, error) {
    user, err := db.FindUser(id)
    if err != nil {
        return nil, fmt.Errorf("finding user %s: %w", id, err)
    }
    return user, nil // happy path stays at the left margin
}

Make the zero value useful. Design types so the zero value works without a constructor - sync.Mutex and bytes.Buffer are the gold standard.

type Counter struct {
    mu    sync.Mutex // usable at the zero value - no New() needed
    count int
}

func (c *Counter) Inc() { c.mu.Lock(); c.count++; c.mu.Unlock() }

Packages: flat, named for what they do

Start flat; add a package only when a domain earns a namespace. Name packages by what they do (auth, billing, jobs), never by what layer they are (service, repository, controller) - layer-named packages breed circular imports and interface bloat and add zero clarity in Go. No utils/, helpers/, or common/ junk drawers; they signal unclear ownership. Packages don't import each other sideways - cycles mean wrong boundaries; the composition root wires them.

In this repo: the two public surfaces are server/ (build an A2A agent) and client/ (call one), with types/ for the shared A2A wire types and server/config/ for configuration. That is the established structure - follow it; don't invent a service/repository layer split. spf13's transferable rules still hold: name by purpose, no junk-drawer packages, wire at the composition root (here, the A2AServerBuilder / AgentBuilder).