AIDive

Пакет к видео

Пять правил Claude Code без обхода: хуки, список deny и конфигурация линтера

7 мин чтения

Кратко и вывод

Мы поручили Claude Code настоящие задачи в нашем небольшом API для счетов на TypeScript (Claude Code 2.1.294, Opus 5.5, auto mode) и проверили результат детектором копипаста, проверкой типов и тестами. Затем мы установили по одному механизму на правило: хук или настройку, а не строку в CLAUDE.md.

  • Когда пять правил были записаны прозой в CLAUDE.md, функция A (кредит-ноты) не нарушила ни одного из них: 0 клонов, 45 проходящих тестов (34 базовых плюс 11), ни один тест не удалён, ни одна конфигурация не тронута.
  • Когда правил не было, функция B1 (периодические расписания и CSV-выгрузка) оставила 3 точных клона. Парсер тела счёта был скопирован в парсер расписаний, а шаблонный поиск одного обработчика был скопирован во второй. Проверка типов была зелёной, проходили 47 тестов. Второй проход, B2, оставил все 3 клона на месте.
  • С установленными механизмами мы повторили те же промпты. Хук клонов сработал на обработчике расписаний (jscpd нашёл 1 клон, базовое значение 0), и Claude вынес общую проверку в один метод. Хук новых файлов выдал три запроса разрешения для модулей расписания, на которые мы ответили да, и один для файла utils, на который мы ответили нет, и ничего не было записано. На промпт про enum и interface Claude ничего не правил и назвал конфигурацию линтера и хук. Stop-хук отказал на переименование, сделанное командой оболочки, фразой "Rule 4: tests fail. Not done yet.", и Claude исправил два ожидания. Команда оболочки на tsconfig.json была отклонена оболочкой.
  • Каждый механизм мы также проверили плохой правкой вручную: клон, нарушения линтера, красная сборка и удалённый тест были отклонены.

Вывод: сначала установите stop-хук, затем список deny, который короткий. На одноразовом прототипе пропустите всё это. Хук обеспечивает то, что может показать один вызов инструмента. Верна ли абстракция, решаете вы.

Синтез по источникам

CLAUDE.md это контекст, а не принудительная конфигурация. В документации Claude Code по памяти сказано, что CLAUDE.md и правила загружаются как контекст, а не как принудительная конфигурация s2. Страница с лучшими практиками говорит то же с другой стороны: CLAUDE.md предназначен для рекомендаций, и Claude может решить, что одна из них не относится к делу. Обязательное поведение принадлежит хуку, правилу deny или управляемой настройке s1.

Отсюда два вида инструкций. В первом виде вы пишете строку, а модель её читает: промпт, CLAUDE.md, skill. Во втором виде вы настраиваете проверку, а оболочка её запускает: хук, правило deny, управляемая настройка s1. Пять правил в этом наборе относятся ко второму виду.

Код 2 делает разное в зависимости от события хука. На PostToolUse код 2 показывает stderr Claude, хотя инструмент уже отработал s3. Предупреждение PostToolUse должно завершаться с кодом 2, чтобы дойти до Claude, потому что stderr хука, завершившегося с кодом 0, не виден никогда s3. На PreToolUse код 2 блокирует вызов, даже если хук напечатал решение allow s3. На Stop код 2 блокирует остановку, а всё, что команда печатает в stderr, возвращается Claude как причина, по которой он ещё не может закончить s1.

Хуку Stop нужна защита, и у него есть предел. Хуки Stop получают stop_hook_active, который равен true, когда Claude уже продолжает работу из-за stop-хука, поэтому его нужно проверять, чтобы не блокировать из-за условия, которое никогда не разрешится s3. Документированная защита завершается с кодом 0, когда он равен true s18. Claude Code также применяет предел в 8 подряд идущих продолжений, который поднимается через CLAUDE_CODE_STOP_HOOK_BLOCK_CAP s3. В changelog версии 2.1.143 сказано, что ход теперь заканчивается с предупреждением после 8 подряд идущих блокировок s19.

