AI Rules in the Netlify Build Pipeline
Netlify deploys from git: push to the production branch triggers a production deploy. PRs create deploy previews. Like Vercel, the AI rules file (CLAUDE.md) is in the repository and deploys automatically. The sync concern: ensuring the rules are present, current, and valid at build time. Netlify provides two integration points: build plugins (custom logic that runs during the build) and build commands (standard npm scripts).
Netlify-specific features: build plugins (reusable, shareable build steps that run at specific points in the build lifecycle), deploy previews with deploy contexts (different settings per branch or deploy type), and Netlify Functions (serverless functions that can validate rules at runtime). For AI rules: the build plugin approach is the most elegant — it runs validation as a first-class part of the Netlify build.
The approach: create a Netlify build plugin (or a simple prebuild script) that validates the CLAUDE.md during every build. The plugin checks: file exists, version is current, and required sections are present. If validation fails: the build fails, preventing deployment of a project with missing or outdated rules.
Step 1: Build Plugin for Rule Validation
Netlify build plugins: run at specific points in the build lifecycle (onPreBuild, onBuild, onPostBuild, onSuccess, onError). For rule validation: use onPreBuild (runs before the build starts). The plugin: reads CLAUDE.md, validates its content, and fails the build if validation fails. Create the plugin in your repo: netlify/plugins/validate-rules/index.js with an onPreBuild handler.
Plugin logic: read CLAUDE.md from the project root (using the NETLIFY_BASE environment variable for monorepo support). Check: file exists (if not: fail with 'CLAUDE.md not found — AI rules are required for deployment'). Parse the version header (if present). Compare against the minimum required version. Check for required sections (security rules, testing standards). Return: success (build continues) or failure (build stops with a descriptive error).
Registration: in netlify.toml, add the plugin: [[plugins]] package = './netlify/plugins/validate-rules'. The plugin runs on every build — production, deploy preview, and branch deploys. No external packages needed — the plugin is local to the repository. AI rule: 'A local build plugin is the simplest approach. No npm package to publish or maintain. The plugin code lives in the repo alongside the rules it validates.'
A Netlify build plugin can be published to npm (shared across organizations) or kept local (./netlify/plugins/validate-rules/). For most teams: the local approach is simpler. The plugin code: lives in the repo, version-controlled with the project, and requires no publishing step. If you later want to share the plugin across multiple Netlify sites: extract to an npm package then. Start local. Share later if needed.
Step 2: Deploy Previews for Rule Testing
Netlify deploy previews: created for every PR. If the PR modifies CLAUDE.md: the deploy preview reflects the change. Use deploy previews to: test that rule changes do not break the build, verify the validation plugin accepts the updated rules, and share the preview with the team for rule change review. The deploy preview URL: posted as a comment on the PR by Netlify.
Deploy contexts: Netlify supports different configurations per deploy context (production, deploy-preview, branch-deploy). For rule validation: the same rules should apply to all contexts (the same CLAUDE.md, the same validation). Exception: if the team experiments with rule changes in a feature branch, the branch deploy context can use relaxed validation (warning instead of error for version mismatches). AI rule: 'Same rules for all contexts by default. Relaxed validation only for explicitly designated experimentation branches.'
Notification on rule changes: configure Netlify notifications (Slack, email) to alert the team when a deploy includes CLAUDE.md changes. The notification: triggers review of the rule change. Combined with the deploy preview: the team sees exactly what changed and can verify the impact. AI rule: 'Treat CLAUDE.md changes as deployment-significant events. Notification on change: ensures the team reviews rule modifications promptly.'
The prebuild script (node scripts/validate-rules.js) works on: Vercel (runs prebuild automatically), Netlify (runs prebuild automatically), Railway (runs prebuild as part of npm run build), AWS Amplify (runs prebuild), and any CI/CD system that uses npm scripts. Write once: validate everywhere. If you deploy to multiple platforms: the prebuild script is the universal approach. Platform-specific plugins: only when you need platform-specific lifecycle hooks.
Step 3: Alternative — Prebuild Script Approach
If a Netlify build plugin feels like overkill: use a simple prebuild script in package.json. The script: identical to the Vercel approach. 'prebuild': 'node scripts/validate-rules.js'. Netlify runs prebuild before the build command. The script checks CLAUDE.md existence and version. Build fails if validation fails. No plugin infrastructure needed.
When to use the plugin vs the script: Plugin advantages: runs at a well-defined lifecycle point (onPreBuild), can access Netlify-specific environment variables and utilities, and is shareable across Netlify sites. Script advantages: simpler (one JavaScript file), portable (works on Vercel, Netlify, Railway, and any platform that runs npm scripts), and no Netlify-specific knowledge required.
Monorepo handling: for monorepos on Netlify, set the Base Directory in netlify.toml (base = 'apps/web/'). The prebuild script or plugin: runs in the base directory context. Check for CLAUDE.md in both the base directory (app-specific rules) and the monorepo root (shared rules). AI rule: 'The prebuild script approach is recommended for most teams: simpler, portable, and works across all deployment platforms. Use the plugin approach only if you need Netlify-specific lifecycle hooks.'
A team relaxes rule validation for deploy previews ('it is just a preview, validation can be lenient'). A developer: pushes code with missing rules to a PR. The deploy preview: succeeds (lenient validation). The team merges without checking rules. Production deploy: fails (strict validation). Or worse: production deploy succeeds but the rules are missing, and the AI generates non-compliant code. Same validation for all contexts: prevents this cascade.
Netlify AI Rules Summary
Complete Netlify AI rules sync setup.
- Rules deploy with git: CLAUDE.md in the repo, deployed automatically with every push
- Build plugin: netlify/plugins/validate-rules/ with onPreBuild handler. Checks existence and version
- Alternative: prebuild script in package.json. Simpler, portable across all platforms
- Deploy previews: test rule changes before merging. Preview URL posted on PR
- Deploy contexts: same rules for all contexts. Relaxed validation only for experimentation branches
- Notifications: alert team on CLAUDE.md changes. Trigger review of rule modifications
- Monorepo: set Base Directory in netlify.toml. Validate both app-level and root-level rules
- Recommendation: prebuild script for simplicity. Build plugin for Netlify-specific lifecycle integration