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

> Learn the AI agent workflow using Go Modern Guidelines list and explain commands. Discover identifiers, filter by version or path, and get detailed recommendations with code examples.

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

---

**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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) (lines 48‑86). When invoked, it calls `guidelines.ListText` as implemented in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) (lines 63‑66) to retrieve the formatted list.

```bash
go run . list

```

*Typical output:*

```text
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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) (lines 61‑77) with the error message `listVersionSourceConflictError`.

```bash
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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) (lines 88‑110) and forwards the IDs to `guidelines.ExplainText` in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) (lines 76‑82).

**Explain a single guideline:**

```bash
go run . explain atomic_types

```

**Explain multiple guidelines using the repeatable flag:**

```bash
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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) (lines 34‑38, 46‑52) and [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) (lines 65‑77).

## Core Implementation Files

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

## Complete Automated Workflow Example

```go
// 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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go)
- **Filtering**: Apply `--go-version` or `--file-path` to narrow results, with conflict validation in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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.