Мой CLAUDE.md — 582 строки. Шесть слоёв и провал за каждым

Каждый новый чат в Claude Code начинается с нуля. Он не знает проекта, не помнит, что мы обсуждали час назад в соседнем окне, и понятия не имеет, что один порт на одном сервере трогать нельзя. В этом посте я разберу CLAUDE.md, который я построила, чтобы с этим справляться: шесть слоёв, инцидент, из-за которого появился каждый из них, почему хук работает там, где записанное правило не работает, одна настройка, которая не дала взломанному npm-пакету попасть на мою машину, и какие части я оставила бы в обычном проекте. Когда 12 апреля 2026 года вышел русскоязычный оригинал, конфиг был 582 строки.

CLAUDE.md должен решать две задачи одновременно: переносить контекст между сессиями и не допускать необратимых действий. На r/ClaudeAI каждую неделю появляется новая страшилка. Агент удалил продовую базу. Агент запушил секреты в публичный репозиторий. Агент «оптимизировал» биллинговый сервис, пока каждый клиент не получил счёт на ноль. Типичный CLAUDE.md из пяти-десяти строк не решает ни одну из этих задач. Я решила относиться к нему как к архитектурной задаче, а не как к списку пожеланий, и у каждого правила в нём есть конкретная история.

Три инцидента за первыми правилами

Агент «починил» работающую систему. Воскресный вечер. Агент видит 127.0.0.1 в конфиге внешнего хранилища и решает, что предыдущая сессия допустила ошибку. Он вписывает настоящий IP. Загрузки ломаются. Полчаса отладки спустя выясняется, что трафик шёл через SNI-прокси поверх локального туннеля, и 127.0.0.1 был правильным значением. Без контекста очевидное «исправление» и было поломкой.

Правило, которое из этого вышло: не менять конфиг, пока не понятно, почему текущие значения такие, какие есть. Если значение выглядит странно, сначала разобраться, потом действовать.

fail2ban принял агента за брутфорсера. Агент проверял состояние сервера и каждый раз открывал новое SSH-соединение. Дюжина соединений за минуту выглядела как атака, и IP забанили на полчаса. На этой машине как раз шёл тренировочный прогон, и я больше не могла до неё достучаться.

Правило: один SSH-мост на всё, один клиент на сессию, никаких отдельных скриптов для проверки, исправления и верификации. Всё объединяется в один вызов.

«Отфильтровать» оказалось значит «удалить». Я попросила отфильтровать датасет, имея в виду вынуть неподходящие изображения. Агент понял буквально и удалил файлы. Не перенёс и не пометил. Удалил.

Правило: фильтрация означает перенос или пометку, но не удаление. Перед любым удалением проверить, что пользователь просил именно удаление такими словами.

Написать «будь осторожен» не работает. Нужна система.

Шесть слоёв, ни один не был запланирован

Каждый слой появился после конкретного провала.

Правила, 9 файлов. Загружаются по ситуации. Когда агент пишет статью, ему не нужны правила про SSH; когда он отлаживает код, ему не нужны правила про прозу. Claude Code может подтянуть файл правил, который соответствует задаче.

Память, 78 файлов. Появилась, когда агент в третий раз забыл конфигурацию сервера. Между сессиями она хранит настройки инфраструктуры, решения по проекту, мои предпочтения и прошлые ошибки. Файлы ссылаются друг на друга как [[filename]], всего 178 перекрёстных ссылок, так что обычный Markdown превращается в граф знаний. Часть памяти загружается всегда, остальное — по теме.

Handoff-файлы. Появились, когда новый чат прямиком зашёл в тот же тупик, что и предыдущий. Когда сессия заканчивается, агент пишет сводку: что сделано, что НЕ сработало (самое ценное) и одно следующее действие. Настоящий пример, переведённый с русского:

## Session goal
Colour checker: CNN sweep + diffusion, first visual results.

