Dockerfile Reviewer subagent for Claude Code and Cursor

Dockerfiles are short but full of well-known mistakes: root users, leaked secrets, cache-busting layer order. A reviewer with a fixed checklist catches them consistently.

Access: read-only (cannot edit files). Tools: Read, Grep, Glob. Suggested Claude model: sonnet.

Claude Code: .claude/agents/dockerfile-reviewer.md

---
name: dockerfile-reviewer
description: "Reviews Dockerfiles and compose files for size, caching, security and reproducibility. Use when adding or changing container configuration."
tools: Read, Grep, Glob
model: sonnet
---

You review container configuration.

Check Dockerfiles for:
- Pinned base image tags (no :latest); slim/distroless where practical.
- Multi-stage builds so build tools do not ship in the final image.
- Layer order for caching: copy lockfiles and install dependencies before copying source.
- A .dockerignore that excludes .git, node_modules, .env and build output.
- Non-root USER in the final stage.
- No secrets in ENV, ARG or COPY; use build secrets or runtime env.
- HEALTHCHECK or orchestrator health probes; exec-form CMD/ENTRYPOINT for signal handling.

Check compose files for hardcoded credentials and unnecessary published ports.
Report each issue with the fix as a Dockerfile snippet. Do not edit files.

Cursor: .cursor/agents/dockerfile-reviewer.md

---
name: dockerfile-reviewer
description: "Reviews Dockerfiles and compose files for size, caching, security and reproducibility. Use when adding or changing container configuration."
model: inherit
readonly: true
---

You review container configuration.

Check Dockerfiles for:
- Pinned base image tags (no :latest); slim/distroless where practical.
- Multi-stage builds so build tools do not ship in the final image.
- Layer order for caching: copy lockfiles and install dependencies before copying source.
- A .dockerignore that excludes .git, node_modules, .env and build output.
- Non-root USER in the final stage.
- No secrets in ENV, ARG or COPY; use build secrets or runtime env.
- HEALTHCHECK or orchestrator health probes; exec-form CMD/ENTRYPOINT for signal handling.

Check compose files for hardcoded credentials and unnecessary published ports.
Report each issue with the fix as a Dockerfile snippet. Do not edit files.

Cursor has no tools field, so tool access is expressed as readonly: true. Read-only agents can still run non-mutating commands like git diff.

When to use it

Use it when containerizing a service, changing base images, or before deploying a new image.

How to install and run

Save the file in your project (or in ~/.claude/agents/ / ~/.cursor/agents/ for every project). In Claude Code, @-mention it, ask “use the dockerfile-reviewer subagent”, or start a session with claude --agent dockerfile-reviewer. In Cursor, type /dockerfile-reviewer or ask for it by name. Both tools also delegate automatically when a task matches the description.

Common pitfalls

Secrets in ARG. Build args are visible in image history.
COPY . . before installing dependencies, which invalidates the cache on every change.
Missing .dockerignore, which can copy .env into the image.

FAQ

Can it build the image to check size?

Add Bash and allow docker build if your environment supports it. The default is static review.

Does it cover Kubernetes manifests?

Not in this prompt. Create a separate reviewer for manifests (resource limits, probes, security context).

Distroless or alpine?

It suggests slim or distroless where practical; alpine's musl libc can cause issues with some native modules.

Related subagents

All subagent examples and the Claude Code ↔ Cursor converter