У PreToolUse четыре решения. Хук PreToolUse возвращает решение в hookSpecificOutput с четырьмя исходами: allow, deny, ask или defer s3. Хук новых файлов в этом наборе отвечает ask, что возвращает вас в цикл в виде запроса разрешения. Хук PreToolUse, вышедший по таймауту, вызов не блокирует. Начиная с 2.1.295 можно задать onFailure: "block", чтобы он блокировал s3 s19.

У matcher есть слепое пятно. Matcher Edit|Write срабатывает только на инструментах Edit и Write, но не на Bash s18. Правки, сделанные через Bash, могут попасть в хук PostToolUse в tool_response.bashEditDiff начиная с 2.1.269, за настройкой bashEditDiffEnabled s3 s19.

Правила deny: используйте Edit(path) и знайте предел. Правило deny Write(path) не срабатывает. Используйте Edit(path), которое покрывает все встроенные инструменты правки файлов s4. Правила deny также не покрывают скрипт на Python или Node, который сам открывает файл s4.

Правила с ограничением по пути и ловушка во frontmatter. Правило с ограничением по пути загружается, когда Claude использует Read, Write или Edit на подходящем файле s2. До 2.1.288 их загружал только Read s19. Если YAML между маркерами не разбирается, Claude Code игнорирует frontmatter и загружает правило так, будто у него нет paths, то есть оно действует везде s2.

jscpd ловит только точные клоны. Запущенный как npx jscpd ., он сканирует клоны. Запуски по умолчанию сообщают только о точных клонах, а переименованные клоны и почти-совпадения включаются отдельно s20. Минимальный размер клона по умолчанию 50 токенов s20. Наш хук снижает его до 30 токенов и 4 строк. В нашем тесте переписанная почти-копия с другими строками и тем же поведением не была поймана.

Почему проверки на каждую правку, а не более длинный CLAUDE.md. SlopCodeBench выяснил, что лучший агент проходит 14,8% контрольных точек. Это доля прохождения, а не доля мусора. Структурная эрозия растёт в 77% траекторий, а многословность в 75,5% s6. Код агентов в 2,3 раза многословнее и в 2,0 раза более эродирован, чем 473 открытых репозитория на Python s6. Явные указания по качеству снижают начальную многословность и эрозию до трети, не влияя на скорость деградации s6. Указания помогают в начале. Проверка на каждую правку действует на наклон.

Stop-хук, который «ничего не делает». Ветка на Hacker News, "Claude is ignoring stop hooks", показывает скрипт, заканчивающийся на cat с кодом 0. Оболочка ничего не блокировала, потому что для блокировки нужен код 2 с причиной в stderr s8.

Чего хук оценить не может. Issue в Claude Code о том, что правила CLAUDE.md не соблюдаются, называет хуки PreToolUse частичной полумерой. Хук обеспечивает то, что может показать один вызов инструмента. «Верна ли эта абстракция?» хуком не решить, а если отключить хук, поведение возвращается s7.

Код

Заметка по установке: settings.json кладётся в .claude/settings.json, четыре скрипта хуков в .claude/hooks/, domain.md в .claude/rules/domain.md, а eslint.config.js в корень репозитория. Добавьте eslint, typescript-eslint и jscpd как devDependencies. Создайте два файла базовых значений: .claude/jscpd-baseline (число клонов) и .claude/test-baseline (число проходящих тестов). Хуки используют jq, а stop-хук вызывает pnpm typecheck и pnpm test, поэтому эти скрипты должны существовать в вашем package.json.