## Done
- CNN baseline: median 1.99 deg (11M params, 21 MB)
- Sweep on 5 GPUs: crop128 (3.17), bs16 (2.04), lr3e-4 (NaN)
- Diffusion training started: epoch 5/50, loss 0.827

## Did NOT work
- EfficientNet-B0: hash mismatch in the Docker image
- lr=3e-4: NaN after epoch 10-13, no gradient clipping
- CNN, visually: three numbers give stray colour casts

## Next step
Inference script for diffusion + visual sheets with 24 patches

Следующий чат читает около 1500 токенов вместо того, чтобы заново разбирать проект. За четыре дня накопилось 27 handoff-файлов, и ни один тупик не повторился. Работает это и между аккаунтами: у меня три подписки, две рабочие и одна личная, и handoff позволяет продолжить в другой без объяснения всего заново. Как это выросло в инструмент для нескольких людей, которые работают одновременно, описано в Несколько Claude в одном репо.

Хроники. Появились, когда после двадцати handoff-файлов стало неясно, как проект пришёл к своему нынешнему состоянию. Handoff отвечает на вопрос «что дальше», хроника — на вопрос «как мы сюда пришли». Ключевые решения, повороты и тупики, три-семь строк на каждую веху.

Хуки. Появились, когда правило «проверь ссылки в CLAUDE.md» перестало соблюдаться через двадцать минут сессии. Следующий раздел посвящён им.

Скиллы, 16. Упакованные знания под конкретные задачи. Описание написано как триггер для модели: «use when: GPU hung, server health check needed», а не как «помогает с серверами».

Правило — это пожелание, хук — это гарантия

Это была самая неочевидная вещь, которую я поняла за тот месяц. Правило в CLAUDE.md — это инструкция в промпте. Модель может её забыть, истолковать по-своему или отбросить поздно в длинной сессии, когда контекст забит другими вещами. Моё правило «проверь ссылки перед работой» продержалось примерно десять минут, а потом агент увлёкся задачей.

Хук — это Python-скрипт, который Claude Code запускает по событию: SessionStart, Stop, PreToolUse. Он не забывает и не переосмысляет. Он срабатывает каждый раз. Вот тот, который просит handoff перед закрытием длинной сессии:

# remind_handoff.py  (Stop hook, simplified)
age = session_age_minutes()
if age < 15:
    return                      # short session, nothing to hand off

if fresh_handoff_exists():
    return                      # already written

print(json.dumps({              # block the close, ask for the handoff
    "decision": "block",
    "reason": f"Session ran {int(age)} min with no handoff. "
              f"Write one into .claude/handoffs/ before exiting."
}))

Модель обычно сама понимает, когда пора: задача закончена или контекст заполняется. Хук закрывает случаи, когда она забывает.

Если что-то должно происходить каждый раз, это хук, а не правило.

Одна строка конфига против атаки через цепочку поставок

31 марта 2026 года официальный npm-пакет axios, примерно 100 миллионов загрузок в неделю, был скомпрометирован через аккаунт одного из мейнтейнеров (Elastic Security Labs). Вредоносная версия 1.14.1 вышла в 00:21 UTC, а плохие версии оставались на npm до 03:15 UTC, то есть около трёх часов (постмортем axios). Microsoft приписывает атаку Sapphire Sleet, государственной группировке из КНДР (Microsoft Security Blog).

В моём .npmrc была одна строка:

min-release-age=7

Пакеты, опубликованные меньше семи дней назад, не устанавливаются. Большинство вредоносных пакетов находят в течение одного-трёх дней, так что семь дней — комфортный запас. На меня это не повлияло, а стоило одной строки. Аналог для Python идёт в uv.toml:

exclude-newer = "7 days"

Исследования за этим: 37 статей

Значительная часть правил появилась не из моих ошибок, а из академических работ: 37 статей arXiv, переработанных в принципы. Четыре из них сильнее всего изменили мой workflow.

