go-structurelisted

# Go Project Structure Recommend and scaffold idiomatic Go project layouts. Matches structure to project type and size — start simple, grow when needed. ## When to Use - Initializing a new Go project or module - User asks about project layout or directory organization - Reviewing an existing project for structural anti-patterns - Migrating from flat layout to a more structured one - Setting up a monorepo with multiple services ## Prerequisites 1. **go.mod exists or will be created**: The project must be a Go module. 2. **Project type is known or inferrable**: CLI tool, REST API, library, or monorepo. ## Core Principle **Simplicity first, complexity when necessary.** Do not impose structure upfront. Let it emerge from actual needs. A single `main.go` is a valid starting point. ## Anti-Patterns to Flag | Anti-Pattern | Problem | Fix | |---|---|---| | Generic package names (`utils`, `helpers`, `common`, `base`) | Become dumping grounds, convey no intent | Rename to specific purpose: `validator`, `auth`, `cache` | | Over-nesting (`internal/services/user/handlers/http/v1/`) | Cognitive load, cumbersome imports | Flatten to `internal/user/handler.go` | | Circular dependencies (`A` imports `B`, `B` imports `A`) | Compilation error, poor separation | Extract shared types into a separate package or use interfaces | | Business logic in HTTP handlers | Couples domain to transport, hard to test | Move to service layer, handlers only do HTTP concerns | | The `main.go` monster (al