ai-agents-workspace-starter: Skill for Claude Code

Skill: Infra Patterns

Patterns and templates for infra development. Read when configuring Docker, CI/CD, servers.

---

docker-compose.yml Service Template

Key properties for each service:

• build.context: .., dockerfile: infra/{service}/Dockerfile, target: development
• container_name: ${PROJECT_NAME:-app}-{service}
• restart: unless-stopped
• ports: env-based (e.g. ${SERVICE_PORT:-8080}:8080)
• volumes: source code bind mount with :cached
• environment: DATABASE_URL, REDIS_URL using service hostnames (not localhost)
• depends_on: with condition: service_healthy
• healthcheck: test, interval 30s, timeout 5s, retries 3, start_period 10s
• networks: app-network
• Resource limits: mem_limit, cpus

Dockerfile Multi-Stage Template

3 stages:

1. builder - python:3.12-slim, install deps with --no-cache-dir --prefix=/install
2. development - non-root user (appuser), copy from builder, hot reload (--reload)
3. production - minimal, USER appuser, HEALTHCHECK CMD, --workers 4

Key rules:

• Always create non-root user: groupadd -r appuser && useradd -r -g appuser appuser
• Production: USER appuser before CMD
• Include HEALTHCHECK in production stage

Makefile Target Template

• Pattern: .PHONY: target + $(COMPOSE) exec backend <command>
• Every target has a ## Description comment for make help

Requirements Policy

When CI/CD or multiple environments are added:

1. Split: requirements/base.txt, requirements/dev.txt, requirements/prod.txt
2. dev.txt and prod.txt start with -r base.txt
3. Production containers install ONLY prod.txt
4. Dev containers install dev.txt (pytest, ruff, mypy, factory-boy)
5. NEVER install test tools in production

.env Best Practices

• Unique ports per project (avoid collisions): BACKEND_PORT, DB_PORT, REDIS_PORT
• Unique volume and network names (auto from ${PROJECT_NAME})
• Secrets: NEVER commit .env, generate with openssl rand -hex 32