12-factor-app

Original：🇺🇸 English

Translated

The Twelve-Factor App methodology for building scalable, maintainable cloud-native applications. Use when designing backend services, APIs, microservices, or any software-as-a-service application. Triggers on deployment patterns, configuration management, process architecture, logging, and infrastructure decisions.

3installs

Sourcepproenca/dot-skills

Added on2026-04-15

NPX Install

npx skill4agent add pproenca/dot-skills 12-factor-app

SKILL.md Content

View Translation Comparison →

Community Cloud-Native Applications Best Practices

Comprehensive methodology for building modern software-as-a-service applications that are portable, scalable, and maintainable. Contains 51 rules across 12 categories, covering the entire application lifecycle from codebase management to production operations.

When to Apply

Reference these guidelines when:

Designing new backend services or APIs
Containerizing applications for Kubernetes or Docker
Setting up CI/CD pipelines
Managing configuration across environments
Implementing logging and monitoring
Planning application scaling strategy
Debugging deployment or environment issues

Rule Categories by Priority


code-
dep-
config-
svc-
build-
proc-
scale-
disp-
port-
parity-
log-
admin-

Priority	Category	Impact	Prefix
1	Codebase & Version Control	CRITICAL	`code-`
2	Dependencies	CRITICAL	`dep-`
3	Configuration	CRITICAL	`config-`
4	Backing Services	HIGH	`svc-`
5	Build, Release, Run	HIGH	`build-`
6	Processes & State	HIGH	`proc-`
7	Concurrency & Scaling	HIGH	`scale-`
8	Disposability	HIGH	`disp-`
9	Port Binding	MEDIUM	`port-`
10	Dev/Prod Parity	MEDIUM	`parity-`
11	Logging	MEDIUM	`log-`
12	Admin Processes	MEDIUM	`admin-`

Quick Reference

1. Codebase & Version Control (CRITICAL)

```
code-single-codebase
```
- Maintain one codebase per application in version control
```
code-one-app-one-repo
```
- Enforce one-to-one correlation between codebase and application
```
code-deploys-not-branches
```
- Use deploys not branches to represent environments
```
code-shared-as-libraries
```
- Factor shared code into libraries managed by dependency manager

2. Dependencies (CRITICAL)

```
dep-explicit-declaration
```
- Declare all dependencies explicitly in a manifest file
```
dep-isolate-execution
```
- Isolate dependencies to prevent system package leakage
```
dep-no-system-tools
```
- Never rely on implicit system tools being available
```
dep-deterministic-builds
```
- Use lockfiles for deterministic dependency resolution

3. Configuration (CRITICAL)

```
config-separate-from-code
```
- Strictly separate configuration from code
```
config-use-env-vars
```
- Store configuration in environment variables
```
config-no-env-groups
```
- Treat environment variables as granular controls not grouped environments
```
config-validate-on-startup
```
- Validate required configuration at application startup
```
config-never-commit-secrets
```
- Never commit secrets or credentials to version control

4. Backing Services (HIGH)

```
svc-as-attached-resources
```
- Treat backing services as attached resources
```
svc-connection-strings
```
- Reference all backing services via connection URLs in config
```
svc-no-local-vs-remote
```
- Make no distinction between local and third-party services
```
svc-detach-attach-without-code
```
- Design services to be detachable and attachable without code changes

5. Build, Release, Run (HIGH)

```
build-separate-stages
```
- Strictly separate build, release, and run stages
```
build-immutable-releases
```
- Create immutable releases with unique identifiers
```
build-no-runtime-changes
```
- Never modify code at runtime - changes require new release
```
build-complexity-in-build
```
- Push complexity into build stage keep run stage minimal
```
build-artifact-per-commit
```
- Generate one build artifact per commit deploy same artifact everywhere

6. Processes & State (HIGH)

```
proc-stateless-processes
```
- Execute the application as stateless processes
```
proc-no-sticky-sessions
```
- Never use sticky sessions - store session data in backing services
```
proc-no-local-filesystem
```
- Never assume local filesystem persists between requests
```
proc-compile-at-build
```
- Perform asset compilation and bundling at build time not runtime
```
proc-share-nothing
```
- Design processes to share nothing with each other

7. Concurrency & Scaling (HIGH)

```
scale-process-model
```
- Scale out via the process model with multiple process types
```
scale-process-types
```
- Assign workloads to appropriate process types
```
scale-no-daemonize
```
- Never daemonize or write PID files let process manager handle it
```
scale-horizontal-not-vertical
```
- Design for horizontal scaling over vertical scaling
```
scale-process-formation
```
- Define process formation as declarative configuration

8. Disposability (HIGH)

```
disp-disposable-processes
```
- Design processes to be disposable started or stopped at any moment
```
disp-fast-startup
```
- Minimize startup time to enable rapid scaling and recovery
```
disp-graceful-shutdown
```
- Implement graceful shutdown on SIGTERM
```
disp-crash-only
```
- Design for crash-only software that recovers from sudden death
```
disp-idempotent-operations
```
- Make operations idempotent to safely retry after failures

9. Port Binding (MEDIUM)

```
port-self-contained
```
- Make the application completely self-contained with embedded server
```
port-export-via-binding
```
- Export services via port binding using PORT environment variable
```
port-any-protocol
```
- Use port binding to export any protocol not just HTTP

10. Dev/Prod Parity (MEDIUM)

```
parity-minimize-gaps
```
- Minimize gaps between development and production environments
```
parity-same-backing-services
```
- Use the same type and version of backing services in all environments
```
parity-deploy-frequently
```
- Deploy frequently to minimize the time gap
```
parity-developers-deploy
```
- Involve developers in deployment to minimize personnel gap

11. Logging (MEDIUM)

```
log-event-streams
```
- Treat logs as event streams not files
```
log-no-routing
```
- Never route or store logs from within the application
```
log-structured-format
```
- Use structured logging for machine-readable event streams
```
log-unbuffered-stdout
```
- Write logs unbuffered to stdout for real-time streaming

12. Admin Processes (MEDIUM)

```
admin-one-off-processes
```
- Run admin tasks as one-off processes not special scripts
```
admin-same-environment
```
- Run admin processes against a release with same codebase and config
```
admin-repl-access
```
- Provide REPL access for debugging and data inspection

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information