How the go-modern-guidelines Repository Is Structured: A Complete Technical Guide

The go-modern-guidelines repository follows a clean, purpose-driven architecture that separates CLI command handling in internal/cli/, guideline data management in internal/guidelines/, and Go version resolution in internal/goversion/, all orchestrated by a minimal main.go entry point.

The JetBrains/go-modern-guidelines project provides a lightweight CLI tool and embeddable library for surfacing modern Go idioms based on target version constraints. Understanding the go-modern-guidelines repository structure reveals how the tool bundles guideline data, resolves version constraints from project files, and exposes both a command-line interface and a plugin system for AI agents.

Repository Layout Overview

The repository organizes code into distinct internal packages following Go best practices for maintainable command-line tools. This separation of concerns allows you to modify version detection logic, extend guideline data, or change output formatting without affecting other components.

• main.go – The binary entry point at the repository root, responsible only for bootstrapping
• internal/cli/ – Implements user-facing commands (list, explain, --version, --help) and output formatting
• internal/guidelines/ – Houses the embedded JSON data store and loading logic via //go:embed
• internal/goversion/ – Provides version string parsing and resolution from go.mod or go.work files
• plugin/ – Contains agent integration definitions for Junie, Claude Code, Codex, and Cursor
• scripts/ – Development helpers including dev-install.sh and build automation

Core Package Architecture

The Entry Point (main.go)

Located at the repository root, main.go serves as a minimal bootstrap that delegates immediately to the CLI layer. According to the source code, this file contains only the essential wiring to forward execution to cli.Run, keeping the binary entry point thin and maintainable.

CLI Implementation (internal/cli/)

The internal/cli/cli.go file implements the primary user interface logic. This package handles flag parsing for commands like go-modern-guidelines list and go-modern-guidelines explain, validates arguments, and coordinates between the version resolution and guideline retrieval systems.

The core cli.Run function serves as the main dispatch point for both the compiled binary and programmatic consumers. When users invoke the list command, the internal runList function orchestrates the filtering and display logic.

Guideline Engine (internal/guidelines/)

This package contains the heart of the system and leverages Go's embedded filesystem capabilities:

• guidelines.go – Implements mustLoadModernGoGuidelines() which uses the //go:embed directive to bundle guidelines.json into the compiled binary. This file also exports ListText() for generating version-filtered summaries and ExplainText() for detailed guidance lookup.
• guidelines.json – The raw data store containing all modern Go guidelines with metadata fields including since_version, which determines when a feature became available.

Version Resolution (internal/goversion/)

The internal/goversion/goversion.go file provides the goversion.Resolve function, which parses Go version strings from go.mod, go.work, or explicit --go-version flags. This decoupled approach ensures the CLI can accurately filter guidelines based on the target Go version without embedding filesystem logic in the command handlers.

Plugin System (plugin/)

The plugin/ directory includes skill definitions that allow AI agents to consume guidelines as a marketplace plugin. The plugin/skills/use-modern-go/SKILL.md file describes integration patterns for agents such as Junie, Claude Code, Codex, and Cursor.

Execution Flow Through the Architecture

The runtime operation follows a clear pipeline pattern that demonstrates the separation of concerns in the codebase:

1. Bootstrap – main.main invokes cli.Run with command-line arguments and output streams
2. Version Detection – cli.runList calls goversion.Resolve to determine the target Go version from filesystem context or explicit flags
3. Data Loading – guidelines.mustLoadModernGoGuidelines reads the embedded guidelines.json resource
4. Filtering – The system computes supportedGuidelines by comparing each guideline's since_version against the resolved Go version
5. Rendering – ListText or ExplainText format the filtered results for terminal output

This architecture makes it easy to add new guidelines by simply extending guidelines.json without modifying Go source code, or to change version-resolution logic without touching CLI formatting.

Practical Usage Examples

You can interact with the repository's code both as a CLI tool and as an embeddable library.

Command-Line Usage

# List guidelines for the Go version detected from go.mod

go-modern-guidelines list

# Target a specific version explicitly

go-modern-guidelines list --go-version 1.26

# Show detailed guidance for specific guideline IDs

go-modern-guidelines explain G001 G005

Embedding in Your Own Go Code

package main

import (
	"fmt"
	"github.com/JetBrains/go-modern-guidelines/internal/guidelines"
)

func main() {
	// Get a short summary for Go 1.27
	fmt.Println(guidelines.ListText("1.27"))

	// Get detailed guidance for a specific guideline
	text, _ := guidelines.ExplainText([]string{"G001"})
	fmt.Println(text)
}

Programmatic CLI Invocation

package main

import (
	"os"
	"github.com/JetBrains/go-modern-guidelines/internal/cli"
)

func main() {
	// Emulate `go-modern-guidelines list`
	cli.Run([]string{"list"}, os.Stdout)
}

Summary

• The repository separates concerns across internal/cli/, internal/guidelines/, and internal/goversion/ packages
• main.go acts as a minimal bootstrap that delegates to cli.Run in internal/cli/cli.go
• Guideline data lives in internal/guidelines/guidelines.json and is embedded using //go:embed
• The goversion.Resolve function handles version detection from go.mod, go.work, or flags
• The plugin/ directory enables AI agent integration through skill definitions
• Both CLI and library APIs are supported for maximum flexibility

Frequently Asked Questions

What is the role of main.go in the repository?

The main.go file serves as the minimal entry point for the compiled binary. It contains only bootstrapping code that immediately forwards execution to cli.Run in the internal/cli package. This pattern keeps the root-level code clean and ensures all command logic remains testable within the internal packages.

How does the tool determine which Go version to use?

The tool uses goversion.Resolve implemented in internal/goversion/goversion.go to parse version strings from go.mod, go.work, or an explicit --go-version flag passed by the user. This function returns the resolved version string that internal/cli uses to filter guidelines whose since_version is less than or equal to the target.

Where are the actual guideline definitions stored?

All guideline definitions reside in internal/guidelines/guidelines.json. This JSON file contains structured data including guideline IDs, descriptions, code examples, and since_version fields. The internal/guidelines/guidelines.go file embeds this data into the binary using the //go:embed directive and provides the loading and formatting logic.

Can I use this as a library in my own Go program?

Yes. The internal/guidelines package exports ListText() and ExplainText() functions that you can call programmatically after importing the module. This allows you to integrate modern Go guideline checking into your own tools without shelling out to the CLI binary.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}