playbooks

home / skills / hoangnguyen0403 / agent-skills-standard / configuration

configuration skill

/skills/golang/configuration

This skill helps you apply 12-Factor, typed config, and secret management guidelines across languages, loading env vars and validating config.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill configuration

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.1 KB
---
name: Configuration
description: Standards for application configuration using environment variables and libraries.
metadata:
  labels: [golang, config, env, viper]
  triggers:
    files: ['configs/**', 'cmd/**']
    keywords: [configuration, env var, viper, koanf]
---

# Golang Configuration Standards

## **Priority: P1 (STANDARD)**

## Principles

- **12-Factor App**: Store config in environment variables.
- **Typed Config**: Load config into a struct, validate it immediately.
- **Secrets**: Never commit secrets. Use env vars or secret managers.
- **No Globals**: Return a Config struct and inject it.

## Libraries

- **Standard Lib**: `os.Getenv` for simple apps.
- **Viper**: Industry standard for complex configs (supports env, config files, remote config).
- **Koanf**: Lighter, cleaner alternative to Viper.
- **Caarlos0/env**: Good for strict struct tagging.

## Pattern

1. Define `Config` struct.
2. Load from defaults.
3. Override from file (optional).
4. Override from Env (priority).
5. Validate.

## References

- [Config Pattern](references/config-patterns.md)

Overview

This skill codifies standards for application configuration using environment variables and proven libraries across languages and frameworks. It emphasizes typed configuration, immediate validation, secret handling, and dependency injection to keep apps predictable and secure. The guidance is practical and implementation-focused for TypeScript and other ecosystems.

How this skill works

The skill inspects configuration handling patterns and recommends a consistent flow: define a typed Config object, load defaults, optionally read files, override from environment variables, then validate. It flags anti-patterns like global config, committed secrets, and unvalidated values, and suggests libraries appropriate for app complexity. Implementation notes include recommended libraries (lightweight and full-featured) and clear validation steps.

When to use it

  • New project setup to establish a consistent config pattern across services.
  • Refactoring legacy code that uses globals or scattered environment access.
  • Enforcing 12-factor best practices for cloud-native deployments.
  • Securing secrets and ensuring they are not stored in source control.
  • Standardizing config loading and validation across multiple languages or frameworks.

Best practices

  • Follow 12-Factor: store runtime config in environment variables, not code.
  • Use a typed Config structure and return it for dependency injection instead of globals.
  • Load defaults, then optional files, then override with environment variables (env has highest priority).
  • Validate config immediately on startup and fail fast on missing or invalid values.
  • Never commit secrets; use env vars or secret managers and restrict access.
  • Choose libraries based on needs: standard lib for simple apps, Viper/Koanf for complex cases, small tag-based libs for strict struct loading.

Example use cases

  • Golang microservice: define a Config struct, use Viper or Koanf to merge file and env, validate required fields, inject into components.
  • TypeScript backend: map env vars to a typed config interface, validate with schema validators, and export factory that returns the config instance.
  • Mobile apps: keep build-time defaults separate and inject runtime secrets via secure stores and environment-like mechanisms during CI/CD.
  • Monorepo with multiple services: standardize the load-override-validate flow to reduce deployment errors and environment drift.

FAQ

Should I ever use global variables for configuration?

Avoid globals. Return a typed Config and inject it where needed; this improves testability and limits hidden dependencies.

Which library should I choose for Go?

Use the standard library for simple apps, Koanf for a lightweight approach, and Viper when you need rich features like remote config and multiple file formats.