go:embed

Canonical guidance

• use //go:embed for static assets needed at runtime
• keep patterns explicit and package-local
• choose embed.FS when a file tree or fs.FS integration matters

Use when

• templates
• small static web assets
• fixture data that should travel with the binary

Avoid

• embedding huge mutable data sets
• broad patterns that pull in unintended files
• confusing embed with runtime configuration

Preferred pattern

import "embed"

//go:embed templates/*.html
var templates embed.FS

Anti-pattern

• embedding development-only assets because it was simpler than fixing the runtime file lookup path

Explanation: This anti-pattern is tempting because it removes one deployment problem, but it quietly bloats the binary and hides asset ownership.

Why

• embedding is excellent for stable static assets, not for everything that happens to live on disk