golang-project-layout

Name: golang-project-layout
Author: samber

34kinstalls179forks

How to install golang-project-layout?

samber/cc-skills-golang/golang-project-layout

$npx -y skills add samber/cc-skills-golang --skill golang-project-layout

Installs into the current project.

Summary

Provides a guide for setting up Golang project layouts and workspaces. Use when starting a new Go project, organizing an existing codebase, setting up a monorepo with multiple packages, creating CLI tools with multiple main packages, deciding between cmd/internal/pkg directory co

Files · 1

View on GitHub

SKILL.md

1	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.
2
3	# Go Project Layout
4
5	## Architecture Decision: Ask First
6
7	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.
8
9	→ See `samber/cc-skills-golang@golang-design-patterns` skill for detailed architecture guides with file trees and code examples.
10
11	## Dependency Injection: Ask Next
12
13	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.
14
15	## 12-Factor App
16
17	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/`).
18
19	## Quick Start: Choose Your Project Type
20
21	\| Project Type \| Use When \| Key Directories \|
22	\| --- \| --- \| --- \|
23	\| CLI Tool \| Building a command-line application \| `cmd/{name}/`, `internal/`, optional `pkg/` \|
24	\| Library \| Creating reusable code for others \| `pkg/{name}/`, `internal/` for private code \|
25	\| Service \| HTTP API, microservice, or web app \| `cmd/{service}/`, `internal/`, `api/`, `web/` \|
26	\| Monorepo \| Multiple related packages/modules \| `go.work`, separate modules per package \|
27	\| Workspace \| Developing multiple local modules \| `go.work`, replace directives \|
28
29	## Module Naming Conventions
30
31	### Module Name (go.mod)
32
33	Your module path in `go.mod` should:
34
35	- MUST match your repository URL: `github.com/username/project-name`
36	- Use lowercase only: `github.com/you/my-app` (not `MyApp`)
37	- Use hyphens for multi-word: `user-auth` not `user_auth` or `userAuth`
38	- Be semantic: Name should clearly express purpose
39
40	Examples:
41
42	```go
43	// ✅ Good
44	module github.com/jdoe/payment-processor
45	module github.com/company/cli-tool
46
47	// ❌ Bad
48	module myproject
49	module github.com/jdoe/MyProject
50	module utils
51	```
52
53	### Package Naming
54
55	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.
56
57	## Directory Layout
58
59	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.
60
61	See [directory layout examples](references/directory-layouts.md) for universal, small project, and library layouts, plus common mistakes.
62
63	## Essential Configuration Files
64
65	Every Go project should include at the root:
66
67	- Makefile — build automation. See [Makefile template](assets/Makefile)
68	- .gitignore — git ignore patterns. See [.gitignore template](assets/.gitignore)
69	- .golangci.yml — linter config. See the `samber/cc-skills-golang@golang-lint` skill for the recommended configuration
70
71	For application configuration with Cobra + Viper, see [config reference](references/config.md).
72
73	## Tests, Benchmarks, and Examples
74
75	Co-locate `_test.go` files with the code they test. Use `testdata/` for fixtures. See [testing layout](references/testing-layout.md) for file naming, placement, and organization details.
76
77	## Go Workspaces
78
79	Use `go.work` when developing multiple related modules in a monorepo. See [workspaces](references/workspaces.md) for setup, structure, and commands.
80
81	## Initialization Checklist
82
83	When starting a new Go project:
84
85	- [ ] Ask the developer their preferred software

People who liked this also viewed

6 picks

Type

golang-project-layout

34kinstalls179forks

View on GitHub

How to install golang-project-layout?

samber/cc-skills-golang/golang-project-layout

$npx -y skills add samber/cc-skills-golang --skill golang-project-layout

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	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.
2
3	# Go Project Layout
4
5	## Architecture Decision: Ask First
6
7	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.
8
9	→ See `samber/cc-skills-golang@golang-design-patterns` skill for detailed architecture guides with file trees and code examples.
10
11	## Dependency Injection: Ask Next
12
13	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.
14
15	## 12-Factor App
16
17	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/`).
18
19	## Quick Start: Choose Your Project Type
20
21	\| Project Type \| Use When \| Key Directories \|
22	\| --- \| --- \| --- \|
23	\| CLI Tool \| Building a command-line application \| `cmd/{name}/`, `internal/`, optional `pkg/` \|
24	\| Library \| Creating reusable code for others \| `pkg/{name}/`, `internal/` for private code \|
25	\| Service \| HTTP API, microservice, or web app \| `cmd/{service}/`, `internal/`, `api/`, `web/` \|
26	\| Monorepo \| Multiple related packages/modules \| `go.work`, separate modules per package \|
27	\| Workspace \| Developing multiple local modules \| `go.work`, replace directives \|
28
29	## Module Naming Conventions
30
31	### Module Name (go.mod)
32
33	Your module path in `go.mod` should:
34
35	- MUST match your repository URL: `github.com/username/project-name`
36	- Use lowercase only: `github.com/you/my-app` (not `MyApp`)
37	- Use hyphens for multi-word: `user-auth` not `user_auth` or `userAuth`
38	- Be semantic: Name should clearly express purpose
39
40	Examples:
41
42	```go
43	// ✅ Good
44	module github.com/jdoe/payment-processor
45	module github.com/company/cli-tool
46
47	// ❌ Bad
48	module myproject
49	module github.com/jdoe/MyProject
50	module utils
51	```
52
53	### Package Naming
54
55	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.
56
57	## Directory Layout
58
59	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.
60
61	See [directory layout examples](references/directory-layouts.md) for universal, small project, and library layouts, plus common mistakes.
62
63	## Essential Configuration Files
64
65	Every Go project should include at the root:
66
67	- Makefile — build automation. See [Makefile template](assets/Makefile)
68	- .gitignore — git ignore patterns. See [.gitignore template](assets/.gitignore)
69	- .golangci.yml — linter config. See the `samber/cc-skills-golang@golang-lint` skill for the recommended configuration
70
71	For application configuration with Cobra + Viper, see [config reference](references/config.md).
72
73	## Tests, Benchmarks, and Examples
74
75	Co-locate `_test.go` files with the code they test. Use `testdata/` for fixtures. See [testing layout](references/testing-layout.md) for file naming, placement, and organization details.
76
77	## Go Workspaces
78
79	Use `go.work` when developing multiple related modules in a monorepo. See [workspaces](references/workspaces.md) for setup, structure, and commands.
80
81	## Initialization Checklist
82
83	When starting a new Go project:
84
85	- [ ] Ask the developer their preferred software

People who liked this also viewed

6 picks

Type