modular-go

name	modular-go
description	Practical guidance for Go package design with minimal public APIs, single-responsibility boundaries, stateless-first flow, one-way state transitions, and orchestration-to-capability separation. Use when creating, refactoring, or reviewing Go architecture, package boundaries, interfaces, handlers, managers, builders, and execution flows.

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

Topic	Guidance	Reference
Module Boundary	Expose minimal API and separate deep vs wide interfaces	references/module-boundary.md
State Flow	Use stateless functions and one-shot state objects	references/state-flow.md
Orchestration	Use a single public executor and internal helpers	references/orchestration.md
gRPC Practices	Keep handlers as thin translators; isolate transport from domain	references/grpc-practices.md
Review Checklist	Run a fast architecture sanity check before merge	references/review-checklist.md

References

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