AGENTS.md — Docker

Dockerfile authoring rules, from Docker's official best practices.

• Use multi-stage builds; ship only runtime artifacts in the final stage (COPY --from=…).
• Choose a minimal official/verified base image; pin the version and digest.
• Don't install unnecessary packages.
• Order instructions least-changing → most-changing; install deps before copying source.
• Combine related commands into one RUN; clean up in the same layer.
• For apt: apt-get update && apt-get install -y --no-install-recommends … in one RUN, then rm -rf /var/lib/apt/lists/*.
• Sort multi-line arguments alphanumerically.
• Prefer COPY over ADD; reserve ADD for checksummed remote URLs or tar auto-extraction.
• Use exec form for CMD/ENTRYPOINT (["bin","arg"]); exec "$@" in entrypoint scripts so the app is PID 1.
• Use absolute WORKDIR paths instead of RUN cd ….
• Run as a non-root USER when privileges aren't needed.
• Never bake secrets via ENV/ARG/COPY; use RUN --mount=type=secret.
• Add a .dockerignore to exclude .git, secrets, and build cruft.
• One concern per container; keep containers ephemeral and stateless.
• Rebuild often with --pull to pick up security patches.