Recommended Workflow for AI Agents Using the `list` and `explain` Commands in Go Modern Guidelines

AI agents should first execute the list command to discover available guideline identifiers, optionally filter by Go version or file path, then invoke explain with specific IDs to retrieve detailed recommendations including summaries and code examples.

The JetBrains/go-modern-guidelines repository provides a CLI tool designed for automated analysis of Go codebases. Understanding the recommended workflow for AI agents using the list and explain commands enables programmatic discovery and retrieval of modern Go coding standards tailored to specific project versions.

Step 1: Discover Available Guidelines with list

Run the list command to obtain a concise table of guideline identifiers applicable to a specific Go version or project file. This serves as the entry point that tells the agent which IDs can be queried later.

The command parsing logic resides in internal/cli/cli.go (lines 48‑86). When invoked, it calls guidelines.ListText as implemented in internal/guidelines/guidelines.go (lines 63‑66) to retrieve the formatted list.

go run . list

Typical output:

atomic_types: Prefer atomic types over the sync/atomic package
error_wrapping: Wrap errors with %w in fmt.Errorf

Step 2: Filter by Target Version or File

Optionally supply --go-version, --file-path, or a positional file path to restrict the list to the version the agent is analyzing. This filters out guidelines that are not yet relevant, ensuring the agent only works with supported recommendations.

Conflict handling for mutually exclusive flags lives in internal/cli/cli.go (lines 61‑77) with the error message listVersionSourceConflictError.

go run . list --go-version=1.27

Only guidelines whose sinceVersion is less than or equal to 1.27 are displayed.

Step 3: Parse the Output

Read the output lines formatted as <id>: <short description>. Extract the <id> values required for the next step. IDs are the unique keys used by the explain command; accurate extraction is essential for subsequent retrieval.

Step 4: Retrieve Detailed Guidance with explain

Invoke explain with one or more guideline IDs (either via --guideline-id repeats or as positional arguments). The agent receives a rich, multi-section explanation: summary, details, and concrete before/after code examples.

The explain command is implemented in internal/cli/cli.go (lines 88‑110) and forwards the IDs to guidelines.ExplainText in internal/guidelines/guidelines.go (lines 76‑82).

Explain a single guideline:

go run . explain atomic_types

Explain multiple guidelines using the repeatable flag:

go run . explain --guideline-id=atomic_types --guideline-id=error_wrapping

Both guidelines are rendered back-to-back, separated by a blank line.

Step 5: Render or Consume Results

The explain output is a formatted block that can be parsed programmatically (e.g., split on double-newlines) or displayed directly to a user. The agent can now either present the guidance to a human or feed it into downstream tooling such as an automated refactoring engine.

Step 6: Handle Errors Robustly

If the agent supplies an unknown ID or contradictory flags, the CLI returns clear error messages such as "unknown Go modern code guideline ids…" or "list accepts only one Go version source". Robust error handling lets the agent capture these and retry with corrected parameters.

Error generation occurs in internal/guidelines/guidelines.go (lines 34‑38, 46‑52) and internal/cli/cli.go (lines 65‑77).

Core Implementation Files

• internal/cli/cli.go: CLI parsing, command dispatch, flag conflict handling, and orchestration of list and explain. View source
• internal/guidelines/guidelines.go: Core data model, loading of embedded guidelines.json, and implementation of ListText, ExplainText, and version filtering logic. View source
• internal/guidelines/schema/schema.go: JSON schema parsing for the guideline definitions used by mustLoadModernGoGuidelines. View source
• internal/goversion/goversion.go: Version comparison utilities (goversion.Compare) that power the version-filtering in list. View source

Complete Automated Workflow Example

// 1. Run list and capture IDs
listOut, _ := exec.Command("go", "run", ".", "list", "--go-version=1.26").Output()
ids := parseIDs(string(listOut))          // e.g. []string{"atomic_types"}

// 2. Run explain for the first ID
explainOut, _ := exec.Command("go", "run", ".", "explain", ids[0]).Output()
fmt.Println(string(explainOut))           // Detailed guidance with examples

Summary

• Discovery: Use list to retrieve available guideline IDs via guidelines.ListText in internal/guidelines/guidelines.go
• Filtering: Apply --go-version or --file-path to narrow results, with conflict validation in internal/cli/cli.go lines 61‑77
• Extraction: Parse <id>: <description> lines to collect unique identifiers for the next phase
• Retrieval: Call explain to invoke guidelines.ExplainText for full guidance including summaries and code examples
• Integration: Process formatted output programmatically or display to users for manual review
• Resilience: Handle listVersionSourceConflictError and unknown ID errors generated in internal/guidelines/guidelines.go lines 34‑52

Frequently Asked Questions

How does an AI agent filter guidelines for a specific Go version?

The agent passes the --go-version flag to the list command, which uses goversion.Compare from internal/goversion/goversion.go to evaluate each guideline's sinceVersion field. Only guidelines with versions less than or equal to the target are returned, ensuring compatibility with the analyzed codebase.

What happens if an agent provides conflicting version sources?

The CLI detects conflicts in internal/cli/cli.go (lines 61‑77) and returns the listVersionSourceConflictError message stating "list accepts only one Go version source". The agent must choose between using --go-version, --file-path, or a positional argument, but cannot combine them simultaneously.

Can an AI agent retrieve explanations for multiple guidelines at once?

Yes. The agent can pass multiple --guideline-id flags or provide multiple positional arguments to the explain command. The guidelines.ExplainText function in internal/guidelines/guidelines.go (lines 76‑82) processes each ID sequentially and returns formatted blocks separated by blank lines.

How should an agent parse the structured output from these commands?

For list, split lines on the colon delimiter to separate IDs from descriptions. For explain, split the output on double-newlines to isolate sections (summary, details, examples), or treat the entire block as structured text for consumption by downstream systems.

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