Enforce agent conventions with a pre-commit hook that fails the commit and tells the agent how to fix it, instead of endlessly editing AGENTS.md
Geoffrey Huntley (of Ralph loop fame): when the agent skips your diagnostics library, don't edit AGENTS.md — add a pre-commit hook that scans the diff, fails the commit on bypasses, and prints a fix instruction for the agent. He says it then goes "ten out of ten".
Visit site Git pre-commit hook + any coding agent ↗- Pricing
- Free
- Region
- Global
- Where it's from
- Overseas
- Added
- Oct 17, 2026
- Tested on
- Oct 17, 2026
- Version we used
- git pre-commit hook (Bash), tested with git on Linux 2026-10-17
- Categories
- CodingAutomation & Agents
- Original author
- Geoffrey Huntley @GeoffreyHuntley ↗
- Our test
- Partly tested
- Cost / time
- Free: hooks are built into git, and they work with or without an agent.
The task
Make a coding agent reliably follow a project convention (e.g. all logging/observability goes through one module) instead of hoping prompts or skill packs stick.
Steps
- Pick a convention the agent keeps breaking that a script can detect, e.g. "no direct console.log / observability SDK calls; use the diagnostics module".
- Write .git/hooks/pre-commit (or manage it with husky / the pre-commit framework) that checks only added lines in the staged diff (git diff --cached -U0), excluding the convention module itself.
- On a hit, exit 1 and phrase the output as an instruction to the agent: which line broke the rule, what to use instead, and to commit again.
- Let the agent work normally. When its commit fails it reads that output and fixes the code — the fix prompt is injected back into the loop.
- If a problem shows up three times, add another check. Huntley also suggests deleting skill packs and AGENTS.md every few months to re-evaluate; keep the deterministic checks.
Prompt
Write a git pre-commit hook that checks added lines in the staged diff: if they call console.log / console.error directly (except in src/diagnostics.js), reject the commit and print a fix instruction for the agent — use log() from src/diagnostics.js, then commit again. Afterwards, prove it works with a deliberately violating commit.
What the author says
In his 2026-10-13 post Huntley writes that instead of updating AGENTS.md (there's still a delta and it drifts), he writes a pre-commit hook that checks the git diff for direct calls bypassing his diagnostics module, fails the commit and injects a prompt — "all of a sudden it's ten out of ten". He calls skill packs / AGENTS.md "astrology for software engineers". Simon Willison quoted the passage the same day.
Our test
In a scratch git repo we wrote the hook described above and verified the "block the commit + print a fix instruction" half of the mechanism. We did not run a coding agent loop on a real project, so "the agent self-corrects, ten out of ten" is unverified.
What we found when we tried it:Staging a new console.log("hi") made git commit exit 1, and the hook printed the offending line plus "AGENT: use log() instead, then commit again". After switching to import { log } and log("hi"), the commit succeeded (exit 0). The hook is about 10 lines of Bash.
How to get in
Original is an English blog post at ghuntley.com. The method only needs git, so it works with any agent or model, including Chinese ones.
Who it suits
Engineers running Claude Code / Codex / Cursor agents in long loops who keep fighting "it ignores our conventions".
Pitfalls
- Only works for rules a script can decide; "make it more elegant" can't be gated.
- .git/hooks isn't committed; distribute via husky, the pre-commit framework, or core.hooksPath for teams and cloud agents.
- Agents may bypass with git commit --no-verify — forbid it in agent permissions/instructions, or re-run the same check in CI.
- Scan only added lines or legacy code fails every commit; keep regexes tight, since false positives push the agent to break correct code.
- "Ten out of ten" is the author's experience; we did not run a controlled agent comparison.
More in this category
- A demo video per docs page that flags itself when the UI changesVideoScreenplayClaude CodeTool free; uses your agent's quota◐ Partly testedOverseas
- AI backend code that guards against races, leaks and bad migrationsCodingbackendskillsClaude CodePostgreSQLFree; about 2× tokens per task◐ Partly testedOverseas
- An afternoon of AI work, a 3D action game you play in the browserCodingClaude CodeTripoJimengSkill free; Claude quota plus asset tools◐ Partly testedChina
- Keep a long-running AI-built project from turning into a messCodingClaudeCodexoil-delegateNeeds Claude and Codex plans◐ Partly testedChina
- Use a web app once and get an AI write-up of how it worksResearchREAClaude CodeChromeFree tools; needs Claude or Codex◐ Partly testedOverseas