Файл настроек содержит список deny для правила 5 (tsconfig.json, vitest.config.ts, eslint.config.js и .claude/**) и записи хуков для правил с 1 по 4. Положите его в .claude/settings.json.

settings.json

{
  "permissions": {
    "deny": [
      "Edit(tsconfig.json)",
      "Edit(vitest.config.ts)",
      "Edit(eslint.config.js)",
      "Edit(.claude/**)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      { "matcher": "Write", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/new-file-ask.sh\"", "timeout": 10 } ] }
    ],
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/no-clone.sh\"", "timeout": 60 } ] },
      { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/lint-edit.sh\"", "timeout": 60 } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/done-check.sh\"", "timeout": 120 } ] }
    ]
  }
}

settings.json on GitHub

Правило 1, переиспользуй, прежде чем писать. Хук PostToolUse на Edit|Write. Он запускает jscpd на src/ после каждой правки файла .ts, сравнивает число клонов с базовым значением и при росте числа завершается с кодом 2 и местом двойника. Положите его в .claude/hooks/no-clone.sh.

no-clone.sh

#!/usr/bin/env bash
# PostToolUse hook (matcher: Edit|Write). Rule 1: reuse before you write.
# Runs the copy-paste detector on src/ after every edit. A clone that was not
# there at the baseline blocks with the twin's location (exit 2 -> stderr reaches Claude).
set -u
INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
case "$FILE" in *.ts) ;; *) exit 0 ;; esac
cd "$(printf '%s' "$INPUT" | jq -r '.cwd')" || exit 0
BASE=$(cat .claude/jscpd-baseline 2>/dev/null || echo 0)
OUT=$(mktemp -d)
npx --no-install jscpd src --min-lines 4 --min-tokens 30 --reporters json --output "$OUT" --silent >/dev/null 2>&1
COUNT=$(jq '.statistics.total.clones // 0' "$OUT/jscpd-report.json" 2>/dev/null || echo 0)
if [ "$COUNT" -gt "$BASE" ]; then
  echo "Rule 1 (reuse before you write): jscpd found $COUNT clone(s), baseline is $BASE. A helper you just wrote already exists:" 1>&2
  jq -r '.duplicates[] | "  \(.firstFile.name):\(.firstFile.start)-\(.firstFile.end)  ==  \(.secondFile.name):\(.secondFile.start)-\(.secondFile.end)"' "$OUT/jscpd-report.json" 1>&2
  echo "Import and reuse the existing one; do not keep both." 1>&2
  rm -rf "$OUT"; exit 2
fi
rm -rf "$OUT"; exit 0

no-clone.sh on GitHub

Правило 2, никаких модулей, о которых никто не просил. Хук PreToolUse на Write. Когда путь находится в src/, а файла ещё нет, он отвечает ask с причиной, и Claude Code показывает запрос разрешения. Положите его в .claude/hooks/new-file-ask.sh.

new-file-ask.sh

#!/usr/bin/env bash
# PreToolUse hook (matcher: Write). Rule 2: no module nobody asked for.
# Creating a file that does not exist yet under src/ becomes a permission prompt:
# the human says yes or no, the model does not decide alone.
set -u
INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
CWD=$(printf '%s' "$INPUT" | jq -r '.cwd')
case "$FILE" in "$CWD"/src/*) ;; *) exit 0 ;; esac
[ -e "$FILE" ] && exit 0
REL=${FILE#"$CWD"/}
jq -cn --arg r "Rule 2: new module under src/ ($REL). One new file needs a reason: approve only if the task asked for it, otherwise put the code in the module it belongs to." \
  '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"ask",permissionDecisionReason:$r}}'

new-file-ask.sh on GitHub

Правило 3, соглашения это линтер. Хук PostToolUse на Edit|Write, который запускает ESLint на изменённом файле .ts и при любой ошибке завершается с кодом 2. Он только проверяет и никогда не исправляет. Положите его в .claude/hooks/lint-edit.sh.

lint-edit.sh

#!/usr/bin/env bash
# PostToolUse hook (matcher: Edit|Write). Rule 3: conventions are lint, not prose.
# Runs ESLint on the file that was just edited; a violation is a lint error at the
# exact line, every edit (exit 2 -> stderr reaches Claude). Lint only, never --fix.
set -u
INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
case "$FILE" in *.ts) ;; *) exit 0 ;; esac
cd "$(printf '%s' "$INPUT" | jq -r '.cwd')" || exit 0
if ! npx --no-install eslint --no-warn-ignored "$FILE" 1>&2; then
  echo "Rule 3: the conventions above are enforced by eslint.config.js; fix the file, do not change the config." 1>&2
  exit 2
fi
exit 0

lint-edit.sh on GitHub

Правила линтера, которые он запускает: type вместо interface, никакого enum, никакого any, никаких импортов ввода-вывода или хранилища в src/domain/ и никаких прямых импортов хранилища в обработчиках. Положите файл в корень репозитория.

eslint.config.js

// Conventions as lint rules. Run on every edited file by .claude/hooks/lint-edit.sh.
import tseslint from "typescript-eslint";

export default [
  {
    files: ["src/**/*.ts", "test/**/*.ts"],
    languageOptions: { parser: tseslint.parser },
    plugins: { "@typescript-eslint": tseslint.plugin },
    rules: {
      "no-restricted-syntax": [
        "error",
        { selector: "TSInterfaceDeclaration", message: "Use `type`, never `interface` (project convention)." },
        { selector: "TSEnumDeclaration", message: "Use a const object or a union type, never `enum` (project convention)." },
      ],
      "@typescript-eslint/no-explicit-any": "error",
    },
  },
  {
    files: ["src/domain/**/*.ts"],
    rules: { "no-restricted-imports": ["error", { patterns: [
      { group: ["node:fs", "node:http", "fs", "http"], message: "src/domain has no I/O." },
      { group: ["../store/*", "../http/*", "**/store/*", "**/http/*"], message: "src/domain imports nothing from store or http." },
    ] }] },
  },
  {
    files: ["src/http/handlers/**/*.ts"],
    rules: { "no-restricted-imports": ["error", { patterns: [
      { group: ["../../store/*", "**/store/*"], message: "Handlers reach the store through the app context only." },
    ] }] },
  },
];

