Generate CNCF/12-Factor compliance checklists and ADRs for cloud-native applications. Use when reviewing application architecture, planning containerization, or documenting cloud-native decisions.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Generate Architecture Decision Records (ADRs) and compliance checklists for CNCF and 12-Factor App principles.
When asked to generate a checklist, create an ADR at docs/adr/NNNN-cloud-native-compliance.md:
# ADR-NNNN: Cloud-Native Compliance Assessment
## Status
Proposed | Accepted | Implemented
## Context
[Brief description of the application and why this assessment is needed]
## 12-Factor App Compliance
| Factor | Status | Notes |
|--------|--------|-------|
| I. Codebase | | One codebase tracked in VCS, many deploys |
| II. Dependencies | | Explicitly declare and isolate dependencies |
| III. Config | | Store config in environment variables |
| IV. Backing Services | | Treat backing services as attached resources |
| V. Build, Release, Run | | Strictly separate build and run stages |
| VI. Processes | | Execute app as stateless processes |
| VII. Port Binding | | Export services via port binding |
| VIII. Concurrency | | Scale out via process model |
| IX. Disposability | | Fast startup and graceful shutdown |
| X. Dev/Prod Parity | | Keep development, staging, production similar |
| XI. Logs | | Treat logs as event streams |
| XII. Admin Processes | | Run admin/management tasks as one-off processes |
## Container Standards
| Requirement | Status | Notes |
|-------------|--------|-------|
| `/health` endpoint | | Orchestrator health checks |
| `/ready` endpoint | | Startup readiness (if slow init) |
| Graceful SIGTERM | | Drain connections, finish requests |
| Log to stdout | | No file logging |
| Non-root user | | Container security |
| Environment config | | No hardcoded configuration |
| OCI labels | | Image metadata and linking |
## Supply Chain Security
| Requirement | Status | Notes |
|-------------|--------|-------|
| Image signing (Cosign) | | Cryptographic verification |
| SLSA provenance | | Build attestations |
| Dependency scanning | | Vulnerability detection |
| SBOM generation | | Software bill of materials |
## Observability
| Requirement | Status | Notes |
|-------------|--------|-------|
| Structured logging | | JSON log format |
| OpenTelemetry tracing | | Distributed tracing |
| Prometheus metrics | | `/metrics` endpoint |
| Correlation IDs | | Cross-service request tracking |
## Decision
[Summary of compliance status and recommended actions]
## Consequences
[Impact of implementing/not implementing the recommendations]
One codebase tracked in revision control, many deploys.
Explicitly declare and isolate dependencies.
package.json, pyproject.toml, go.mod with lockfilesStore config in the environment.
Treat backing services as attached resources.
Strictly separate build and run stages.
Execute the app as one or more stateless processes.
Export services via port binding.
Scale out via the process model.
Maximize robustness with fast startup and graceful shutdown.
Keep development, staging, and production as similar as possible.
Treat logs as event streams.
Run admin/management tasks as one-off processes.
# FastAPI example
@app.get("/health")
async def health():
return {"status": "healthy"}
@app.get("/ready")
async def ready():
# Check database, cache, etc.
if await database.is_connected():
return {"status": "ready"}
raise HTTPException(503, "Not ready")
import signal
import asyncio
async def shutdown(signal, loop):
logging.info(f"Received {signal.name}, shutting down...")
# Stop accepting new requests
# Wait for in-flight requests
# Close connections
tasks = [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]
await asyncio.gather(*tasks, return_exceptions=True)
loop.stop()
loop = asyncio.get_event_loop()
for sig in (signal.SIGTERM, signal.SIGINT):
loop.add_signal_handler(sig, lambda s=sig: asyncio.create_task(shutdown(s, loop)))
# Create non-root user
RUN useradd --create-home --shell /bin/bash appuser
USER appuser
WORKDIR /home/appuser/app
When assessing cloud-native readiness, consider:
Store in docs/adr/ with numeric prefix:
docs/adr/
├── 0001-use-postgresql.md
├── 0002-adopt-kubernetes.md
├── 0003-cloud-native-compliance.md
└── template.md
#!/bin/bash
# Quick cloud-native assessment
echo "=== Cloud-Native Readiness Check ==="
# Check for Dockerfile
[ -f Dockerfile ] && echo "✓ Dockerfile found" || echo "✗ No Dockerfile"
# Check for health endpoint in code
grep -r "/health" --include="*.py" --include="*.ts" --include="*.go" . >/dev/null && \
echo "✓ Health endpoint found" || echo "✗ No health endpoint"
# Check for environment config
grep -r "os.environ\|process.env\|os.Getenv" --include="*.py" --include="*.ts" --include="*.go" . >/dev/null && \
echo "✓ Environment config found" || echo "? Check config handling"
# Check for structured logging
grep -r "structlog\|pino\|zap\|slog" --include="*.py" --include="*.ts" --include="*.go" . >/dev/null && \
echo "✓ Structured logging found" || echo "? Check logging setup"
# Check for non-root in Dockerfile
grep -i "USER" Dockerfile >/dev/null 2>&1 && \
echo "✓ Non-root user in Dockerfile" || echo "✗ No USER directive"
echo "=== Assessment Complete ==="