modular-go

Concise guidance for designing Go packages that stay small, focused, and easy to evolve.

Purpose and Triggers

• Use for Go package design, refactoring, and code review.
• Focus on API boundaries, state modeling, and flow decomposition.
• Use when deciding the right abstraction level: local helper, utility package, manager, or builder.
• Prefer explicit boundaries over convenience exports.

Design Principles

1. Every export is a promise — keep the public surface minimal and intentional.
2. One package, one responsibility you can explain in one sentence.
3. Depth over breadth — narrow interfaces that hide rich implementations outlast wide, shallow ones.
4. Stateless by default — treat mutable state as liability that must justify its lifecycle cost.
5. Split along responsibility seams, not file size — every new boundary must earn its indirection cost.
6. Orchestration tells the story; capability methods do the work.
7. Boundaries are translation layers — convert errors, types, and protocols at the edges, not in core logic.
8. Choose the smallest abstraction that solves the real problem; resist premature generalization.
9. Lifecycle is a first-class design concern — design shutdown paths alongside startup paths.

Workflow

1. Define one package responsibility.
2. Expose one obvious primary entry point (type, interface, or function).
3. Keep helpers local by default; extract to xxxutil only for real cross-package reuse.
4. Keep transport handlers focused on protocol mapping and delegate behavior to injected dependencies.
5. Compose orchestration from focused functions, with short stage-intent comments.
6. Re-evaluate boundaries when a package can no longer be explained in one sentence.
7. Re-check against the reference checklists before merge.

Topics

References

• Reference files are intentionally short and task-focused.
• Source links are listed in each reference file frontmatter urls.