eslint.config.js on GitHub

Слова соглашений живут в файле правила с ограничением по пути. Он загружается, только когда Claude трогает src/domain/. Следите, чтобы заголовок YAML был валидным, иначе правило загрузится везде. Положите его в .claude/rules/domain.md.

domain.md

---
paths:
  - "src/domain/**"
---
# src/domain: pure functions, nothing else

- No I/O here: no `node:fs`, no `node:http`, nothing from `src/store/` or `src/http/`.
- `type`, never `interface`; const objects or union types, never `enum`; no `any`.
- Money is an integer number of cents; reuse `money.ts` (`assertCents`, `formatCents`, `sum`) instead of writing a new helper.
- One new file needs a reason the task gives. No class, factory or generic helper for one caller.
These conventions are checked by ESLint on every edit (`.claude/hooks/lint-edit.sh`).

domain.md on GitHub

Правило 4, готово значит проверки пройдены. Хук Stop с защитой stop_hook_active. Он запускает проверку типов и тесты, сравнивает число проходящих тестов с .claude/test-baseline и завершается с кодом 2 и выводом ошибок, пока что-то красное или тест исчез. Положите его в .claude/hooks/done-check.sh.

done-check.sh

#!/usr/bin/env bash
# Stop hook. Rule 4: done means the checks passed.
# Refuses the end of the turn while typecheck or tests are red, or while the test
# count dropped under the baseline (a suite made green by deleting tests is red).
set -u
INPUT=$(cat)
# Guard: when Claude Code is already continuing because of this hook, let it stop.
[ "$(printf '%s' "$INPUT" | jq -r '.stop_hook_active')" = "true" ] && exit 0
cd "$(printf '%s' "$INPUT" | jq -r '.cwd')" || exit 0
# Nothing changed since the last commit: nothing to check.
[ -z "$(git status --porcelain -- src test 2>/dev/null)" ] && exit 0
LOG=$(mktemp)
if ! pnpm --silent typecheck > "$LOG" 2>&1; then
  echo "Rule 4: typecheck fails. Not done yet." 1>&2; tail -30 "$LOG" 1>&2; rm -f "$LOG"; exit 2
