How Fleek Uses Git Hooks to Enforce Deterministic Standards for AI Coding Agents

Beyond Prompts: How Git Hooks Steer AI Coding Agents in Production

Fleek engineers and non-engineers utilize AI coding agents like Claude Code to build internal tools within a monorepo of 10+ sub-applications. While instruction files like CLAUDE.md provide heuristic guidelines, Git hooks provide a deterministic enforcement layer that blocks non-compliant commits.

Why This Matters

In production environments, instruction files (heuristics) are only followed 90-95% of the time by AI agents, leading to eventual drift and broken conventions. Git hooks transform error messages into prompt engineering, forcing AI self-correction through deterministic blocks that prevent technical debt from entering the repository without human intervention.

Key Insights

• Deterministic Enforcement vs. Heuristics: CLAUDE.md files offer guidelines, but Git hooks ensure code literally cannot reach the repo without passing checks (Fleek, 2026).
• Error messages as prompt engineering: High-quality hook output containing the rule, violation location, and replacement code enables AI to self-correct on the first retry.
• Documentation integrity via pre-commit: A specific hook at Fleek blocks commits if code changes occur without corresponding updates to the app’s CLAUDE.md context file.
• Universal enforcement: Git hooks apply to all contributors—human or AI—ensuring a consistent standard across Claude Code sessions and CI/CD pipelines.
• Bypass mechanisms: Every hook requires environment variable overrides (e.g., SKIP_CHECK_NAME=1) for instances where human engineers must override the deterministic layer.

Working Examples

A deterministic hook error message designed to serve as a prompt for AI self-correction.

╔══════════════════════════════════════════════════════════════╗
║ console.log DETECTED — commit blocked ║
╚══════════════════════════════════════════════════════════════╝
Found console.* calls in app code:
apps/large-buyer/fe/pages/index.tsx:42: console.log(data)
RULE: Use @fleekit/logger instead of console.* in app code.
import { createLogger } from "@fleekit/logger";
const log = createLogger("my-tool");
log.info({ key: "value" }, "Message here");

Pre-commit hook output enforcing the creation of context files for AI agents.

╔══════════════════════════════════════════════════════════════╗
║ MISSING CLAUDE.md — commit blocked ║
╚══════════════════════════════════════════════════════════════╝
The following app(s) have code changes but no CLAUDE.md:
• apps/large-buyer/
Every app must have a CLAUDE.md describing its purpose,
data sources, business logic, and gotchas.
TO FIX: Create apps/large-buyer/CLAUDE.md before committing.

Practical Applications

• Use Case: Fleek uses a pre-commit hook to replace console.log with @fleekit/logger by providing the exact import and initialization code in the error message. Pitfall: Using generic ‘Error: console.log not allowed’ messages causes AI to spiral into wrong fixes or remove logs entirely.
• Use Case: Automatic documentation maintenance where hooks require updates to CLAUDE.md files when app code is touched to prevent ‘documentation rot’. Pitfall: Relying on human discipline or advisory warnings results in AI agents ignoring 100% of non-blocking warnings.

References:

• https://dev.to/98lenvi/beyond-prompts-how-git-hooks-steer-ai-coding-agents-in-production-4pf9