--- id: daily-golang-project-layout name: "golang-project-layout" url: https://skills.yangsir.net/skill/daily-golang-project-layout author: samber domain: ai-software-architecture-engineering tags: ["project-structure", "software-architecture", "code-organization", "go-layout", "modularity"] install_count: 2800 rating: 4.40 (24 reviews) github: https://github.com/samber/cc-skills-golang --- # golang-project-layout > 根据项目规模设计合理的 Go 项目布局，避免过度分层，简单脚本保持扁平，复杂服务按需分层 **Stats**: 2,800 installs · 4.4/5 (24 reviews) ## Before / After 对比 ### 项目结构设计 **Before**: 手动规划目录结构需要权衡可维护性和开发效率，过度分层增加跳转成本，分层不足导致代码耦合，设计需要 1-2 小时，且后期重构成本高 **After**: 根据功能复杂度和团队规模自动推荐最合适的布局，生成清晰的模块划分和依赖关系图，10 分钟获得可扩展的项目结构 | Metric | Before | After | Change | |---|---|---|---| | 设计时间 | 90分钟 | 10分钟 | -89% | ## Readme # golang-project-layout **Persona:** You are a Go project architect. You right-size structure to the problem — a script stays flat, a service gets layers only when justified by actual complexity. # Go Project Layout ## Architecture Decision: Ask First When starting a new project, **ask the developer** what software architecture they prefer (clean architecture, hexagonal, DDD, flat structure, etc.). NEVER over-structure small projects — a 100-line CLI tool does not need layers of abstractions or dependency injection. → See `samber/cc-skills-golang@golang-design-patterns` skill for detailed architecture guides with file trees and code examples. ## Dependency Injection: Ask Next After settling on the architecture, **ask the developer** which dependency injection approach they want: manual constructor injection, or a DI library (samber/do, google/wire, uber-go/dig+fx), or none at all. The choice affects how services are wired, how lifecycle (health checks, graceful shutdown) is managed, and how the project is structured. See the `samber/cc-skills-golang@golang-dependency-injection` skill for a full comparison and decision table. ## 12-Factor App For applications (services, APIs, workers), follow [12-Factor App](https://12factor.net/) conventions: config via environment variables, logs to stdout, stateless processes, graceful shutdown, backing services as attached resources, and admin tasks as one-off commands (e.g., `cmd/migrate/`). ## Quick Start: Choose Your Project Type Project Type Use When Key Directories **CLI Tool** Building a command-line application `cmd/{name}/`, `internal/`, optional `pkg/` **Library** Creating reusable code for others `pkg/{name}/`, `internal/` for private code **Service** HTTP API, microservice, or web app `cmd/{service}/`, `internal/`, `api/`, `web/` **Monorepo** Multiple related packages/modules `go.work`, separate modules per package **Workspace** Developing multiple local modules `go.work`, replace directives ## Module Naming Conventions ### Module Name (go.mod) Your module path in `go.mod` should: - **MUST match your repository URL**: `github.com/username/project-name` - **Use lowercase only**: `github.com/you/my-app` (not `MyApp`) - **Use hyphens for multi-word**: `user-auth` not `user_auth` or `userAuth` - **Be semantic**: Name should clearly express purpose **Examples:** ``` // ✅ Good module github.com/jdoe/payment-processor module github.com/company/cli-tool // ❌ Bad module myproject module github.com/jdoe/MyProject module utils ``` ### Package Naming Packages MUST be lowercase, singular, and match their directory name. → See `samber/cc-skills-golang@golang-naming` skill for complete package naming conventions and examples. ## Directory Layout All `main` packages must reside in `cmd/` with minimal logic — parse flags, wire dependencies, call `Run()`. Business logic belongs in `internal/` or `pkg/`. Use `internal/` for non-exported packages, `pkg/` only when code is useful to external consumers. See [directory layout examples](https://github.com/samber/cc-skills-golang/blob/HEAD/skills/golang-project-layout/references/directory-layouts.md) for universal, small project, and library layouts, plus common mistakes. ## Essential Configuration Files Every Go project should include at the root: - **Makefile** — build automation. See [Makefile template](https://github.com/samber/cc-skills-golang/blob/HEAD/skills/golang-project-layout/assets/Makefile) - **.gitignore** — git ignore patterns. See [.gitignore template](https://github.com/samber/cc-skills-golang/blob/HEAD/skills/golang-project-layout/assets/.gitignore) - **.golangci.yml** — linter config. See the `samber/cc-skills-golang@golang-linter` skill for the recommended configuration For application configuration with Cobra + Viper, see [config reference](https://github.com/samber/cc-skills-golang/blob/HEAD/skills/golang-project-layout/references/config.md). ## Tests, Benchmarks, and Examples Co-locate `_test.go` files with the code they test. Use `testdata/` for fixtures. See [testing layout](https://github.com/samber/cc-skills-golang/blob/HEAD/skills/golang-project-layout/references/testing-layout.md) for file naming, placement, and organization details. ## Go Workspaces Use `go.work` when developing multiple related modules in a monorepo. See [workspaces](https://github.com/samber/cc-skills-golang/blob/HEAD/skills/golang-project-layout/references/workspaces.md) for setup, structure, and commands. ## Initialization Checklist When starting a new Go project: - **Ask the developer** their preferred software architecture (clean, hexagonal, DDD, flat, etc.) - **Ask the developer** their preferred DI approach — see `samber/cc-skills-golang@golang-dependency-injection` skill - Decide project type (CLI, library, service, monorepo) - Right-size the structure to the project scope - Choose module name (matches repo URL, lowercase, hyphens) - Run `go version` to detect the current go version - Run `go mod init github.com/user/project-name` - Create `cmd/{name}/main.go` for entry point - Create `internal/` for private code - Create `pkg/` only if you have public libraries - For monorepos: Initialize `go work` and add modules - Run `gofmt -s -w .` to ensure formatting - Add `.gitignore` with `/vendor/` and binary patterns ## Related Skills → See `samber/cc-skills-golang@golang-cli` skill for CLI tool structure and Cobra/Viper patterns. → See `samber/cc-skills-golang@golang-dependency-injection` skill for DI approach comparison and wiring. → See `samber/cc-skills-golang@golang-linter` skill for golangci-lint configuration. → See `samber/cc-skills-golang@golang-continuous-integration` skill for CI/CD pipeline setup. → See `samber/cc-skills-golang@golang-design-patterns` skill for architectural patterns. Weekly Installs735Repository[samber/cc-skills-golang](https://github.com/samber/cc-skills-golang)GitHub Stars1.1KFirst SeenMar 22, 2026Security Audits[Gen Agent Trust HubPass](/samber/cc-skills-golang/golang-project-layout/security/agent-trust-hub)[SocketPass](/samber/cc-skills-golang/golang-project-layout/security/socket)[SnykPass](/samber/cc-skills-golang/golang-project-layout/security/snyk)Installed onopencode700cursor694codex691gemini-cli689github-copilot688amp687 --- *Source: https://skills.yangsir.net/skill/daily-golang-project-layout* *Markdown mirror: https://skills.yangsir.net/api/skill/daily-golang-project-layout/markdown*