Go Core Idioms
Idiomatic sequential Go for 1.26. For anything touching goroutines, channels,
errgroup, or context cancellation, use go-concurrency instead.
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Map existing error/logging/interface patterns
- fuse-ai-pilot:research-expert - Verify latest Go docs via Context7/Exa
- mcp__context7__query-docs - Confirm stdlib signatures (errors, log/slog)
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
| Feature |
Description |
| Error handling |
Explicit if err != nil, %w wrapping, errors.Join, errors.AsType (1.26) |
| Structured logging |
log/slog stdlib — handlers, attrs, groups, LogValuer |
| Generics |
Type params, constraints, self-referential types (1.26) |
| Interfaces |
Small, consumer-side — "accept interfaces, return structs" |
| Modernizers |
go fix auto-applies dozens of idiom/API fixers (1.26) |
Critical Rules
- Explicit
if err != nil - No sugar exists; never discard with _ = err
- Wrap with
%w, not %v - Preserves the chain for errors.Is/As/AsType
- Accept interfaces, return structs - Define interfaces where consumed, not where produced
- Value receivers by default - Use pointer receivers only for mutation or large structs
- Run
go fix + go vet - Let modernizers migrate to current idioms (1.26)
Architecture
internal/
├── user/
│ ├── user.go # struct + value-receiver methods
│ ├── errors.go # sentinel + typed errors
│ └── repository.go # consumer-side interface, concrete struct returned
└── platform/
└── logging/
└── logger.go # slog setup, one *slog.Logger injected downward
→ See error-patterns.md for full example
Reference Guide
Concepts
| Topic |
Reference |
When to Consult |
| Error handling |
error-handling.md |
Wrapping, sentinels, errors.Join, AsType |
| Structured logging |
slog-logging.md |
Choosing handlers, attrs, groups, perf |
| Generics & 1.26 |
generics-and-1.26.md |
Type params, self-ref types, new(expr) |
| Interfaces & style |
interfaces-and-style.md |
Interface placement, naming, receivers |
Templates
| Template |
When to Use |
| error-patterns.md |
Building an error strategy for a package |
| slog-setup.md |
Wiring a structured logger into an app |
Quick Reference
Wrap and inspect errors
if err != nil {
return fmt.Errorf("load user %d: %w", id, err) // %w keeps the chain
}
// 1.26: type-safe, generic replacement for errors.As
if pathErr, ok := errors.AsType[*fs.PathError](err); ok {
log.Printf("failed path: %s", pathErr.Path)
}
→ See error-handling.md
Structured logging with slog
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
logger.Info("user created", "id", id, slog.Duration("took", elapsed))
→ See slog-logging.md
Best Practices
DO
- Keep interfaces one-to-three methods, named at the call site
- Add context on the way up with
%w; check with errors.Is/AsType
- Use
slog.LogAttrs on hot paths to avoid allocation
- Run
go fix to adopt current APIs and idioms automatically (1.26)
DON'T
- Swallow errors (
_ = err) or return bare err when context helps
- Define interfaces next to their implementation "just in case"
- Reach for pointer receivers without a mutation or size reason
- Write Java-esque getters/setters or
IFoo interface prefixes
1---2name: go-core-idioms3description: Use when writing or reviewing idiomatic sequential Go — error handling, slog logging, generics, interfaces, style. Not for concurrency (go-concurrency).4versions:5 go: "1.26"6user-invocable: false7references: references/error-handling.md, references/slog-logging.md, references/generics-and-1.26.md, references/interfaces-and-style.md, references/templates/error-patterns.md, references/templates/slog-setup.md8related-skills: go-concurrency, solid-go9metadata:10 source: https://skillmd.com/skills/fusengine/go-core-idioms11---1213<objective>14Covers idiomatic sequential Go 1.26: error handling (%w wrapping, errors.Join,15errors.Is/As, errors.AsType), slog structured logging, generics, small16consumer-side interfaces, naming/style conventions, new(expr), and go fix17modernizers. Does not cover goroutines/channels/errgroup/context concurrency18(see go-concurrency), non-Go languages, or framework-specific code.19</objective>2021# Go Core Idioms2223Idiomatic sequential Go for 1.26. For anything touching goroutines, channels,24`errgroup`, or `context` cancellation, use **go-concurrency** instead.2526## Agent Workflow (MANDATORY)2728Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:29301. **fuse-ai-pilot:explore-codebase** - Map existing error/logging/interface patterns312. **fuse-ai-pilot:research-expert** - Verify latest Go docs via Context7/Exa323. **mcp__context7__query-docs** - Confirm stdlib signatures (errors, log/slog)3334After implementation, run **fuse-ai-pilot:sniper** for validation.3536---3738## Overview3940| Feature | Description |41|---------|-------------|42| **Error handling** | Explicit `if err != nil`, `%w` wrapping, `errors.Join`, `errors.AsType` (1.26) |43| **Structured logging** | `log/slog` stdlib — handlers, attrs, groups, `LogValuer` |44| **Generics** | Type params, constraints, self-referential types (1.26) |45| **Interfaces** | Small, consumer-side — "accept interfaces, return structs" |46| **Modernizers** | `go fix` auto-applies dozens of idiom/API fixers (1.26) |4748---4950## Critical Rules51521. **Explicit `if err != nil`** - No sugar exists; never discard with `_ = err`532. **Wrap with `%w`, not `%v`** - Preserves the chain for `errors.Is`/`As`/`AsType`543. **Accept interfaces, return structs** - Define interfaces where consumed, not where produced554. **Value receivers by default** - Use pointer receivers only for mutation or large structs565. **Run `go fix` + `go vet`** - Let modernizers migrate to current idioms (1.26)5758---5960## Architecture6162```63internal/64├── user/65│ ├── user.go # struct + value-receiver methods66│ ├── errors.go # sentinel + typed errors67│ └── repository.go # consumer-side interface, concrete struct returned68└── platform/69 └── logging/70 └── logger.go # slog setup, one *slog.Logger injected downward71```7273→ See [error-patterns.md](references/templates/error-patterns.md) for full example7475---7677## Reference Guide7879### Concepts8081| Topic | Reference | When to Consult |82|-------|-----------|-----------------|83| **Error handling** | [error-handling.md](references/error-handling.md) | Wrapping, sentinels, `errors.Join`, `AsType` |84| **Structured logging** | [slog-logging.md](references/slog-logging.md) | Choosing handlers, attrs, groups, perf |85| **Generics & 1.26** | [generics-and-1.26.md](references/generics-and-1.26.md) | Type params, self-ref types, `new(expr)` |86| **Interfaces & style** | [interfaces-and-style.md](references/interfaces-and-style.md) | Interface placement, naming, receivers |8788### Templates8990| Template | When to Use |91|----------|-------------|92| [error-patterns.md](references/templates/error-patterns.md) | Building an error strategy for a package |93| [slog-setup.md](references/templates/slog-setup.md) | Wiring a structured logger into an app |9495---9697## Quick Reference9899### Wrap and inspect errors100101```go102if err != nil {103 return fmt.Errorf("load user %d: %w", id, err) // %w keeps the chain104}105// 1.26: type-safe, generic replacement for errors.As106if pathErr, ok := errors.AsType[*fs.PathError](err); ok {107 log.Printf("failed path: %s", pathErr.Path)108}109```110111→ See [error-handling.md](references/error-handling.md)112113### Structured logging with slog114115```go116logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))117logger.Info("user created", "id", id, slog.Duration("took", elapsed))118```119120→ See [slog-logging.md](references/slog-logging.md)121122---123124## Best Practices125126### DO127- Keep interfaces one-to-three methods, named at the call site128- Add context on the way up with `%w`; check with `errors.Is`/`AsType`129- Use `slog.LogAttrs` on hot paths to avoid allocation130- Run `go fix` to adopt current APIs and idioms automatically (1.26)131132### DON'T133- Swallow errors (`_ = err`) or return bare `err` when context helps134- Define interfaces next to their implementation "just in case"135- Reach for pointer receivers without a mutation or size reason136- Write Java-esque getters/setters or `IFoo` interface prefixes