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

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 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, 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 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, 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.

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.

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, which is embedded directly into the binary using the //go:embed directive. The guidelines.go module loads this data at runtime through supportedGuidelines, eliminating external dependencies and ensuring offline operation. The 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:

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

Explain multiple guidelines simultaneously:

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

Retrieve details for the project's current Go version:

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, 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 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. The binary embeds this file using the //go:embed directive, and internal/guidelines/guidelines.go loads and parses it at runtime without requiring external files or network connectivity.

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