skills.rest
dmwin72015
dmwin72015COMMUNITY
Explore all skills by this author →
WebsiteGitHub

golang-project-layout

Guide Go repository structure with cmd, internal, and pkg conventions.

1|Updated May 27, 2026
Search Tags:#architecture#go#project layout#go.mod#go.work#cmd internal pkg#testing conventions
One-click install
npx skills add https://github.com/dmwin72015/netdisk --skill golang-project-layout-dmwin72015
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: golang-project-layout
Source: https://github.com/dmwin72015/netdisk/tree/main/.agents/skills/golang-project-layout
Command: npx skills add https://github.com/dmwin72015/netdisk --skill golang-project-layout-dmwin72015

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

It helps you avoid messy Go repositories by providing a practical, conventions-based directory and module layout that scales from small tools to multi-binary services without over-engineering.

Core Features & Use Cases

  • Architecture-first structuring: Prompts you to confirm the desired architecture and scope before choosing a layout, preventing premature complexity.
  • Clear conventions for modules and packages: Enforces module naming rules (match repo URL, lowercase, hyphens) and package naming expectations to keep imports predictable.
  • Correct placement of main vs logic: Ensures all main packages live under cmd/ with minimal startup wiring, while business logic stays in internal/ or pkg/ as appropriate.
  • Project-type specific guidance: Covers CLI tools, libraries, services, workspaces/monorepos, and testing placement rules (including _test.go co-location and testdata/).
  • Guardrails against common mistakes: Flags anti-patterns like using a Java-style src/, generic folder names like utils/common, misplaced secrets, and incorrect config/log handling for services.

Quick Start

Ask the AI to propose a Go layout for your project by stating whether it is a CLI tool, library, or service, and what architecture and DI approach you prefer, then request a concrete cmd/ and internal/ directory plan plus the correct go.mod module path.

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 Go project with cmd, internal, and pkg directories?▼

To structure a Go project, place all `main` packages under `cmd/` with minimal startup wiring, keep business logic in `internal/` or `pkg/`, and match the `go.mod` module path to your repository URL for predictable imports.

What is the standard project layout for a multi-module Go monorepo?▼

A multi-module Go monorepo uses `go.work` to manage local development workflows across modules, enforcing lowercase hyphenated module naming and correct `cmd/internal/pkg` placement to keep the architecture maintainable.

How do I organize tests and testdata in a Go service repository?▼

Organize Go tests by co-locating `_test.go` files with their source code and placing fixed test assets in a `testdata/` directory, applying conventions uniformly across CLI tools, libraries, and services.

What are common Go project layout anti-patterns I should avoid?▼

Common Go project layout anti-patterns to avoid include using a Java-style `src/` directory, creating generic package names like `utils` or `common`, and misplacing secrets or configuration files within business logic directories.

When should I use go.work instead of go.mod for my Go project?▼

Use `go.work` instead of individual `go.mod` files when setting up monorepos or multi-module development workflows to manage local dependencies, while standalone CLI tools or libraries typically require only a single `go.mod`.

Related Skills

Explore More Software Engineering Skills→
svangesvange
1

ai-init

Initialize and configure ai-shell for new repositories or workspaces.

Community
Intermediate
vanstinatorvanstinator

golang-project-layout

Guide Go repository directory structures with cmd/, internal/, pkg/, and configs/ conventions.

Community
Intermediate
TencentBlueKingTencentBlueKing
2.5k

backend-microservice-development

Standardize Kotlin/Java backend microservices with a four-layer package structure.

Official
Advanced
sambersamber
2.9k

golang-project-layout

Identify and apply optimal Go project layouts for single-module and monorepo structures.

Community
Intermediate