golang
- Repo stars 0
- Author repo skills-registry
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Go Best Practices
## Error Handling
Check every error. The `if err != nil` pattern is intentional -- Go makes error handling explicit. Never discard errors with `_`. Wrap errors with context using `fmt.Errorf("doing X: %w", err)` so call chains produce readable messages.
Use sentinel errors (`var ErrNotFound = errors.New("not found")`) for expected conditions that callers check with `errors.Is()`. Use custom error types for errors that carry structured data.
## Project Structure
Follow the standard layout: `cmd/` for application entry points, `internal/` for private packages, `pkg/` for public libraries (if any). Keep `main.go` minimal -- it wires up dependencies and starts the server.
One package per directory. Package names should be short, lowercase, and descriptive. Avoid `util` or `common` packages -- they become dumping grounds.
## Concurrency
Do not communicate by sharing memory -- share memory by communicating. Use channels for synchronization between goroutines. Use `sync.Mutex` only for protecting simple shared state where channels would be overkill.
Always ensure goroutines can be stopped. Pass `context.Context` and check `ctx.Done()`. Leaking goroutines is a memory leak that grows over time.
Use `sync.WaitGroup` when you need to wait for a known number of goroutines to complete. Use `errgroup.Group` when any goroutine failure should cancel the rest.
## Interfaces
Define interfaces where they are used, not where they are implemented. Keep interfaces small -- one or two methods is ideal. The `io.Reader` and `io.Writer` interfaces are the gold standard.
Accept interfaces, return structs. This makes code testable -- callers can inject mocks that satisfy the interface.
## Testing
Use table-driven tests for functions with multiple input/output combinations. Name test cases clearly. Use `t.Run()` for subtests so failures identify which case broke.
Use `testing.T.Helper()` in test helper functions so failure messages point to the calling test, not the helper.
## Dependencies
Use `go mod tidy` to keep `go.mod` clean. Vendor dependencies with `go mod vendor` for reproducible builds in CI. Avoid unnecessary dependencies -- the standard library is comprehensive. Check if `net/http`, `encoding/json`, or `os` already do what you need.
## Performance
Profile before optimizing with `pprof`. Pre-allocate slices with `make([]T, 0, expectedCap)` when the size is known. Avoid string concatenation in loops -- use `strings.Builder`. Reduce allocations by reusing buffers with `sync.Pool` for hot paths.
---
> Source: [calcosmic/Aether](https://github.com/calcosmic/Aether) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
Sections and files
Listed in source order.
sections -> Error Handling → Project Structure → Concurrency → Interfaces → Testing → Dependencies
terms -> Check every error. · Use sentinel errors (var ErrNotFound = errors.New("not found")) for expected conditions that callers check with errors.Is(). · Follow the standard layout: cmd/ for application entry points, internal/ for private packages, pkg/ for public libraries (if any). · One package per directory. · Do not communicate by sharing memory -- share memory by communicating. · Always ensure goroutines can be stopped. · Use sync.WaitGroup when you need to wait for a known number of goroutines to complete. · Define interfaces where they are used, not where they are implemented.
files/cmd -> if err != nil · . Wrap errors with context using · var ErrNotFound = errors.New("not found") · errors.Is() · cmd/ · internal/ · pkg/ · main.go
body sha256 -> 33fa850324ca
Error Handling
Check every error. The
if err != nilpattern is intentional -- Go makes error handling explicit. Never discard errors with_. Wrap errors with context usingfmt.Errorf("doing X: %w", err)so call chains produce readable messages. Use sentinel errors (var ErrNotFound = errors.New("not found")) for expected conditions that callers check witherrors.Is(). Use custom error types for errors that carry structured data.Project Structure
Follow the standard layout:
cmd/for application entry points,internal/for private packages,pkg/for public libraries (if any). Keepmain.gominimal -- it wires up dependencies and starts the server. One package per directory. Package names should be short, lowercase, and descriptive. Avoidutilorcommonpackages -- they become dumping grounds.Concurrency
Do not communicate by sharing memory -- share memory by communicating. Use channels for synchronization between goroutines. Use
sync.Mutexonly for protecting simple shared state where channels would be overkill. Always ensure goroutines can be stopped. Passcontext.Contextand checkctx.Done(). Leaking goroutines is a memory leak that grows over time. Usesync.WaitGroupwhen you need to wait for a known number of goroutines to complete. Useerrgroup.Groupwhen any goroutine failure should cancel the rest.Interfaces
Define interfaces where they are used, not where they are implemented. Keep interfaces small -- one or two methods is ideal. The
io.Readerandio.Writerinterfaces are the gold standard. Accept interfaces, return structs. This makes code testable -- callers can inject mocks that satisfy the interface.Testing
Use table-driven tests for functions with multiple input/output combinations. Name test cases clearly. Use
t.Run()for subtests so failures identify which case broke. Usetesting.T.Helper()in test helper functions so failure messages point to the calling test, not the helper.