Twelve-Factor Apps skill for Codex

Done well means the same immutable build artifact runs in every environment with only environment-provided config changing, any instance can be killed at any moment without losing data or dropping in-flight requests, and the app scales by adding processes. The twelve factors are a checklist toward that, not a religion; note justified exceptions.

Before auditing

1. Read AGENTS.md, the Dockerfile, compose files, Kubernetes manifests or Helm charts, Procfile, and CI deploy jobs. These show how the app actually runs.
2. Find config loading (settings.py, config/*.yml, appsettings.*.json, .env handling) and the process entry point (signal handling, server start).
3. Note the platform: Kubernetes, ECS, Cloud Run, Heroku-style PaaS, VMs. Some fixes (graceful shutdown timing, health probes) depend on it.

Audit checklist with evidence

Run the probes, record pass, fail or exception with file paths.

#	Factor	Pass when	Probe
1	Codebase	One repo (or monorepo package) per deployable; many deploys of it	Check for copy-pasted forks per customer or environment
2	Dependencies	All declared and locked; nothing relies on host tools	Lockfile present and used in build; probe A for implicit host tools
3	Config	Environment-specific values come from env or a secret store, not code	Probe B; look for if ENV == "production" branches
4	Backing services	DB, cache, queue, SMTP reached by URL/credentials from config; swappable	Hard-coded hostnames or local-socket assumptions
5	Build, release, run	Build once; release = build + config; no code changes at runtime	Images rebuilt per environment, migrations or asset builds at container start
6	Processes	Stateless; no sticky sessions; local disk only for scratch	Probe C; in-memory session stores
7	Port binding	App serves HTTP itself on $PORT	Requires an external app server injected at deploy
8	Concurrency	Scale by process type (web, worker, scheduler)	One process doing web plus cron plus queue work
9	Disposability	Fast start, graceful SIGTERM, idempotent jobs	Signal handlers; startup time; shutdown test below
10	Dev/prod parity	Same backing service types and versions in dev and prod	SQLite in dev with Postgres in prod; compose image tags vs prod versions
11	Logs	Unbuffered event stream to stdout/stderr; no log files or rotation in the app	Probe D
12	Admin processes	Migrations and one-off tasks run as separate processes from the same release	Migration scripts run by hand from laptops or baked into web startup

rg -n "apt-get install|brew install" scripts/ Makefile                     # A: implicit host tools
rg -n "localhost|127\.0\.0\.1|\.internal|prod|staging" src -g '!**/*test*'  # B: env-specific values in code
rg -n "writeFile|/tmp/|uploads/|open\(.*['\"]w" src                         # C: local disk state
rg -n "FileHandler|RotatingFileHandler|transports\.File|\.log['\"]" src     # D: log files

Add the modern extras every reviewer asks about: health endpoints (separate liveness and readiness), secrets from a secret manager rather than plain env in manifests, telemetry (metrics and traces), and a non-root container user.

Fixes that come up most

Config

# settings.py: fail fast on missing config; no per-environment branches
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    redis_url: str
    log_level: str = "INFO"
    feature_x_enabled: bool = False

settings = Settings()  # reads env vars; raises at startup if DATABASE_URL is missing

Keep a committed .env.example with every key and no real values. Never commit .env. Config is what varies between deploys; constants that never vary (page size limits, route tables) stay in code.

Graceful shutdown

The orchestrator sends SIGTERM, waits a grace period (Kubernetes default 30 s), then SIGKILLs. On SIGTERM: fail the readiness check, stop accepting new connections, finish in-flight requests, close pools, exit 0.

// Node HTTP server
const server = app.listen(process.env.PORT ?? 3000);
process.on("SIGTERM", () => {
  ready = false;                         // readiness endpoint now returns 503
  server.close(async () => {             // stops accepting, waits for in-flight
    await db.end();
    process.exit(0);
  });
  setTimeout(() => process.exit(1), 25_000).unref(); // stay under the grace period
});

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, os.Interrupt)
defer stop()
go func() { _ = srv.ListenAndServe() }()
<-ctx.Done()
shutdownCtx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
defer cancel()
_ = srv.Shutdown(shutdownCtx)

Container gotcha: a shell-form CMD npm start makes sh PID 1, which does not forward SIGTERM. Use exec form (CMD ["node", "server.js"]) or an init such as tini, and avoid npm start as the entrypoint in production.

Kubernetes gotcha: endpoints are removed asynchronously, so new requests can arrive after SIGTERM. A short preStop sleep (5 to 10 s) or keeping the listener open briefly avoids dropped requests during rollouts.

Logs

Log one JSON object per line to stdout; let the platform ship and rotate. In Python, set PYTHONUNBUFFERED=1 in the image or logs arrive late and out of order.

Admin processes and migrations

Run migrations as a separate release step (Kubernetes Job, Helm hook, PaaS release phase), not in every web container’s startup, where N replicas race to migrate. Running migrations or one-off scripts against production is an outward-facing, potentially destructive action: confirm with the user before executing any of them.

Justified exceptions

• Large or structured config (routing tables, feature matrices) can live in mounted files from a ConfigMap or config service; the principle is “outside the build”, not “only env”.
• Secrets in plain environment variables leak into crash dumps and child processes; mounting them from a secret manager is better than the original factor.
• Stateful services (databases, brokers) are not twelve-factor apps; do not force them.

Verification

• Build the image once and run it with two different env files; it must start and point at different backing services with no rebuild.
• Shutdown test: start the app, send a slow request, send SIGTERM (docker kill --signal=SIGTERM <id>), confirm the request completes and the process exits 0 within the grace period.
• Kill a running instance under light load (hey or k6 against a local or staging copy) and confirm zero failed requests and no lost uploads or sessions.
• rg probes from the checklist come back clean or each hit is documented as acceptable.

Output template

## Twelve-factor review: <app>
| # | Factor | Status | Evidence | Fix |
|---|---|---|---|---|
| 3 | Config | Fail | `src/db.ts:12` hard-codes `prod-db.internal` | Read `DATABASE_URL`; added to `.env.example` |
| 9 | Disposability | Fail | shell-form CMD, no SIGTERM handler | Exec-form CMD, graceful shutdown in `server.ts` |

**Exceptions accepted:** <factor, reason>
**Verification run:** <tests and results>