Build Workflow
- Inspect
go.mod,go.work,cmd/,internal/, package names, existing build scripts, and tests before proposing layout changes. - Prefer the smallest module/package structure that satisfies the current repo. Do not introduce architecture folders by default.
- Keep packages cohesive around behavior and import boundaries. Split only when it reduces coupling, clarifies ownership, or creates a real reusable package.
- Put binaries in
cmd/<name>when there are multiple commands or substantial support code. A single small command can live at module root. - Put non-public implementation packages under
internal/. Use ordinary importable packages only when external reuse is intended. - Keep names short, lowercase, and meaningful at the call site. Avoid stutter such as
user.UserServicewhenuser.Serviceis clear. - Produce plans that include verification commands: usually
go test ./...,go vet ./..., format/import sorting, and project-specific lint/build commands.
Audit Workflow
- Inspect
go.mod,go.work, package tree, command layout, import boundaries, and test locations before judging. - Flag unnecessary modules, architecture folders, public packages,
pkg/usage, or command placement only when they create real coupling or confusion. - Check whether package names are cohesive, short, lowercase, and clear at call sites.
- Report findings with concrete boundary or layout consequences; avoid cosmetic restructuring advice.
- Pair with
golang-code-auditwhen producing a full findings-first review.
Load References
- Read
references/repo-layout.mdwhen changing module layout, package boundaries, command placement, or workspace setup. - Pair with the companion
golang-architecture-patternsskill when the task involves service boundaries, dependency direction, ports/adapters, or domain layering. - Pair with the companion
golang-testingskill when the plan must include test strategy.