fi
if ! pnpm --silent test > "$LOG" 2>&1; then
  echo "Rule 4: tests fail. Not done yet." 1>&2; grep -v '^\s*$' "$LOG" | tail -30 1>&2; rm -f "$LOG"; exit 2
fi
BASE=$(cat .claude/test-baseline 2>/dev/null || echo 0)
COUNT=$(grep -oE 'Tests +[0-9]+ passed' "$LOG" | grep -oE '[0-9]+' | head -1)
rm -f "$LOG"
if [ -n "$COUNT" ] && [ "$COUNT" -lt "$BASE" ]; then
  echo "Rule 4: $COUNT tests passed, the baseline is $BASE. A test disappeared; restore it." 1>&2; exit 2
fi
exit 0

done-check.sh on GitHub

Сделайте это в понедельник

  • Выполните claude --version и убедитесь, что у вас 2.1.288 или новее, чтобы правила с ограничением по пути загружались на Write и Edit s19.
  • Установите eslint, typescript-eslint и jscpd как devDependencies и проверьте, что jq есть в вашем PATH.
  • Сначала скопируйте done-check.sh, создайте .claude/test-baseline с текущим числом проходящих тестов и добавьте запись Stop в .claude/settings.json.
  • Добавьте список permissions.deny со строками Edit(...) для конфигурации компилятора, конфигурации тестов, конфигурации линтера и .claude/**. Не пишите строки Write(...).
  • Скопируйте eslint.config.js, выполните npx eslint src на нетронутом репозитории и исправьте или зафиксируйте базовым значением всё найденное, прежде чем подключать хук.
  • Выполните npx jscpd src --min-lines 4 --min-tokens 30, запишите число клонов в .claude/jscpd-baseline, затем добавьте no-clone.sh и new-file-ask.sh.
  • Скопируйте domain.md в .claude/rules/, подгоните путь под свои папки и проверьте, что заголовок YAML разбирается.
  • Повторите жест, для которого написано каждое правило, и прочитайте отказ. Затем правкой вручную проверьте на одном файле, что правило срабатывает.

Измерения

Наш прогон: небольшой API для счетов на TypeScript с 34 тестами, Claude Code 2.1.294, Opus 5.5, auto mode, 2026-11-07. Клоны подсчитаны jscpd с --min-lines 4 --min-tokens 30.

Настройка Заданные функции Клонов найдено jscpd Тестов проходит Что сработало
Правила прозой в CLAUDE.md A: кредит-ноты (1 мин 21 с) 0 45 (34 базовых + 11) Срабатывать нечему. Ни одно правило не нарушено
Правила не записаны B1: периодические расписания и CSV-выгрузка (2 мин 27 с) 3 47 (34 + 13) Ничего не установлено. 3 новых модуля, изменено 14 файлов
Правила не записаны B2: endpoint отмены и две CSV-выгрузки (около 1 мин 30 с) 3, те же 55 Ничего не установлено. Claude вынес src/http/csv.ts и переиспользовал его
Механизмы включены, живой повтор Снова B1, затем рефакторинг enum, торопливое переименование, удаление хука и изменение tsconfig 0 в конце 54 Хук клонов один раз (1 клон, базовое значение 0), 3 запроса новых файлов плюс 1 отклонённый, хук линтера не понадобился, stop-хук один раз, deny один раз
Механизмы включены, механический тест Плохие правки вручную 0 на базовом, 1 после вставки 5-строчной копии formatCents 33 из 34 после удаления одного теста Хук клонов, запрос новых файлов, хук линтера (4 ошибки), stop-хук (сборка красная, число тестов ниже базового)

Подробности механического теста. Конфигурация ESLint дала 0 проблем на нетронутом репозитории. lint-edit.sh на файле с импортом node:fs, interface, enum и any сообщил о 4 ошибках на их строках и завершился с кодом 2. Хук клонов сообщил domain/money.ts:21 == http/views.ts:5. Путь под src/, которого не существовало, вернул ask с причиной. Stop-хук сказал "Rule 4: 33 tests passed, the baseline is 34. A test disappeared; restore it." Переписанная почти-копия jscpd не поймана.

Что дальше

Что мы оставили за пределами пяти правил и где каждому место.

Git-хуки и Lefthook. Git-хук или шлюз конвейера это допустимое место для тех же проверок. Он срабатывает при коммите, а не пока Claude правит, поэтому обратная связь приходит позже. Это другая настройка, не входящая в этот набор. Если набор тестов идёт минуты, оставьте быструю часть в stop-хуке, а остальное перенесите в конвейер.

Prompt-хуки уровня агента. Хуки, которые просят модель оценить правку, недетерминированы, поэтому не входят в пятёрку. Правило, которое можно проверить командой, принадлежит скрипту.

Команды ревью. /simplify и /code-review запускаются вручную. Они полезны, но ревью остаётся за вами, и ни одна из них не является принудительным механизмом.

Цифры вендоров об инцидентах. Отчёты вендоров о частоте инцидентов на pull request это сигнал корреляции, не специфичный для Claude Code и не измеренный на нашем коде. Мы их не использовали. Каждая цифра в этом наборе взята из источников по ссылкам выше или из нашего прогона.

Готовый набор правил. Репозиторий anti-slop это вендорный набор правил Oxlint с 18 общими правилами и 5 правилами Effect. Он предназначен для вендоринга, официального пакета npm нет s10. Это хорошая модель правила: ошибка линтера на нужной строке при каждом запуске.

Правила прозой. Сборники правил для CLAUDE.md полезны для слов соглашения. Держите их в файлах правил с ограничением по пути, а гарантию отдайте проверке.

FAQ

Останавливает ли правило deny скрипт на Python, который пишет файл? Нет. Правила deny не покрывают скрипт на Python или Node, который сам открывает файлы s4. Тот, у кого есть ключи, всё равно может править файл вручную. Список deny останавливает встроенные инструменты правки агента и очевидные обходные пути.

Почему мой stop-хук никогда не блокирует? Сначала проверьте код завершения. Для блокировки нужен код 2 с причиной в stderr. Скрипт, заканчивающийся на cat с кодом 0, не блокирует никогда s8. Затем проверьте защиту: если stop_hook_active равен true, хук должен завершаться с кодом 0. Предел также заканчивает ход после 8 подряд идущих блокировок s3.

Ловит ли matcher Edit|Write правки через Bash? Нет. Он срабатывает только на инструментах Edit и Write, но не на Bash s18. Начиная с 2.1.269 diff файлов, изменённых командой Bash, можно добавить в результат инструмента Bash за настройкой bashEditDiffEnabled s19. Наш stop-хук всё равно ловит результат, потому что в конце хода запускает проверку типов и тесты.

А что с файлами, созданными командой оболочки? Файл, созданный так, не является вызовом инструмента Write, поэтому хук новых файлов его не видит. Добавьте matcher Bash, если нужно за этим следить, или просмотрите git status в конце хода.

Отменяет ли хук правку? Нет. Хук PostToolUse запускается после инструмента, который уже отработал. С кодом 2 он показывает stderr Claude s3. Затем Claude исправляет файл. Действие до его выполнения останавливают только хук PreToolUse и список deny.

Файлы