• Proof loop. Агент говорит, что тесты проходят; вы проверяете, и они не проходят. Proof loop запрещает агенту подписывать собственную работу. Нужны артефакты: вывод тестов и вердикт верификатора в новой сессии, которая не видела, как делалась работа. Источник: arXiv 2603.10165.
• Структурированные рассуждения. Вместо свободного «может быть так, а может иначе»: что мы точно знаем из кода и логов, пошаговая трассировка, что из этого следует и какие гипотезы проверены и отброшены. В экспериментах Угаре и Чандры такое полуформальное рассуждение подняло точность оценки эквивалентности патчей с 78% до 88% на отобранных примерах и до 93% на реальных патчах, сгенерированных агентами (arXiv 2603.01896).
• Детерминированная оркестрация. Всё детерминированное, например тесты, линтеры и форматирование, идёт через shell-скрипт. Модель теряет счёт в циклах и путает условия веток. Скрипт не путает.
• Красные линии. Обычные правила модель интерпретирует творчески. Красные линии — абсолютные запреты без исключений, и каждый привязан к инциденту: не удалять без подтверждения, не менять продовые конфиги, не разобравшись в них. Паттерн пришёл из китайских инженерных команд, 红线, буквально «красная линия».

Остальное — от генератора-оценщика и autoresearch до многоагентной декомпозиции, кодифицированного контекста, безопасности агентов и целостности документации — описано в репозитории.

Цифры и место, где это не сработало

78 файлов памяти. 178 перекрёстных ссылок. 27 handoff-файлов за четыре дня. Коэффициент попаданий KV-кэша 96,9% на 83 сессиях за неделю. Конфиг поддерживает себя сам: после каждого изменения агент проверяет, не устарели ли ссылки, а хук SessionStart проверяет их автоматически.

Работает ли это идеально? Нет. Аудит нашёл четыре файла памяти, которые выпали из индекса. Дрейф документации внутри системы, созданной именно против дрейфа документации. Без системы было бы хуже.

В чём я не уверена

Я не уверена, что всем нужно всё это. Для большинства проектов, наверное, хватит пяти принципов: детерминированной оркестрации, структурированных рассуждений, защиты цепочки поставок, кодифицированного контекста и handoff-ов.

Я не уверена и в том, что шесть слоёв — это минимум. Возможно, я перестаралась (переусложнила систему). Но за тот месяц ни один контекст не потерялся и ни один тупик не вернулся.

Один из принципов, тестирование допущений, говорит об этом прямо. Каждый компонент конфигурации кодирует допущение о том, чего модель не может сделать сама, а модели улучшаются. Убирайте компоненты и измеряйте. Какой-то слой здесь, вероятно, уже не нужен.

Что изменилось после апреля

Обновление, сентябрь 2026. Репозиторий переименован из claude-code-config в codex-claude-code-config, потому что те же принципы, хуки и скиллы теперь работают и с Codex, и со смешанными сессиями Claude и Codex, а старое название этого уже не описывало. Старый URL перенаправляет. На 23 сентября 2026 года в нём было 30 принципов, 58 скиллов, 35 файлов правил и 73 скрипта в hooks/, а на GitHub — 150 звёзд и 24 форка.

Цифры в разделах выше (9 файлов правил, 78 файлов памяти, 16 скиллов, 37 статей, 582 строки) описывают мою установку на 12 апреля. Тогда они были верны, и я оставила их как есть.

С чего начать

Вставьте это в чат Claude Code:

https://github.com/AnastasiyaW/codex-claude-code-config - study it, pick what fits my work and set up my Claude Code

Начинайте с малого: защита цепочки поставок (одна строка в .npmrc), детерминированная оркестрация (тесты через скрипты) и структурированные рассуждения (формат для отладки). Остальное добавляйте тогда, когда это потребует очередной провал. Всё распространяется по лицензии MIT.

Страница проекта на этом сайте — codex-claude-code-config. Справочная библиотека, которая выросла рядом, описана в 785 статьях для агентов, а не для людей, а почему я доверяю handoff-ам больше, чем собственной истории сессий desktop-приложения, — в 45 МБ сессий Claude Code, которые вы никогда не открываете.