The seven-line `.gitignore` diff that almost erased our branch guard

Jul 26, 2026 · 3 min read

Updated Oct 13, 2026

Cover image for: The seven-line `.gitignore` diff that almost erased our branch guard

The diff was seven lines removed and seven added in .gitignore: four blanket-ignored .claude/* entries swapped for two narrow un-ignores. Small enough to skim, and small enough to almost ship without checking what else lived in that directory.

The change existed because of one hook. On July 21, a serial leading-wildcard scan (LIKE '%...') crawled six cache tables on the shared live prod DB and wedged it for about five minutes, throwing errors on every customer /accounts page. The fix was a PreToolUse hook, .claude/hooks/block-prod-db-scan.sh, dependency-free, with no ops-tools, node or python required. It inspects any Bash/Write/Edit/MultiEdit payload for a prod-DB connection marker (company_DB_*/company_CACHE_*, DSN=appdb..., pyodbc, sqlcmd, Invoke-Sqlcmd) combined with a leading-wildcard LIKE, and blocks it. The hook itself was straightforward. The hard part was where it had to live to apply to everyone.

Why the hook couldn’t stay personal

A hook only fires if it’s wired into .claude/settings.json. That file had been fully gitignored repo-wide since an earlier fix, so every developer’s settings were local and private, drifting independently. Paste the new guardrail into a single settings.local.json and it protects exactly one clone. Everyone else’s next git pull comes down clean, with no hook, no protection, and no signal that anything is missing.

So the fix was to un-ignore settings.json so the wiring could be shared and version-controlled. That’s the .gitignore diff:

-.claude/settings.local.json
-.claude/settings.json
-.claude/mcp.json
-.claude/*.lock
...
 .claude/*
!.claude/skills/
+!.claude/hooks/
+!.claude/settings.json

Only then did we look at what the shared settings.json would replace, instead of assuming it was blank because it had never been tracked.

The wrong turn

Our first move was to add the new hook entry to settings.json and push it. Fast, minimal diff, done. Before committing we ran git ls-tree -r --name-only origin/develop -- .claude to see what was already tracked on develop, mostly as a formality.

It wasn’t one. Two other hooks were already sitting in .claude/hooks/ on develop: check-branch.sh, a guard that blocks Edit/Write directly on master/develop, and check-learnings.sh. Neither was referenced in any tracked settings.json, because there wasn’t one. Each developer’s settings.local.json was the only thing wiring those hooks in, and it had drifted per clone since the earlier fix gitignored the shared file. We checked .claude across all ten clones:

clone-1    hooks/ skills/ settings.local.json  3.6K
clone-2    hooks/ skills/ settings.local.json  1.0K
clone-3    hooks/ skills/ settings.local.json  549B
clone-4    hooks/ skills/ settings.json  261B settings.local.json  3.6K

The sizes ran from 549 bytes to 3.6K on files with the same nominal purpose. Had we committed a settings.json that wired only the new prod-DB hook, it would have become the tracked source of truth the moment anyone pulled it. check-branch.sh would have stopped firing for them, on develop and master both, the exact branches it exists to protect. We would have traded one incident risk for a second, worse one, and shipped it as a fix.

Shipping all three at once

The change went out with three hooks together: the branch guard, the pre-commit installer, and the new DB scan guardrail, all wired through the newly tracked settings.json. Before pushing, we rehearsed the migration in a spare clone to see what a real developer’s next pull would do. It throws a merge conflict on their local settings.json/settings.local.json instead of silently overwriting. That’s a feature: it forces the 30-second cleanup instead of letting it get skipped.

Then we wrote the message that actually goes out, instead of a changelog entry nobody reads:

FYI, we made some updates to help our development rules stay in sync across developers. This will cause your next pull to throw an error. Run the following prompt to get your local setup back in sync.

A paste-ready prompt was attached, and the two remaining local-config cleanups were filed as their own follow-up. The guardrail now propagates itself. Anyone who cloned since the earlier gitignore change gets the branch guard back, and anyone who clones fresh gets all three hooks by default, with no manual step to forget.

What the diff didn’t show

.claude/settings.json is a dependency graph, and every hook anyone has wired into it depends on whatever gets changed next. git diff on the file you’re changing says nothing about the files that already live next to it. Before sharing a config that was previously local, list what is already tracked and what each clone has wired locally, then ship the related guardrails together.

AI Skills

Use this lesson with the AI assistant you already use

A leading wildcard scan against six shared production cache tables wedged the database for about five minutes and broke every customer accounts page. The proposed hook fix exposed that the shared Claude settings file had been ignored and its existing hook wiring had drifted across ten clones.

Paste the prompt, share only the context needed to answer it, and treat the result as a draft for your review. Do not include confidential information or let an AI assistant make changes without your approval.

Optional: for a visual report and saved memory, run /dxdev first. Don’t have it? Get it at dxdev.com/skills/dxdev. The prompt works without it.

dxdev LESSON · paste into your AI coding agent
LESSON: Treat Shared Tool Settings As Dependency Graphs When Making Guardrail Changes
SOURCE: dxdev.com/blog/shared-guardrails-atomic-deployment
WHAT HAPPENED: A dependency-free hook was created to block production database commands that combine recognized connection markers with leading wildcard LIKE queries. For the hook to protect every clone, .claude/settings.json had to become tracked instead of remaining ignored. Before committing, an inspection of the develop branch found two existing hook scripts that were present but only wired through each developer's local settings. A settings.json containing only the new database hook would have silently displaced the branch guard for developers who pulled it. The team shipped all three hooks together, rehearsed the migration in a spare clone, and warned developers that reconciling local settings would produce a merge conflict.
THE RULE: When making shared configuration authoritative, inventory every existing dependency it can replace or override before publishing it. Ship the complete preserved configuration atomically, and test the migration path that existing local configurations will follow.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
      1. The tracked shared settings file explicitly references every required hook script that exists in the repository.
      2. Before promoting a local configuration file to the shared source of truth, the team has compared its hook entries with configurations across existing clones.
      3. A spare-clone rehearsal confirms whether pulling the configuration change preserves safeguards or forces an explicit merge resolution.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.

Send us what your agent found →

Prefer to talk it through first? Start an assessment or talk to us.

Lesson: Treat Shared Tool Settings As Dependency Graphs When Making Guardrail Changes

Choose your next level of detail

Want the practical version?

How AI Helps starts with the work problem, what improves, and where human judgment still matters.

See how AI helps Talk to us

The seven-line `.gitignore` diff that almost erased our branch guard

Why the hook couldn’t stay personal

The wrong turn

Shipping all three at once

What the diff didn’t show

Use this lesson with the AI assistant you already use

Related in Agent guardrails

selfmanaged Domains and a Cleanup Worker That Needed a Fail-Closed Check

The Approval Gate That Blocked Us for Fifteen Hours and Never Caught a Mistake

The Staff-Center Commits We Reverted Out of Develop

30 Clones, 20 Stale Branches, and Commits That Lived on One Disk

One Line in the Rules Ended a Thousand Small Checkpoints

Want the practical version?

Follow the Build