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

> Explore the structure of the go-modern-guidelines repository. Discover how CLI, guideline data, and Go version resolution are organized for a clear, purpose-driven architecture. Learn more today.

- Repository: [JetBrains/go-modern-guidelines](https://github.com/jetbrains/go-modern-guidelines)
- Tags: technical-guide
- Published: 2026-08-29

---

**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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/dev-install.sh) and build automation

## Core Package Architecture

### The Entry Point (main.go)

Located at the repository root, [`main.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.go)** – Implements `mustLoadModernGoGuidelines()` which uses the `//go:embed` directive to bundle [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) into the compiled binary. This file also exports `ListText()` for generating version-filtered summaries and `ExplainText()` for detailed guidance lookup.
- **[`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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

```bash

# 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

```go
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

```go
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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/main.go) acts as a minimal bootstrap that delegates to `cli.Run` in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go)
- Guideline data lives in [`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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.