skills.rest
titaneric
titanericCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

golang-project-layout

Guides Go project structure, module naming, and workspace setup decisions.

1|Updated May 25, 2020
Search Tags:#golang#monorepo#12-factor#directory structure#project layout#go.work#go modules
One-click install
npx skills add https://github.com/titaneric/dotfiles --skill golang-project-layout-titaneric
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: golang-project-layout
Source: https://github.com/titaneric/dotfiles/tree/main/dot_agents/skills/golang-project-layout
Command: npx skills add https://github.com/titaneric/dotfiles --skill golang-project-layout-titaneric

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and assets (resource) components.

What problem does it solve? Starting or reorganizing a Go project often leads to inconsistent directory structures, misplaced business logic in main packages, and confusion over cmd/, internal/, and pkg/ conventions. This Skill provides opinionated, right-sized guidance so projects follow idiomatic Go layout from day one. ## Core Features & Use Cases - Architecture-First Workflow: Prompts the developer to choose an architecture (clean, hexagonal, DDD, flat) and a dependency injection approach before imposing any structure. - Layout Templates: Provides universal, small-project, library, and monorepo layouts with rules for cmd/, internal/, pkg/, and go.work workspaces. - Ready-to-Use Assets: Ships a Makefile template and .gitignore template, plus references for Cobra/Viper configuration, test file placement, and 12-Factor App conventions. - Use Case: When scaffolding a new Go microservice, the Skill asks about architecture and DI preferences, then generates a cmd/server entry point, internal/ business logic packages, and a Makefile with build, test, and lint targets. ## Quick Start Ask the agent to set up the directory structure for a new Go CLI tool or web service using this skill.

Frequently Asked Questions about golang-project-layout

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure a new Go project with cmd, internal, and pkg directories?▼

Place all main packages under cmd/{name}/ with minimal logic that only parses flags, wires dependencies, and calls Run(). Put private business logic in internal/ and use pkg/ only for code genuinely useful to external consumers.

What is the difference between internal and pkg in Go projects?▼

internal/ holds non-exported code that Go itself prevents external modules from importing, while pkg/ is for libraries intended for outside consumers. Default to internal/ for service and business logic; use pkg/ sparingly.

When should I use go.work workspaces in a Go monorepo?▼

Use go.work when developing multiple related Go modules that import each other, such as a monorepo with separate modules per package. Do not use workspaces for single-module projects or simple applications with only external dependencies.

Where should test files go in a Go project?▼

Co-locate _test.go files in the same directory as the code they test, using either the same package for white-box tests or a _test package suffix for black-box tests. Use a testdata/ directory for fixtures, which Go ignores during builds.

Should I put configuration secrets in a Viper config.yaml file?▼

No. Sensitive values like database passwords, API keys, and JWT secrets must come from environment variables or a secret manager, never config files. Config files are acceptable only for non-sensitive values like ports and log levels.

How do I organize multiple binaries in one Go repository?▼

Create a separate subdirectory under cmd/ for each binary, such as cmd/server/, cmd/cli/, and cmd/migrate/, each with its own main.go. Build them individually with go build ./cmd/server or all at once with go build ./cmd/....

Related Skills

Explore More Software Engineering Skills→
GoogleCloudPlatformGoogleCloudPlatform
1.1k

update-go-version

Updates Go and toolchain versions across modules, workspaces, Dockerfiles, and setup scripts.

Official
Intermediate
lmorchardlmorchard
3

go-cli-builder

Scaffold Go CLI projects with Cobra, Viper, SQLite, and GitHub Actions.

Community
Advanced
xu-xiangxu-xiang
1.9k

golang-patterns

Applies idiomatic Go patterns for error handling, concurrency, interfaces, and package design.

Community
Intermediate
vesvietvesviet

navigate-service

Navigate and explain Go Kratos microservice architecture layers and key components.

Community
Intermediate