AgentSkillsCN

Config & Environment Conventions

服务配置与环境变量的规范：命名规则、优先级设定、启动时校验、敏感信息管理、环境检测机制，以及文档编写最佳实践

SKILL.md
--- frontmatter
name: Config & Environment Conventions
description: Conventions for service configuration and environment variables: naming, precedence, validation at startup, secrets handling, environment detection, and documentation patterns

Config & Environment Conventions

Overview

มาตรฐานการจัดการ configuration และ environment variables ทุก service: naming, validation, defaults, และ secret handling ที่ทำให้ deploy ข้าม environments ได้อย่างมั่นใจ

Why This Matters

  • •Portability: Same code, different configs per env
  • •Safety: Validate config at startup, fail fast
  • •Security: Clear separation of secrets
  • •Debugging: รู้ว่า config มาจากไหน

Core Concepts

1. Environment Variable Naming

  • •รูปแบบ: <APP>_<CATEGORY>_<NAME> (ทั้งหมด UPPER_SNAKE_CASE)
  • •URL/URI ใช้ suffix เดียวกัน (APP_REDIS_URL), boolean ใช้ true|false
  • •แยก “config” กับ “secret” ชัดเจน (ดูข้อ 4)
  • •หลีกเลี่ยงชื่อกว้าง ๆ เช่น TOKEN, KEY (ต้องบอกบริบท เช่น APP_STRIPE_SECRET_KEY)

2. Config Hierarchy

กำหนดลำดับความสำคัญชัดเจน และ document ไว้ในทุก service:

  1. •Secret manager (Vault/AWS SM/GCP SM)
  2. •Environment variables (runtime)
  3. •Environment-specific file (.env.production) (เฉพาะ local/staging ที่อนุญาต)
  4. •Default .env (เฉพาะ local)
  5. •Code defaults (ปลอดภัย และไม่ใช่ production values)

3. Config Validation

  • •validate ตั้งแต่ startup (fail fast) ก่อนรับ traffic
  • •แยก required vs optional ชัดเจน
  • •validate type/format/range (เช่น port, URL, enum)
  • •log เฉพาะ keys ที่โหลดสำเร็จ (ไม่ log ค่า secret)

4. Secret vs Config

  • •Secret: credentials, tokens, private keys, passwords, encryption keys → ต้องมาจาก secret manager และ rotate ได้
  • •Config: hostnames, timeouts, feature toggles, limits → environment variables/ไฟล์ config ได้
  • •หลีกเลี่ยงการผสม: อย่าเอา secret ลง .env.example (ให้ใส่เป็นค่าว่าง + comment ว่า “from secret manager”)

5. Feature Flags Integration

  • •config ที่เปลี่ยน “ตอน runtime” (เช่น rollout %) → ใช้ feature flag system
  • •config ที่เป็น “deploy-time” (เช่น DB host, timeout) → ใช้ env vars
  • •หลีกเลี่ยง “config drift”: ทุก flag ต้องมี owner + cleanup date

6. Environment Detection

  • •มีตัวแปรเดียวสำหรับ env: APP_ENV=development|staging|production|test
  • •หลีกเลี่ยง inference จาก NODE_ENV เพียงอย่างเดียว (ใช้ร่วมได้ แต่ให้มี source-of-truth)
  • •gating behavior ที่อันตราย (debug endpoints, verbose logging) ต้องผูกกับ APP_ENV

7. Config Documentation

  • •ทุก service ต้องมี .env.example ที่ครบ keys และมีคำอธิบายสั้น ๆ
  • •ระบุ default/constraints เช่น APP_HTTP_PORT=3000 (min/max ถ้ามี)
  • •ถ้ามี schema (Zod/JSON schema) ให้ link ในเอกสารของ service/README

8. Default Values

  • •defaults ต้อง “ปลอดภัย” (เช่น feature ปิด, rate limit conservative)
  • •ห้ามใส่ค่า production จริงเป็น default
  • •config สำคัญ (DB URL, secret keys) ควร required และบังคับให้ตั้งใน env/secret manager

Quick Start

typescript
import { z } from "zod";

const schema = z.object({
  APP_ENV: z.enum(["development", "staging", "production", "test"]).default("development"),
  APP_HTTP_PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  APP_DATABASE_URL: z.string().url(),
});

export type AppConfig = z.infer<typeof schema>;

export function loadConfig(env: Record<string, string | undefined> = process.env): AppConfig {
  const result = schema.safeParse(env);
  if (!result.success) {
    throw new Error(`Invalid config: ${result.error.message}`);
  }
  return result.data;
}

Production Checklist

  • • All env vars documented in .env.example
  • • Config validated at startup
  • • Secrets not in .env files
  • • Defaults are safe (not production values)
  • • Required vs optional clearly marked
  • • Config changes don't require code changes

Naming Convention

bash
# Format: <APP>_<CATEGORY>_<NAME>

# Database
APP_DB_HOST=localhost
APP_DB_PORT=5432
APP_DB_NAME=myapp

# External Services
APP_REDIS_URL=redis://localhost:6379
APP_STRIPE_API_URL=https://api.stripe.com

# Feature Flags
APP_FEATURE_NEW_CHECKOUT=true

# Secrets (loaded from secret manager)
APP_SECRET_DB_PASSWORD=  # from Vault/AWS SM
APP_SECRET_API_KEY=      # from Vault/AWS SM

Config Hierarchy

code
Priority (highest to lowest):
1. Secret Manager (Vault, AWS SM)
2. Environment Variables
3. Environment-specific file (.env.production)
4. Default .env file
5. Code defaults

Anti-patterns

  1. •Hardcoded values: Config in code
  2. •Secrets in .env: Committed to git
  3. •No validation: Runtime failures
  4. •Magic strings: Config keys scattered in code
  5. •Implicit env: behavior เปลี่ยนตาม NODE_ENV แบบคาดเดายาก

Integration Points

  • •Secret managers
  • •CI/CD pipelines
  • •Container orchestration
  • •Feature flag systems

Further Reading