How `make dev-install` Rebuilds Local Changes into the Agent's Cache

The make dev-install workflow compiles the current checkout of go-modern-guidelines and places the resulting binary into a per-user cache directory, enabling instant testing of local modifications when the GO_MODERN_GUIDELINES_DEV environment variable is set to 1.

The go-modern-guidelines repository provides a developer-centric workflow for iterating on guideline implementations without disrupting the stable release. When you need to test changes to linting rules or internal logic, the dev-install target rebuilds your local source and injects the fresh binary into a cache that IDE agents can consume. This eliminates the need for full releases or manual binary swaps during active development.

Overview of the Dev-Install Workflow

The workflow bridges your local Git checkout and the IDE agent runtime. Instead of installing a system-wide binary or modifying PATH variables, the mechanism writes the freshly built executable to a deterministic cache location. Agents that respect the GO_MODERN_GUIDELINES_DEV flag automatically prefer this cached build over the bundled release version.

This approach provides three distinct advantages:

• Isolation: The cached binary lives in user space ($HOME/.cache or $XDG_CACHE_HOME) without requiring elevated privileges.
• Atomic updates: The script uses temporary file creation followed by a rename operation, ensuring that running agents never see a partially written binary.
• Instant feedback: Re-running make dev-install after any code change immediately overwrites the cache, and subsequent agent invocations pick up the new version automatically.

Step-by-Step Build Process

The dev-install workflow orchestrates environment detection, compilation, and atomic file placement through the interaction of the Makefile and the scripts/dev-install.sh helper.

Make Target Definition

The entry point resides in the Makefile at lines 18-20, which delegates to the shell script with the install argument:

dev-install:
	@./scripts/dev-install.sh install

This indirection keeps the Makefile declarative while the shell script handles the imperative logic of environment setup and file operations.

Cache Location Resolution

The script determines where to place the binary by checking standard environment variables. According to scripts/dev-install.sh lines 8-12, it resolves the cache root using $XDG_CACHE_HOME or falls back to $HOME/.cache/go-modern-guidelines if the variable is unset. This adheres to the XDG Base Directory Specification while ensuring portability across macOS and Linux environments.

Repository Root Detection

To ensure the build context is correct regardless of the current working directory, the script derives the repository root (module_dir) by traversing one directory up from its own location, as implemented in scripts/dev-install.sh lines 22-24. This technique guarantees that go build executes against the project root containing go.mod, even if you invoke the script from a subdirectory.

Binary Build Step

Inside the resolved module directory, the script executes a sanitized go build command with environment isolation. As shown in scripts/dev-install.sh lines 39-41, it strips potential interference by setting GOFLAGS= and GOWORK=off, while disabling CGO via CGO_ENABLED=0 to ensure a static, portable binary. The output writes to a temporary file named <cache>/dev/go-modern-guidelines.tmp.$$, where $$ provides shell-level process isolation to prevent collisions during concurrent builds.

Atomic Installation

After a successful compilation, the script performs an atomic filesystem operation. Per scripts/dev-install.sh lines 42-45, the temporary file is renamed to <cache>/dev/go-modern-guidelines. This atomic move guarantees that any agent reading the binary path either sees the previous complete version or the new complete version, never a corrupted intermediate state. Upon completion, the script prompts you to export GO_MODERN_GUIDELINES_DEV=1 to enable the dev build.

How Agents Use the Cached Binary

IDE agents (such as the IntelliJ Go plugin) implement a version resolution protocol that checks the environment before launching the tool. When GO_MODERN_GUIDELINES_DEV is set to 1, the agent bypasses the bundled release binary and instead executes the executable found at the cache location. This lookup occurs at runtime, meaning you can edit guideline source files in internal/guidelines/, rebuild with make dev-install, and immediately trigger the updated logic from within your IDE without restarting the plugin or the editor.

Practical Usage Example

The following workflow demonstrates a complete development cycle, from initial cache population through iterative rebuilds:

# Build and install the local checkout into the cache

make dev-install

# Enable the dev binary for the current shell session

export GO_MODERN_GUIDELINES_DEV=1

# Run the tool (the agent will now pick up the cached binary)

go-modern-guidelines lint ./...

# After modifying sources (e.g., in internal/guidelines/), rebuild

make dev-install   # repeat whenever you change code

# When finished testing, remove the dev build

make dev-uninstall

Key Source Files

Understanding the dev-install mechanism requires familiarity with these specific paths in the JetBrains/go-modern-guidelines repository:

• Makefile – Declares the dev-install and dev-uninstall targets that invoke the helper script.
• scripts/dev-install.sh – Performs cache-directory resolution, builds the binary with isolated environment variables, and handles atomic installation/uninstallation.
• internal/guidelines/ – Contains the guideline source implementations; edits here are reflected after rebuilding with make dev-install.

Summary

• make dev-install triggers scripts/dev-install.sh to build the current checkout and cache the binary locally.
• The cache resides at $XDG_CACHE_HOME/go-modern-guidelines or $HOME/.cache/go-modern-guidelines, ensuring per-user isolation.
• The build process uses GOFLAGS= GOWORK=off CGO_ENABLED=0 to produce a clean, static binary written atomically to the cache.
• Setting GO_MODERN_GUIDELINES_DEV=1 instructs agents to load the tool from the cache instead of the released version.
• Re-running the make target overwrites the cached binary, providing immediate feedback on code changes without plugin reloads.

Frequently Asked Questions

Where does make dev-install place the compiled binary?

The script writes the binary to a subdirectory of your user cache. Specifically, it checks $XDG_CACHE_HOME first; if undefined, it defaults to $HOME/.cache/go-modern-guidelines/dev/go-modern-guidelines. This location remains stable across reboots but is specific to your user account.

Why does the build script unset GOFLAGS and GOWORK?

These environment variables are cleared to ensure a deterministic, reproducible build. Disabling workspaces (GOWORK=off) prevents the tool from accidentally compiling against local replace directives in your GOPATH, while clearing GOFLAGS removes any global build tags or compiler flags that might interfere with the standard compilation of the guideline tool.

Do I need to restart my IDE after running make dev-install?

No. The agent checks the GO_MODERN_GUIDELINES_DEV environment variable at execution time. As long as your IDE process inherits the environment where GO_MODERN_GUIDELINES_DEV=1 is exported, the next invocation of the tool will automatically read the fresh binary from the cache directory.

How do I remove the development build and return to the stable release?

Execute make dev-uninstall, which invokes the same shell script with the uninstall argument. This removes the binary from the cache directory. Once the file is deleted, agents will fall back to the bundled release version regardless of the GO_MODERN_GUIDELINES_DEV setting.

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