How to Sync AI Rules in Docker Builds

Why Validate Rules in Docker Builds

Docker builds are the final gate before deployment. If the Docker image builds successfully: it will be deployed. Validating AI rules during the Docker build ensures: every deployed container was built from code with current rules. No container image can exist without validated rules. This is defense-in-depth — even if the CI pipeline's prebuild check was skipped or bypassed, the Docker build catches it.

When rules validation matters in Docker: container-based deployments (ECS, Kubernetes, Cloud Run), any deployment that builds a Docker image as part of the CI/CD pipeline, and local development environments that use Docker Compose. The validation: adds 1-2 seconds to the build time. The benefit: guarantees that the codebase in the container has current, validated AI rules.

The Docker-specific challenge: the CLAUDE.md file is a development-time artifact (developers use it when writing code). It is not needed at runtime (the deployed application does not read CLAUDE.md). The validation: should happen during the build (when the source code is present) but the CLAUDE.md should not be included in the final production image (unnecessary bloat). Multi-stage builds: solve this naturally.

Step 1: Multi-Stage Dockerfile with Validation

The three-stage pattern: Stage 1 (validate): copy the rules file, run validation, fail if invalid. Stage 2 (build): copy source code, install dependencies, build the application. Stage 3 (production): copy only the built application and runtime dependencies. The CLAUDE.md: present in stages 1 and 2. Absent from stage 3 (production image). The validation: runs in stage 1, before any application code is built.

Dockerfile example: 'FROM node:20-alpine AS validate\nCOPY CLAUDE.md .\nCOPY scripts/validate-rules.js scripts/\nRUN node scripts/validate-rules.js\n\nFROM node:20-alpine AS build\nWORKDIR /app\nCOPY package.json pnpm-lock.yaml ./\nRUN corepack enable && pnpm install --frozen-lockfile\nCOPY . .\nRUN pnpm run build\n\nFROM node:20-alpine AS production\nWORKDIR /app\nCOPY --from=build /app/dist ./dist\nCOPY --from=build /app/node_modules ./node_modules\nCMD ["node", "dist/index.js"]'

The validate stage: copies only CLAUDE.md and the validation script. If validation fails: the build stops at stage 1. No application code is compiled, no dependencies are installed. Fail-fast: saves 2-5 minutes of build time when rules are invalid. The production stage: does not contain CLAUDE.md, the validation script, or any development artifacts. AI rule: 'The validation stage adds ~1 second. If it saves the full build (2-5 minutes) when rules are missing: the ROI is immediate on the first failure.'

💡 Validation in Stage 1 = Fail in 1 Second, Not 5 Minutes

Without stage 1 validation: the Dockerfile copies source code, installs dependencies (2 min), builds the application (2 min), then the app crashes because the rules were missing and a convention was wrong. Total wasted time: 4+ minutes. With stage 1 validation: the build fails in 1 second (CLAUDE.md not found). No dependencies installed. No code compiled. The developer fixes the issue and rebuilds. The 1-second validation: saves minutes on every failed build.

Step 2: Build Arguments and Labels for Traceability

Build arguments: pass the expected rule version as a Docker build argument. docker build --build-arg RULES_VERSION=v2.4.0 . In the Dockerfile: ARG RULES_VERSION. The validation script: reads RULES_VERSION and compares against the version in CLAUDE.md. If they do not match: the build fails with a specific error ('Expected rules v2.4.0, found v2.3.1'). This ensures: the Docker image is always built with a specific, expected rule version.

Image labels: add the rule version as a Docker image label. LABEL ai.rules.version='v2.4.0'. This metadata: embedded in the image, queryable with docker inspect. Use cases: auditing (which rule version was this image built with?), compliance (verify all running containers have current rules), and debugging (the production container has rule version X — check the rules changelog for version X to understand the conventions the code follows).

CI integration: in the CI pipeline (GitHub Actions, GitLab CI, Jenkins): read the current rule version from the central rules repo, pass it as a build argument (docker build --build-arg RULES_VERSION=$(cat rules/VERSION)), and verify the label on the built image (docker inspect --format '{{index .Config.Labels "ai.rules.version"}}' myapp:latest). This end-to-end traceability: connects the deployed container to the specific rule version it was validated against.

ℹ️ Image Labels Create End-to-End Rule Traceability

Production incident: a deployed container generates code with an outdated pattern. Investigation: docker inspect the container. Label: ai.rules.version=v2.3.1. Current version: v2.4.0. The container was built with old rules. Action: rebuild and redeploy with current rules. Without labels: 'When was this image built? What rules did it use?' requires digging through CI logs. Labels: the answer is embedded in the image metadata, queryable in 1 second.

Step 3: Docker Compose for Local Development

Docker Compose environments: many teams use Docker Compose for local development. The CLAUDE.md: mounted as a volume (not built into the image). In docker-compose.yml: volumes: ['./CLAUDE.md:/app/CLAUDE.md:ro']. The read-only mount: ensures the developer's CLAUDE.md is available in the container for any validation or tooling that needs it. The :ro flag: prevents the container from modifying the rules file.

Local validation: for Docker Compose-based development, add a validation service. services: validate-rules: image: node:20-alpine, volumes: ['./CLAUDE.md:/app/CLAUDE.md:ro', './scripts:/app/scripts:ro'], command: node /app/scripts/validate-rules.js. The validation service: runs before the application services (using depends_on with condition: service_completed_successfully). If validation fails: Docker Compose does not start the application.

The development workflow: developer edits CLAUDE.md locally (updating rules for their project). Runs docker compose up. The validate-rules service checks the rules. If valid: the application starts. If invalid: Docker Compose shows the validation error. The developer: fixes the rules and retries. AI rule: 'Docker Compose validation: optional but valuable for teams that use Docker for local development. It catches rule issues before the developer starts coding, not after they push to CI.'

⚠️ CLAUDE.md Should NOT Be in the Production Image

CLAUDE.md is a development-time artifact: developers and AI tools use it when writing code. The deployed application does not read CLAUDE.md at runtime. Including it in the production image: adds unnecessary file size, potentially exposes internal coding conventions to anyone who accesses the container, and serves no purpose. Multi-stage builds: the CLAUDE.md exists in build stages (for validation) but is not copied to the production stage. This is the correct behavior.

Docker AI Rules Summary

Complete Docker AI rules sync setup.

Multi-stage: validate (stage 1) → build (stage 2) → production (stage 3). CLAUDE.md not in production image
Fail-fast: validation in stage 1. If invalid: build stops before compiling code (saves 2-5 min)
Build args: --build-arg RULES_VERSION=v2.4.0. Validation compares against CLAUDE.md version
Image labels: LABEL ai.rules.version. Queryable with docker inspect for auditing
CI integration: read version from central repo → build arg → validate → label → deploy
Docker Compose: mount CLAUDE.md as read-only volume. Validation service runs before app starts
Local dev: Docker Compose validation catches rule issues before the developer starts coding
Traceability: every running container traceable to the specific rule version it was built with