golang-project-layout

Guide Go project structuring with cmd/, internal/, and pkg/ conventions.

2|Updated Feb 12, 2024

Search Tags:#go #12-factor #project layout #module naming #go.work #cmd-internal-pkg #testing layout

Ready to run

npx skills add https://github.com/adibfirman/dotfiles --skill golang-project-layout-adibfirman

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: golang-project-layout
Source: https://github.com/adibfirman/dotfiles/tree/main/claude/.claude/skills/technical/golang/golang-project-layout
Command: npx skills add https://github.com/adibfirman/dotfiles --skill golang-project-layout-adibfirman

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

It helps you design a maintainable, idiomatic Go project layout so your codebase stays organized as it grows—without over-structuring early.

Core Features & Use Cases

Project-type layout guidance: Choose a structure for CLI tools, libraries, services, monorepos, or multi-module workspaces.
Correct Go conventions: Enforce module naming rules, package naming (lowercase, singular), and keep cmd/ focused on wiring only.
Practical engineering decisions: Decide between internal/ vs pkg/, co-locate tests with code, and apply 12-Factor conventions for services.
Team-ready setup: Establish essential root files like Makefile, .gitignore, and golangci-lint configuration, plus workspace guidance for multi-module repos.

Quick Start

Ask a question to an AI agent: "Given my repository URL is github.com/example/my-tool and I’m building a small Go CLI with a few subcommands, propose an idiomatic directory layout and explain what should go in cmd/, internal/, pkg/, and tests/."

Frequently Asked Questions about golang-project-layout

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

FAQPage Schema

What is the best way to structure a Go project to avoid over-engineering early?▼

Use a right-sized Go project layout that matches real architectural needs. This prevents over-structuring early by applying idiomatic conventions like `cmd/` for wiring and `internal/` for private packages, keeping the codebase maintainable.

How do I decide between using internal/ vs pkg/ when organizing Go packages?▼

Decide between `internal/` vs `pkg/` by limiting `internal/` to private application code and reserving `pkg/` for reusable public libraries. This ensures correct Go conventions and practical engineering decisions for your codebase boundaries.

Does my Go monorepo need go.work for multi-module workspaces?▼

Your Go monorepo needs `go.work` for optional multi-module workspaces. It enables local development across modules without modifying module naming rules or `go.mod` dependencies, ensuring correct workspace usage.

How do I set up a Go CLI tool directory layout with cmd/ and internal/?▼

Set up a Go CLI tool by keeping `cmd/` focused only on wiring and placing business logic in `internal/`. Apply correct module and package naming conventions, like lowercase singular names, to maintain an idiomatic directory layout.

Can I apply 12-Factor app rules when structuring Go services?▼

You can apply 12-Factor app rules when structuring Go services. The layout guidance ensures services follow configuration and statelessness principles while co-locating tests with code for practical engineering decisions.

What root files do I need to establish a team-ready Go project setup?▼

To establish a team-ready Go project, you need a Makefile, .gitignore, and golangci-lint configuration. These root files support practical engineering decisions and standardize testing layout and workspace guidance.