golang-project-layout
Provides a guide for setting up Golang project layouts and workspaces. Use this whenever starting a new Go project, organizing an existing codebase, setting up a monorepo with multiple packages, creating CLI tools with multiple main packages, or deciding on directory structure. Apply this for any Go project initialization or restructuring work.
- License 许可
- MIT
- 所属仓库
- muratovv/ai-hats
- 最近更新
- 2026-11-05
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- golang-project-layout
- license
- MIT
- metadata
- { "author": "samber", "version": "1.1.3" }
- description
- Provides a guide for setting up Golang project layouts and workspaces. Use this whenever starting a new Go project, organizing an existing codebase, setting up a monorepo with multiple packages, creating CLI tools with multiple main packages, or deciding on directory structure. Apply this for any Go project initialization or restructuring work.
- allowed-tools
- Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent AskUserQuestion
- compatibility
- Designed for Claude Code or similar AI coding agents, and for projects using Golang.
- user-invocable
- true
02 资源文件 9
- 资产文件assets/.gitignore421 B
- 资产文件assets/Makefile2.5 KB
- 参考文档evals/evals.json11.7 KB
- 许可证LICENSE1.0 KB
- 参考文档metadata.yaml651 B
- 参考文档references/config.md1.4 KB
- 参考文档references/directory-layouts.md4.6 KB
- 参考文档references/testing-layout.md5.1 KB
- 参考文档references/workspaces.md2.5 KB
03 SKILL.md 正文
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 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(notMyApp) - Use hyphens for multi-word:
user-authnotuser_authoruserAuth - 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 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
- .gitignore — git ignore patterns. See .gitignore template
- .golangci.yml — linter config. See the
samber/cc-skills-golang@golang-linterskill for the recommended configuration
For application configuration with Cobra + Viper, see config reference.
Tests, Benchmarks, and Examples
Co-locate _test.go files with the code they test. Use testdata/ for fixtures. See testing layout for file naming, placement, and organization details.
Go Workspaces
Use go.work when developing multiple related modules in a monorepo. See workspaces 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-injectionskill - [ ] 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 versionto detect the current go version - [ ] Run
go mod init github.com/user/project-name - [ ] Create
cmd/{name}/main.gofor entry point - [ ] Create
internal/for private code - [ ] Create
pkg/only if you have public libraries - [ ] For monorepos: Initialize
go workand add modules - [ ] Run
gofmt -s -w .to ensure formatting - [ ] Add
.gitignorewith/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.
04 同仓库更多 Skills
tool-evaluation-protocol
Time-bounded protocol for evaluating new tools, libraries, or methodologies before adoption. Use when evaluating a candidate dependency for the project, researching a methodology (e.g. ML/LLM frameworks, testing approaches), or following up on a hype-driven recommendation.
systematic-debugging
4-phase bug-fix protocol (evidence, pattern, hypothesis, verify). Use when investigating any error, failure, or unexpected behavior, handling bug reports from users or monitoring, or diagnosing test failures with non-obvious causes.
skill-template
Canonical template and validation guide for ai-hats skills. Use when creating a new skill, reviewing an existing one for structural compliance, or deciding which pattern fits a new behavior.
skill-optimization
Audit and refactor library components to eliminate redundancy and staleness. Use during periodic library maintenance, after adding multiple new skills or rules, when a role's token budget is too high, or after retrospectives identify component issues.
silent-fallback-gate
PreToolUse hook — refuses an Edit or Write that adds an inert broad except. Use when a Python edit was blocked for a silent fallback.
retro-to-framework
Convert an observation about agent behavior — from a retrospective or from a single incident — into a framework-level change (hook, rule, skill, skill update). Use after a retrospective identifies problems that are not project-specific, after an incident where an agent misapplied a component it had read, when CLAUDE.md band-aids accumulate (more than 3 per-project rules that could be generic), or when the same problem recurs across multiple projects.