/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](references/module-boundary.md) | | State Flow | Use stateless functions and one-shot state objects | [references/state-flow.md](references/state-flow.md) | | Orchestration | Use a single public executor and internal helpers | [references/orchestration.md](references/orchestration.md) | | gRPC Practices | Keep handlers as thin translators; isolate transport from domain | [references/grpc-practices.md](references/grpc-practices.md) | | Review Checklist | Run a fast architecture sanity check before merge | [references/review-checklist.md](references/review-checklist.md) |

References

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