Config Env Conventions

Config Env Conventions

Skill Profile

(Select at least one profile to enable specific modules)

• DevOps
• Backend
• Frontend
• AI-RAG
• Security Critical

Overview

Service configuration and environment variable conventions across all services: naming, validation, defaults, and secret handling for confident deployment across environments.

Why This Matters

• Portability: Same code, different configs per env
• Safety: Validate config at startup, fail fast
• Security: Clear separation of secrets
• Debugging: Know where config comes from

Core Concepts & Rules

1. Core Principles

• Follow established patterns and conventions
• Maintain consistency across codebase
• Document decisions and trade-offs

2. Implementation Guidelines

• Start with the simplest viable solution
• Iterate based on feedback and requirements
• Test thoroughly before deployment

Inputs / Outputs / Contracts

• Inputs:
  • <e.g., env vars, request payload, file paths, schema>
• Entry Conditions:
  • <Pre-requisites: e.g., Repo initialized, DB running, specific branch checked out>
• Outputs:
  • <e.g., artifacts (PR diff, docs, tests, dashboard JSON)>
• Artifacts Required (Deliverables):
  • <e.g., Code Diff, Unit Tests, Migration Script, API Docs>
• Acceptance Evidence:
  • <e.g., Test Report (screenshot/log), Benchmark Result, Security Scan Report>
• Success Criteria:
  • <e.g., p95 < 300ms, coverage ≥ 80%>

Skill Composition

• Depends on: secrets-key-management, config-distribution
• Compatible with: api-style-guide, service-standards-blueprint
• Conflicts with: None
• Related Skills: env-matrix-dev-stg-prod, logging-metrics-tracing-standard

Quick Start

Assumptions

• Services follow 12-Factor App principles
• Secret management system available (Vault, AWS SM, GCP SM)
• Multiple environments (development, staging, production)
• Configuration validation at startup
• TypeScript or similar language with schema validation

Compatibility

• Node.js: 16+
• TypeScript: 4.5+
• Zod: 3.0+
• Vault: 1.10+
• AWS Secrets Manager: Latest API

Test Scenario Matrix

Technical Guardrails

Agent Directives & Error Recovery

(ข้อกำหนดสำหรับ AI Agent ในการคิดและแก้ปัญหาเมื่อเกิดข้อผิดพลาด)

• Thinking Process: Analyze root cause before fixing. Do not brute-force.
• Fallback Strategy: Stop after 3 failed test attempts. Output root cause and ask for human intervention/clarification.
• Self-Review: Check against Guardrails & Anti-patterns before finalizing.
• Output Constraints: Output ONLY the modified code block. Do not explain unless asked.

Definition of Done

Configuration is complete when:

• All env vars follow naming convention
• Configuration schema defined and validated
• .env.example complete with all keys
• Required vs optional clearly marked
• Secrets not in .env files
• Defaults are safe (not production values)
• Environment detection implemented
• Config changes don't require code changes
• Documentation complete
• Startup validation tested

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 changes based on NODE_ENV unpredictably
6. Production defaults: Real production values as defaults
7. Mixed secrets: Secrets and config in same place
8. No documentation: Undocumented configuration options

Reference Links

• 12-Factor App: Config
• Node.js Config Best Practices
• Zod Documentation
• AWS Secrets Manager

Versioning & Changelog

• Version: 1.0.0
• Changelog:
  • 2026-02-22: Initial version with complete template structure

Converted and distributed by TomeVault — claim your Tome and manage your conversions.