# What Is the go-modern-guidelines CLI Tool? Purpose and AI Integration

> Discover the go-modern-guidelines CLI tool, JetBrains' modern Go coding guidelines for AI-assisted development. Enable version-aware code generation with list and explain subcommands.

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

---

**The go-modern-guidelines CLI is a lightweight utility that exposes JetBrains' modern Go coding guidelines to AI-assisted development tools, enabling version-aware code generation through `list` and `explain` subcommands.**

The go-modern-guidelines CLI tool bridges the gap between evolving Go language features and automated code generation. Developed by JetBrains within the go-modern-guidelines repository, this command-line interface ensures AI agents like Junie, Claude Code, Codex, and Cursor can access current best practices even when their training data lags behind the latest Go releases.

## Architecture and Entry Point

### Command Dispatch from main.go

The tool’s entry point in [`main.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/main.go) performs a minimal handoff to the core execution logic. It simply forwards all arguments to `cli.Run`, which handles subcommand routing for the two primary operations: `list` and `explain`.

### Version Resolution and Guideline Filtering

The core logic resides in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go), where the application parses flags and resolves the target Go version via `goversion.Resolve`. For the `list` subcommand (lines 48-86), the dispatcher invokes `guidelines.ListText` to retrieve concise summaries, while the `explain` subcommand (lines 88-112) triggers `guidelines.ExplainText` for detailed documentation. Both paths rely on [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) to filter the embedded dataset via `supportedGuidelines` and format output through `toGuidelinesText` or `toGuidelineDetailsText`.

## Core Commands for AI Integration

### Listing Version-Filtered Guidelines

The `list` command returns a concise view of applicable guidelines based on the resolved Go version. The `supportedGuidelines` function filters the embedded data from [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json), ensuring only features available in the project's Go version (up to Go 1.27) are returned. The `toGuidelinesText` formatter presents these as ID-summary pairs, enabling agents to quickly scan applicable modernizations.

```bash
go-modern-guidelines list

```

This outputs guideline IDs and one-sentence summaries, such as references to `slices.Contains` or `cmp.Or` for the detected Go version.

### Explaining Specific Guidelines

The `explain` command provides comprehensive context for specific guideline IDs through the `toGuidelineDetailsText` function. It extracts full descriptions, rationales, and before/after code examples from the embedded JSON. Agents can query single guidelines or multiple comma-separated IDs to receive detailed implementations that align with the official `modernize` analyzer used by the Go team.

```bash
go-modern-guidelines explain --guideline-id G001

```

This returns the full specification for guideline G001, including example transformations from manual loops to `slices.Contains`.

## Data Management and Embedding

All guideline definitions reside in [`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json), which is embedded directly into the binary using the `//go:embed` directive. The [`guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.go) module loads this data at runtime through `supportedGuidelines`, eliminating external dependencies and ensuring offline operation. The [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go) utilities handle semantic version parsing to match guidelines against specific Go releases accurately.

## Practical Usage Examples

Generate a version-specific list:

```bash
go-modern-guidelines list --go-version 1.26

```

Explain multiple guidelines simultaneously:

```bash
go-modern-guidelines explain --guideline-id G001,G002

```

Retrieve details for the project's current Go version:

```bash
go-modern-guidelines explain --guideline-id G003

```

## Summary

- The go-modern-guidelines CLI tool exposes modern Go best practices through `list` and `explain` subcommands designed for programmatic consumption.
- It filters guidelines by Go version using `goversion.Resolve` and `supportedGuidelines` to ensure compatibility with the target codebase.
- Guideline data is embedded via `//go:embed` from [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json), enabling zero-dependency distribution and offline functionality.
- The tool bridges stale AI training data with current Go capabilities up to version 1.27, matching the behavior of the official `modernize` analyzer.

## Frequently Asked Questions

### Which AI development tools support the go-modern-guidelines CLI?

The tool integrates with Junie, Claude Code, Codex, Cursor, and any AI agent capable of executing shell commands. These agents invoke the `list` and `explain` subcommands to retrieve context-aware coding guidance that compensates for outdated training data.

### How does the CLI determine which guidelines apply to my project?

The [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go) module resolves your project's Go version, which the `guidelines` package uses to filter the dataset via `supportedGuidelines`. This ensures only features available in your specific Go version are recommended.

### Can developers use this tool without AI integration?

Yes. While optimized for AI agents, the go-modern-guidelines CLI functions as a standard command-line utility. Developers can run it directly to audit codebases against modern idioms or learn new standard library features introduced in recent Go versions.

### Where is the guideline data stored and how is it accessed?

All definitions live in [`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json). The binary embeds this file using the `//go:embed` directive, and [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) loads and parses it at runtime without requiring external files or network connectivity.