Skip to content

dirien/yet-another-agent-harness / .claude/skills/agent-ready-go

agent-ready-go

Verified

Prepares Go applications to work effectively with AI coding agents. Use when setting up a new Go project or retrofitting an existing one to ensure: structured JSON logging (slog/Zap/ZeroLog/Logrus), machine-readable command output, thorough golangci-lint configuration, non-interactive CLI design with --yes flags, structured error handling with meaningful exit codes, proper context.Context propagation, graceful shutdown, health check endpoints, and a standardized Makefile. Triggers when a user asks to make their Go app "agent-ready," "AI-friendly," wants to improve agent tooling/observability in a Go project, or needs to audit an existing Go project against agent-readiness best practices.

FileKindSize
SKILL.mdskill md6.3 KB
assets/Makefileother2.5 KB
references/config.mdmarkdown4.0 KB
references/error-handling.mdmarkdown5.6 KB
references/logging.mdmarkdown7.1 KB
references/non-interactive.mdmarkdown4.8 KB
references/services.mdmarkdown5.8 KB
references/testing.mdmarkdown6.5 KB

references/config.md

View on GitHub
<!-- Copyright 2025-2026 Richard Shade. Licensed under Apache-2.0. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
# Configuration Management for Agent-Ready Go

## Priority Order

Apply configuration in this order — later sources override earlier ones:

1. **Default value** — compiled into the binary
2. **Config file** — optional, for complex multi-field configuration
3. **Environment variable** — the primary mechanism for agents and containers
4. **Explicit flag** — highest precedence, passed directly by the caller

For most services and CLI tools, environment variables alone are sufficient.
Reach for a config file only when you have more than ~10 settings.

## Struct-Based Config

Define a typed struct with `env` tags and parse it with
`github.com/caarlos0/env/v11` — a lightweight library with no external
dependencies and good error messages:

```bash
go get github.com/caarlos0/env/v11
```

```go
package config

import (
    "errors"
    "fmt"
    "time"

    "github.com/caarlos0/env/v11"
)

type Config struct {
    Port     int           `env:"PORT"          envDefault:"8080"`
    LogLevel string        `env:"LOG_LEVEL"     envDefault:"info"`
    DBURL    string        `env:"DATABASE_URL"  required:"true"`
    Timeout  time.Duration `env:"TIMEOUT"       envDefault:"30s"`
    Debug    bool          `env:"DEBUG"         envDefault:"false"`
}

func Load() (*Config, error) {
    cfg := &Config{}
    if err := env.Parse(cfg); err != nil {
        return nil, fmt.Errorf("loading config: %w", err)
    }
    return cfg, nil
}
```

All fields are type-safe — durations and booleans are parsed automatically.
Missing `required` fields produce a clear error message that agents can act on.

## Validation

Add a `Validate` method to catch logical errors that the `env` parser cannot
detect (range checks, cross-field constraints, etc.):

```go
func (c *Config) Validate() error {
    var errs []error
    if c.Port < 1 || c.Port > 65535 {
        errs = append(errs, fmt.Errorf("PORT %d out of range [1-65535]", c.Port))
    }
    if c.DBURL == "" {
        errs = append(errs, errors.New("DATABASE_URL is required"))
    }
    return errors.Join(errs...)
}
```

## Config in main()

Load and validate configuration at the very top of `main`. Fail fast with exit
code `2` so the process never starts partially configured — agents see an
immediate, unambiguous failure:

```go
package main

import (
    "fmt"
    "os"

    "github.com/example/myapp/internal/config"
)

func main() {
    cfg, err := config.Load()
    if err != nil {
        fmt.Fprintf(os.Stderr, "config error: %v\n", err)
        os.Exit(2)
    }
    if err := cfg.Validate(); err != nil {
        fmt.Fprintf(os.Stderr, "invalid config: %v\n", err)
        os.Exit(2)
    }

    // cfg is valid — pass it to the rest of the application.
    if err := run(cfg); err != nil {
        fmt.Fprintf(os.Stderr, "error: %v\n", err)
        os.Exit(1)
    }
}
```

## When to Use Viper

[Viper](https://github.com/spf13/viper) is appropriate when you need **all
three** of: config files (TOML/YAML/JSON), environment variables, **and** CLI
flags in a single unified system — typically large CLIs or daemon processes with
rich configuration.

For simpler cases, prefer the struct-based approach above:

| Scenario | Recommendation |
| -------- | -------------- |
| Container / 12-factor app (env vars only) | `caarlos0/env` struct |
| CLI with a few flags and env var overrides | `pflag` / `cobra` + env defaults |
| Daemon with a config file + env overrides | Viper |
| Multi-command CLI with subcommand configs | Viper |

Viper example (minimal):

```go
import "github.com/spf13/viper"

viper.SetConfigName("config")
viper.SetConfigType("yaml")
viper.AddConfigPath(".")
viper.AutomaticEnv() // env vars override file values

if err := viper.ReadInConfig(); err != nil {
    // config file is optional — only fail on parse errors
    var notFound viper.ConfigFileNotFoundError
    if !errors.As(err, &notFound) {
        return fmt.Errorf("reading config: %w", err)
    }
}

port := viper.GetInt("port")
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall