Claude-skill-registry Config & Environment Conventions

Conventions for service configuration and environment variables: naming, precedence, validation at startup, secrets handling, environment detection, and documentation patterns

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/config-env-conventions" ~/.claude/skills/majiayu000-claude-skill-registry-config-environment-conventions && rm -rf "$T"

manifest: skills/data/config-env-conventions/SKILL.md

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:

Secret manager (Vault/AWS SM/GCP SM)
Environment variables (runtime)
Environment-specific file (
```
.env.production
```
) (เฉพาะ local/staging ที่อนุญาต)
Default
```
.env
```
(เฉพาะ local)
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

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

# 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

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

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

Integration Points

Secret managers
CI/CD pipelines
Container orchestration
Feature flag systems