Skip to content

project rulesDevOps and clouddocker

Docker Rules

Project rules for Dockerfiles and Compose: multi-stage builds, pinned base images, non-root users, layer caching and health checks.

npx workspacetemplates add docker-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file19 lines · 1.4 KBFile
# Project rules: Docker

## Dockerfile
- Use multi-stage builds: a build stage with compilers and a final stage with only the runtime and the built output. Prefer slim or distroless bases.
- Pin base images to a specific version, and to a digest for releases. Never use `latest`.
- Order instructions for caching: copy dependency manifests, install, then copy source. Combine package manager steps and clean caches in the same `RUN`. Use BuildKit cache mounts for package downloads.
- Use `COPY`, not `ADD`, unless you need extraction. Keep a strict `.dockerignore` that excludes `.git`, `node_modules`, local env files and build output.

## Runtime
- Create and switch to a non-root user with `USER`. Do not install sudo, SSH or debugging tools in the final image.
- Use the exec form of `CMD` and `ENTRYPOINT` so signals reach the process. One process per container.
- Add a `HEALTHCHECK` or an orchestrator probe. Log to stdout and stderr.
- Read configuration from environment variables. Never bake secrets into layers or pass them as build args; use BuildKit secrets.

## Compose
- Name services and volumes explicitly, set restart policies, use `depends_on` with health conditions, and keep local overrides in a separate file.

## Before finishing
- Run `hadolint Dockerfile`, `docker build`, then scan the image with Trivy or Grype. Report the final image size and confirm the container starts and passes its health check.

What it does

Container images pick up bad habits quickly: huge layers, root processes and tags that change under you. These rules give an agent a checklist for every Dockerfile it writes or edits.

They aim at small, repeatable and safer images, and they name the commands to run before an image is called ready.

Example

you › Containerize this Node API for production

agent › The agent writes a two-stage Dockerfile on a pinned slim base, a dockerignore file, a non-root user and a health check, then builds it, runs hadolint and reports a final size.

Questions

Why pin by digest as well as version?
A version tag can be republished. A digest identifies the exact image bytes, so rebuilds stay identical.
Does it apply to Podman?
Yes for Dockerfiles. The Compose notes apply when you use a compatible compose tool.
  • AWS CDK Rules

    Project rulesaws

    Free
  • GitHub Actions Rules

    Project rulesgithub-actions

    Free
  • Kubernetes Rules

    Project ruleskubernetes

    Free
  • Serverless Lambda Rules

    Project rulesaws

    Free