Enable AI coding agents to write modern Go syntax
This repository provides a set of guidelines that help AI agents utilize the latest features from Go 1.0 through 1.27. It ensures that agents check the project's Go version and prioritize modern syntax and standard library functions available in that version, reducing the need for manual fixes of outdated code.
Why AI writes outdated Go
AI coding agents generate outdated Go code for two reasons. First, there is a time lag in training data; models do not know about features added after their training cutoff, such as errors.AsType[T] introduced in Go 1.26. Second, frequency bias means models are more likely to select older patterns like for i := 0; i < n; i++ because they appear more frequently in training data. These guidelines provide explicit reference material to address both issues. They share the goal of the Go team's modernize analyzer, which updates existing code to modern syntax, by ensuring new code is written with modern Go from the start to reduce future maintenance.
Modern syntax applied by agents
The guidelines cover useful features from Go 1.0 to 1.27, including all items handled by the modernize analyzer. Agents detect the project's Go version from the go.mod file and use language features and standard library additions available up to that version. For example, they use max(a, b) instead of if-else blocks, slices.Contains instead of manual loops, and cmp.Or(a, b, c) instead of nil check chains. They also apply modern features like obtaining a pointer to a value with new(42) or using errors.AsType[T](err) for type-safe error matching. The detailed feature list and examples are available in the FEATURES.md file.
Installation for supported agents
The guidelines support Junie, Claude Code, Codex, and Cursor, and can be applied to other agents via skills.sh. Each agent requires different commands to add the repository to its marketplace and install the plugin. In the Junie CLI, use the /extensions marketplace add and /extensions install commands. Cursor requires adding the marketplace in the terminal and then installing via the /plugins command within a session.
Runtime environment and developer settings
Marketplace integration installs a small CLI via go install on first use, so the Go toolchain must be installed and included in the PATH. The CLI is installed in a local cache (e.g., ~/.cache/go-modern-guidelines) and does not modify project files. While targeting Go 1.25 or later, it runs on older Go versions if automatic toolchain switching (GOTOOLCHAIN=auto) is enabled. When this variable is set, the agent uses the local build instead of the release version. The build script is intentionally separated to prevent agents from triggering builds.
Pre-implementation checks
This repository is suitable for developers using AI coding agents for Go projects, particularly teams that prefer modern Go syntax but face issues with AI generating outdated code. Before use, verify that the Go toolchain is installed on the system and that the agent is one of Junie, Claude Code, Codex, or Cursor, or supports skills.sh. If the Go version is lower than 1.25, check if automatic toolchain switching is enabled. These guidelines serve as a reference for agents when generating code, not as a tool for automatically modifying code, so they cannot be used to bulk update existing codebases.
