Building Guardrails for AI Coding Agents in Go

Creating automated checks for recurring code review comments in Go is essential to ensure code quality and efficiency. This Go repository combines linter configurations, behavioral tests, an architecture test, and scripts to validate the checks against deliberate errors. The checks, referred to as guardrails, ensure that code changes meet specific conditions before acceptance.

For instance, a goroutine must stop upon cancellation, and a rule requiring independent calculations incorporates a test of the package dependency graph. When an agent receives a diagnostic, it can act on the issue, and re-running the same check after a fix helps verify the resolution. However, a passing test might miss a bug, while a failing command could indicate a build error or timeout.

The article provides a step-by-step guide to constructing these checks, establishing their detection capabilities, and identifying decisions still requiring human review. It assumes familiarity with Go tests, contexts, channels, and CI processes. The repository includes source code, configurations, and reproduction commands. The terminal output was generated using Go 1.27.1 and golangci-lint 2.13.2, which are pinned for reproducibility.

The guardrails include formatting and naming checks, ensuring adherence to agreed-upon conventions. Naming rules can inspect source code, while complexity and duplication flags flag code that exceeds agreed limits or repeats existing logic. Static analysis and controlled failures follow, focusing on concurrency, resource handling, synchronization, and architecture compliance.

Verification scripts validate guardrails by creating faulty variants, running relevant commands, and inspecting their diagnostics. Separate cases are used to ensure that build errors and timeouts are rejected as evidence of a violation.

To automate formatting and naming checks, tools like gofmt and revive are employed. gofmt applies standard Go formatting, while revival checks naming conventions, such as capitalizing initialisms. The checks can be run using commands like `gofmt -w .` for formatting and `golangci-lint run --config naming.yml ./testdata/naming` for naming rules. The resulting diagnostics can then be checked against specific naming violations.

The overall workflow relies on ordinary tests and linters as input for code changes, with verification scripts as an additional layer for detecting violations. By separating purposes and ensuring tools are properly pinned, developers can efficiently maintain code quality and reliability.