Go Packages and Imports

When this skill does NOT apply: For naming individual identifiers within a package, see go-naming. For organizing functions within a single file, see go-functions. For configuring linters that enforce import rules, see go-linting.

Package Organization

Avoid Util Packages

Package names should describe what the package provides. Avoid generic names like util, helper, common — they obscure meaning and cause import conflicts.

// Good: Meaningful package names
db := spannertest.NewDatabaseFromFile(...)
_, err := f.Seek(0, io.SeekStart)

// Bad: Vague names obscure meaning
db := test.NewDatabaseFromFile(...)
_, err := f.Seek(0, common.SeekStart)

Generic names can be used as part of a name (e.g., stringutil) but should not be the entire package name.

Package Size

Question	Action
Can you describe its purpose in one sentence?	No → split by responsibility
Do files never share unexported symbols?	Those files could be separate packages
Distinct user groups use different parts?	Split along user boundaries
Godoc page overwhelming?	Split to improve discoverability

Do NOT split just because a file is long, to create single-type packages, or if it would create circular dependencies.

Read references/PACKAGE-SIZE.md when deciding whether to split or combine packages, organizing files within a package, or structuring CLI programs.

Imports

Imports are organized in groups separated by blank lines. Standard library packages always come first. Use goimports to manage this automatically.

import (
    "fmt"
    "os"

    "github.com/foo/bar"
    "rsc.io/goversion/version"
)

Quick rules:

Rule	Guidance
Grouping	stdlib first, then external. Extended: stdlib → other → protos → side-effects
Renaming	Avoid unless collision. Rename the most local import. Proto packages get `pb` suffix
Blank imports (`import _`)	Only in `main` packages or tests
Dot imports (`import .`)	Never use, except for circular-dependency test files

Read references/IMPORTS.md when organizing imports with extended grouping, renaming proto packages, or deciding on blank/dot imports.

Avoid init()

Avoid init() where possible. When unavoidable, it must be:

Completely deterministic
Independent of other init() ordering
Free of environment state (env vars, working dir, args)
Free of I/O (filesystem, network, system calls)

Acceptable uses: complex expressions that can't be single assignments, pluggable hooks (e.g., database/sql dialects), deterministic precomputation.

Read references/PACKAGE-SIZE.md when you need to refactor init() into explicit functions or understand acceptable init() uses.

Exit in Main

Call os.Exit or log.Fatal* only in main(). All other functions should return errors.

Why: Non-obvious control flow, untestable, defer statements skipped.

Best practice: Use the run() pattern — extract logic into func run() error, call from main() with a single exit point:

func main() {
    if err := run(); err != nil {
        log.Fatal(err)
    }
}

Read references/PACKAGE-SIZE.md when implementing the run() pattern, structuring CLI subcommands, or choosing flag naming conventions.

Related Skills

Package naming: See go-naming when choosing package names, avoiding stuttering, or naming exported symbols
Error handling across packages: See go-error-handling when wrapping errors at package boundaries with %w vs %v
Import linting: See go-linting when configuring goimports local-prefixes or enforcing import grouping
Global state: See go-defensive when replacing init() with explicit initialization or avoiding mutable globals

Reference Files

references/IMPORTS.md — Extended import grouping, renaming, blank/dot imports
references/PACKAGE-SIZE.md — Package splitting, init() alternatives, run() pattern, CLI structure

go-packages