Build Workflow
- Let the existing repo architecture lead. Preserve established package naming, dependency injection, and test style unless there is a concrete problem.
- Design boundaries around behavior and data ownership, not pattern names.
- Accept interfaces at the consumer boundary. Return concrete types unless hiding implementation is part of the API.
- Keep interfaces small. Prefer
io.Reader-style capability interfaces over broad service interfaces. - Keep domain/service packages independent of transport, database, CLI, logging, and framework details.
- Keep concurrency out of APIs when possible. Expose synchronous functions; let callers decide whether to run them in goroutines.
- Introduce repositories, ports/adapters, or functional options only when they remove real coupling or constructor complexity.
- Document tradeoffs in plans: dependency direction, concrete vs interface boundaries, test fakes, and simpler alternatives.
Audit Workflow
- Trace dependency direction across packages before judging architecture.
- Flag transport, database, framework, logging, or CLI details leaking into domain/service packages when they make testing or reuse harder.
- Check interfaces for consumer ownership, size, needless abstraction, and pointer-to-interface mistakes.
- Check concurrency APIs for hidden goroutines, cancellation gaps, shared-state races, channel leaks, and shutdown ambiguity.
- Report findings with the simpler alternative, not just the pattern name.
- Pair with
golang-code-auditwhen producing a full findings-first review.
Load References
- Read
references/patterns.mdwhen choosing simple packages, layered services, ports/adapters, repository, functional options, or concurrency patterns. - Pair with the companion
golang-planning-layoutskill for folder/module layout changes. - Pair with the companion
golang-testingskill when architecture choices affect fakes, integration tests, or contract tests.