shared/skills/spec-dockerfile/SKILL.md

name, description

name	description
spec-dockerfile	JSC plugins 共用「Dockerfile 六步流程」：參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口，以多階段建置縮小最終映像、ARG 集中檔首、相依描述先 COPY 以利 layer 快取、COPY --from 逐項明列、.dockerignore、對外契約不變與自我檢查。當其他 skill 內文引用 spec-dockerfile 或 /jsc:spec-dockerfile、或需要產生／重整 Dockerfile 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。

spec-dockerfile — 共用 Dockerfile 六步流程

Dockerfile 一律組織為以下固定六步流程，並採多階段建置縮小最終映像。六步是骨架，每一步的實際內容必須依專案／主程式實作決定 — 不要套用與其無關的固定樣板，也不要硬塞用不到的安裝或建置指令。

六步流程

1. 參數處理：可調參數集中到檔案開頭以 ARG 注入（base image 版本、build flag、路徑等）；# syntax 指示與全域 ARG 置於最前。
2. 安裝套件：先 COPY 相依描述檔（package*.json／requirements.txt／go.mod go.sum／*.csproj 等）再安裝，以利 layer 快取；OS 套件與語言相依在此安裝，安裝後於同一 RUN 清理快取（apt-get clean／rm -rf /var/lib/apt/lists/*、--no-cache）。安裝指令二擇一寫死（如有 lockfile 用 npm ci、否則 npm install），不得以 A || B fallback 串接（避免靜默吞錯、破壞可重現性）。OS 套件只在真的會用到時才安裝。
3. 複製檔案：COPY 實際需要的檔案，明列路徑、不整包 COPY .（除非重整既有 Dockerfile 需保留原行為），並配合 .dockerignore 排除無關檔案（至少 .git、.docs、node_modules 等非執行必需檔）。
4. 執行程序：build／compile／transpile（npm run build／go build／dotnet publish 等）與必要的權限設定（chmod）於此執行；不需 build 時此步只做權限設定。
5. 縮小映像檔：多階段建置，runtime 階段改用較小基底（*-slim／*-alpine／distroless／scratch，依語言對應），只 COPY --from=<build> 帶入執行所必需的產物；必須逐項明列路徑，不得整包搬（整包搬等於沒有縮小）。不把 build 期 dev 相依與快取帶進最終映像；runtime 需要的 OS 執行檔於 runtime 階段安裝；同步搬移 runtime 需要的 ENV／WORKDIR／EXPOSE／USER。
6. 設定入口：ENTRYPOINT／CMD 置於最後，語意與需求（或原檔）一致。

base image 版本

• 預設使用固定 major tag（如 node:22 與 node:22-slim），不用 latest — 避免 base 無預警跳版導致行為漂移、跨環境不一致、無法重現除錯。
• runtime 基底版號需與 build 基底一致，以獨立的 runtime ARG 帶入（如 NODE_RUNTIME=22-slim），不要用 ${VERSION}-slim 組裝。tag 已是 -alpine／-slim 變體時，build 與 runtime 直接沿用同一 tag、不再另組（沒有 node:22-alpine-slim 這種 tag）。使用者明確要求 latest 時，runtime 用 node:slim（沒有 node:latest-slim）。

對外契約不動（重整既有 Dockerfile 時）

• ENTRYPOINT／CMD／EXPOSE／ENV／VOLUME／HEALTHCHECK／USER 的語意保持與原檔一致；只可調整位置與分層，不可改變值或刪除。
• 凡無法可靠保證建置行為等價的重整（ARG 作用範圍跨 FROM、COPY 順序影響覆蓋、RUN 間狀態相依、單階段改多階段時 runtime 缺檔），先確認或標 # 需人工確認 退回最小重排。

自我檢查

1. ARG 在使用它的 FROM 之後有重新宣告（跨階段 ARG 規則）。
2. runtime 階段 COPY --from 帶齊執行所需全部產物（執行檔、相依、靜態資源），容器能啟動。
3. 對外契約（ENTRYPOINT／CMD／EXPOSE／ENV）語意一致。
4. 路徑一致：WORKDIR／COPY 落點與入口（entrypoint.sh／主程式路徑）對得上。
5. 若環境可執行，docker build（或至少 --check／語法檢查）驗證可建置；無法執行時說明原因並標註風險。