claude-stack

Рабочий сетап Claude Code — главная сессия и субагенты по умолчанию работают на Opus 5.5, Fable 5.1 — только агент fable-deep по явному разрешению; собран вокруг трёх идей:

  1. Main session — decider, а не печатная машинка. Главный поток думает, планирует и ревьюит; весь код и все правки пишут дешёвые субагенты. Правило текстовое, в глобальных инструкциях; хук-гейт на Edit/Write в главном потоке был и снят: правки через Bash он не видел, поэтому реальные записи проходили мимо него.
  2. Токен-экономия — дисциплина, а не оптимизация постфактум. Матрица моделей по сложности задачи, эскалация вместо угадывания, внешние дешёвые воркеры под рутину, /clear на границе задач.
  3. Память — на диске, а не в контексте. Состояние задач, факты о проекте и хроника сессий разнесены по разным файлам с чёткими границами: что где лежит и кто это пишет.

В репозитории — переиспользуемые куски этого сетапа: скиллы, агенты, хуки, скрипты и slash-команды. Ничего специфичного для конкретной компании или инфраструктуры здесь нет — это методология и тулинг, конфиги подставляются под свой проект.

Рассчитано на опытных разработчиков, которые уже работают с Claude Code и хотят собрать похожий контур себе.

Живая версия страницы: claude.zardes.dev. Репозиторий: github.com/zarudesu/claude-stack.

Разбор трендов рынка coding-харнесов (снэпшот на конец августа 2026) — docs/harness-trends-2026-08.md.

Содержание

Архитектура сессии

Главная модель сессии (Opus 5.5) отвечает за три вещи: ставит задачу, выбирает исполнителя, ревьюит результат. Код она не правит и массово не читает — поиск и чтение уходят в Explore или специалиста, правки в субагента; точечный просмотр известного файла ради ревью или решения допустим. Это текстовое правило в глобальных инструкциях.

Почему без хука: раньше правило держал хук decider-gate на PreToolUse для Edit/Write/MultiEdit/NotebookEdit; его сняли, потому что правки через Bash (heredoc, sed -i) он не ловил и реальные записи из главного потока проходили мимо.

Сессии и параллельные окна

Матрица моделей по сложности

Субагентов запускают с моделью и уровнем effort, минимально достаточными для задачи — не «на всякий случай мощнее». Дефолт субагента — opus (Claude Opus 5.5, CLAUDE_CODE_SUBAGENT_MODEL=opus), effort medium: на medium Opus 5.5 держит уровень Opus 5 на high примерно за половину токенов.

Модель Сложность Примеры задач
haiku Механика/read-only Explore, поиск файлов, чтение конфигов, grep, запуск готовых команд — не код
opus, effort medium Основная работа Написание кода, фиксы багов, рефакторинг, тесты, IaC, диагностика, планирование
opus, effort high Сложные Ревью кода, аудит безопасности, архитектура, консультант эскалации
sonnet Фоллбек Горящий недельный лимит, массовый boilerplate (или внешний воркер qwen)
local (Ollama, ask -l) Рутина по точному брифу, приватное Механика и boilerplate по точному брифу, приватный код, офлайн, чтение длинных документов — не ревью и не решения (см. «Локальная модель»)

Цены за 1M токенов (вход/выход, на октябрь 2026): Haiku 5.5 — $0.10/$0.50 (промпт до 100K; выше — $0.50/$2.50), Sonnet 5.5 — $2/$10, Opus 5.5 — $4/$20 (чтение кэша $0.20), Fable 5.1 — $10/$50, local (Ollama) — $0. Откат всех субагентов на sonnet при горящем лимите — переменной CLAUDE_CODE_SUBAGENT_MODEL=sonnet; если у агентов задан model: во frontmatter (с 2.1.251 он перебивает переменную), нужен ещё CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (2.1.257+).

Правила выбора: по умолчанию — opus на effort medium; haiku — только read-only механика, не код; effort high — ревью, security audit, архитектура и second opinion; сначала снижай effort, потом меняй модель, sonnet — только фоллбек; Explore-агент всегда на haiku (он для быстрого поиска); Plan-агент — opus, effort high (качество планирования критично для последующих фаз). Самый тяжёлый хвост задач по-прежнему за Fable, но только по явному разрешению (fable-deep).

Матрица не бралась с потолка — периодически проверяется replay-эвалом на реальных смёрженных PR (4 приватных репозитория, 2 стека). Методология: репозиторий клонируется через git clone --no-local, в клоне срезаются все ветки, теги и reflog до состояния «перед PR» — агент не должен видеть будущий мёрдж через git log --all. Ранняя версия эвала на worktree вместо изолированного клона этой защиты не имела: агент подсматривал будущий коммит через git log --all и копировал его побайтово, из-за чего jaccard 1.0 получался «из воздуха», а не из реальной работы модели.

Итог 117 прогонов:

Модель n mean jaccard пустых диффов jaccard ≥ 0.8 cost duration
haiku 38 0.21 61% 11% $0.24 173с
sonnet 38 0.49 8% 24% $0.91 457с
opus 38 0.60 3% 32% $1.86 401с
fable 3 (проба) — — — — —

Устойчивость по репозиториям (mean jaccard haiku/sonnet/opus): 0.18/0.54/0.54, 0.25/0.45/0.57, 0.14/0.50/0.66, 0.26/0.50/0.63 — разброс между репозиториями заметный, но порядок моделей (opus ≥ sonnet ≫ haiku) стабилен на каждом из четырёх.

Fable-проба (n=3, вывод предварительный — выборка слишком мала для полноценного места в матрице): паритет с sonnet на 2 задачах из 3; на одной MR fable дал jaccard 1.00 за $0.87/48с там, где sonnet сдался (jaccard 0.00), а opus взял её за $2.12/305с с jaccard 0.42.

Выводы: haiku снят из маршрутизации кода целиком — 61% пустых диффов означает, что модель в большинстве случаев не вносит изменений вообще, а не вносит их плохо. В августе по итогам эксперимента дефолтом для кода был sonnet, а opus подключался при затыке или на критичном коде; с выходом Opus 5.5 (сентябрь 2026) дефолт субагентов — opus на effort medium, sonnet остался фоллбеком (см. матрицу выше). MR больше ~30 изменённых файлов уверенно не решает ни одна модель (диапазон mean jaccard 0.11–0.52 по всем трём) — это сигнал декомпозировать задачу, а не менять тир модели. Даже лучшая модель в выборке доводит до jaccard ≥ 0.8 только около трети задач.

Ограничения методологии, честно: скоринг v1 — jaccard по набору изменённых файлов плюс объём диффа, без семантического сравнения содержимого. Прогон тестов на replay-патче не делался — эвал проверяет, что патч похож по форме на человеческий, а не что он рабочий. Оба пункта — кандидаты на v2, а не скрытые допущения.

Сам инструмент — scripts/golden-pr-replay.py, три подкоманды: list --repo /path/to/repo (нетривиальные merge-коммиты репозитория с долей lockfile/generated строк), run <merge_sha> --model haiku|sonnet|opus|fable --repo /path/to/repo (один replay с контаминационной защитой и записью метрик в results/), report (сводная таблица по всем прогонам).

Эскалация вместо угадывания

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

Лимит — 1-2 эскалации на задачу.

Внешние дешёвые воркеры (OpenRouter)

Рутинные атомарные задачи (саммари, парсинг, конвертации, boilerplate, кодовые правки по точному брифу) можно вынести за пределы подписки на внешние модели через OpenRouter — это дешевле любого тира Claude на порядок.

or-task.sh [-m flash|pro|qwen] [-o max_tokens] [-t timeout_s] "бриф" [файл ...]

Алиас Класс модели Для чего
flash (дефолт) компактная модель общего назначения саммари, парсинг, конвертации, boilerplate, черновики
pro модель среднего класса тяжёлые черновики и планы
qwen code-специализированная модель кодовые правки по точному брифу — самая буквальная из трёх

Встроенные ограничители: cap на max_tokens (по умолчанию 4096), таймаут на весь вызов (по умолчанию 180 с), cap на объём входа (~300k символов — больше делить задачу, не заливать целиком). Ключ читается из локального env-файла, никогда не коммитится.

Фоллбэки — тихая замена исполнителя запрещена, всё проговаривается в чате:

  1. Сбой API → один ретрай → sonnet-субагент с явной пометкой, что сработал фоллбэк.
  2. Провал качества → один ре-бриф той же модели → эскалация на opus; не больше одного круга.
  3. Аномальная цена вызова (вышла за ожидаемые cap’ы) → стоп и отчёт пользователю, а не тихое продолжение.
  4. Ключ невалиден или баланс исчерпан → явное сообщение, дальше работа на подписке с пометкой в сессии.
  5. Автоматического отката вниз по качеству нет — понижение тира только осознанным решением на новой задаче.

Результат внешнего воркера всегда ревьюит main сам (diff или вывод читает, а не верит отчёту) — скоупинг чужой работы дороже самой экономии, если его пропустить.

Локальная модель (ask)

scripts/ask [--to claude|local|codex | -c|-l|-x] [-p] [--dry] [prompt] [-- target-args] выбирает исполнителя до запуска модели: флаг > файл правил ~/.config/router/rules (строки target<TAB>cwd|text<TAB>pattern, первое совпадение) > claude. local — тот же Claude Code, направленный на Ollama (ANTHROPIC_BASE_URL=http://localhost:11434): все алиасы моделей и субагенты переназначены на локальную модель, плагин памяти выключен (иначе локальная сессия уходит в облачную суммаризацию), auto-compact 120k. Модель — Qwen3.6-35B-A3B (MoE, IQ4_XS, контекст 128k, ~20 GB) на M1 Max 32 GB.

Local стоит $0, и данные не покидают машину. Поэтому туда идёт рутина и механика по точному брифу, приватный код (в том числе корпоративный: это не внешний API, в отличие от OpenRouter), офлайн-работа и чтение длинных документов. Не идут ревью, security, архитектура, многофайловая отладка и решения. Из Claude-сессии: ask -l -p "<бриф>" -- --max-turns 15 в фоне, diff ревьюит главная сессия, провал → один ретрай → облачный субагент. Задачи, от которых облачная модель отказалась, в локальную не пересылаются: маршрут выбирается до модели по типу задачи. Внутри local-сессии без /pm и параллельных агентов — GPU одна.

Замер (2026-10-25, Ollama 0.40.11) Результат
Prefill 680 t/s до 8k, 490 t/s на 32k, 274 t/s на 110k
Decode / кэш префикса 53 t/s; повтор 0.24 с вместо 53 с
Первый ход Claude Code 35–55 с
HumanEval / свой набор кода 14/15 / 3/5
Agentic-задачи 3/3 (4–15 мин, 10–11 ходов, --max-turns ≥3)
Tool calling / needle 17/20 / 12/12 до 110k
SWE-Pro (публичный) 49.5 против Haiku 5.5 64.8 / Sonnet 5.5 81.3

PM-конвейер

Скилл pm — оркестрация нетривиальных задач: main не делает работу сам, а решает, распределяет по субагентам и сводит результат. Работает как для кода, так и для не-кодовых продуктовых задач.

Phase 0 — Classify

Три вопроса без запуска агентов:

  1. Greenfield или brownfield? С нуля → сначала выбор паттерна (Phase 0a); правка существующего → сначала research конвенций (Phase 1).

  2. Размер задачи:

    Size Триггер Воркеры Роль main
    S <50 строк / 1-2 файла / понятный фикс 1× opus (medium) супервизия + ревью
    M (дефолт) 50-500 строк, 1 модуль 2-3× opus (medium) план + сведение
    L 500+ строк, много модулей 4-6 разных моделей полный конвейер
    XL архитектура / больше пары дней / auth-payments-данные 6-10 разных моделей, effort max полный конвейер + аудит безопасности
  3. Меняешь общий интерфейс? (адрес, host, порт, DNS, схема БД, контракт API, формат сообщения). Если да — задача превращается из «поднять артефакт» в «не сломать потребителей»: обязателен инвентарь потребителей ДО переключения и проверка со стороны каждого потребителя ПОСЛЕ, а критерий готовности строится из потребителей, а не из самого артефакта.

Когда /pm не нужен: 1-2-строчная правка в файле, который уже открыт; прямой ответ на вопрос; чистая документация или опечатка — если main сделает быстрее сам, чем брифовать агента, не оркеструет.

Чек-лист смены общего интерфейса

Пять шагов, если ответ на вопрос 3 — «да»:

Phase 0a — выбор паттерна (только greenfield)

Для задачи с нуля, без референса в текущем репозитории, один агент-архитектор (opus, effort high) предлагает 2-3 паттерна реализации в формате «паттерн плюсы минусы для чего лучше подходит риск» и финальную рекомендацию. Очевидный выбор фиксируется в plan.md под отдельным разделом; близкие по весу варианты выносятся на явный выбор пользователя, а не решаются молча. Дальше конвейер не идёт без зафиксированного паттерна — это самая дешёвая точка для смены архитектурного решения, дальше цена ошибки растёт.

Research → Plan → Worker resolution

TDD-цикл

Обязателен для: фиксов багов (тест, воспроизводящий именно сценарий из репорта, пишется до фикса), контрактов API, бизнес-логики, критичного кода. Пропускается для UI-правок, конфигов, чистого рефакторинга при существующих тестах, спайков, документации.

Цикл: Red (агент-автор теста подтверждает, что тест падает) → main читает диф теста (нет ли подгонки под ответ, пустых assertion’ов) → Green (агент-разработчик доводит до зелёного минимальными правками) → опционально Refactor.

Каждый бриф разработчику включает обязательный блок «Правила кода»: минимум кода без фич сверх брифа; трогать только заявленные файлы, не улучшать соседнее; каждая изменённая строка должна прямо следовать из брифа; критерий успеха прогоняется перед отчётом, вывод прикладывается. Без этого блока в брифе агент по умолчанию «улучшит» половину файла заодно.

Verify — из точки потребителя, не оператора

Ключевое правило фазы верификации: собственная машина — почти всегда точка с гарантированно рабочим внешним путём, поэтому проверка с неё даёт ложный зелёный (классическая ловушка: запрос снаружи отвечает 200, а потребитель во внутренней сети лежит). Каждый потребитель проверяется с его собственного хоста и его собственного реального пути аутентификации — подстановка своего или пустого креда вместо того, что реально использует потребитель, даёт ложный FAIL (401/403 на рабочем сервисе). При «connection refused» от потребителя сначала проверяется, слушает ли сервис на его реальном адресе — в большинстве случаев дело в адресе или маршруте, а не в самом сервисе.

Verify возвращает вердикт PASS/FAIL/WARN с issues, размеченными по severity, где каждый issue мапится на конкретную непройденную букву CLEAR. FAIL уводит обратно в фазу разработки с точным диффом и списком issues; WARN — на обсуждение; PASS — в фазу сведения.

Модели по ролям в конвейере

Роль Модель
PM (main) Opus 5.5 (модель сессии), effort high
Research / аналитик / разработчик / тестировщик / git-workflow-manager opus (Opus 5.5), effort medium
Архитектор / code-reviewer / security-auditor / критичное ревью / планировщик opus (Opus 5.5), effort high
Explore / точечный lookup / механика (поиск, чтение, запуск команд) haiku
Boilerplate по точному брифу внешний воркер qwen; приватный код → ask -l -p
Фоллбек при горящем недельном лимите sonnet

Сначала снижай effort, потом меняй модель; sonnet — только фоллбек. Дорогой уровень (effort high, Fable) — это выбор для конкретной развилки, а не тир по умолчанию.

Reconcile и hard caps

Main читает артефакты задачи, заполняет Outcome в plan.md (что сделано, что нет и почему, какие решения принял пользователь), закрывает или обновляет строку в _active.md, предлагает /clear. Планы не удаляются — это журнал аудита.

Жёсткие ограничения конвейера: не больше 3 параллельных research-агентов; 1 dev-агент на файл; не больше 10 параллельных агентов в одной волне; крупные артефакты уходят в файлы задачи, в чат — только ссылка и короткое summary.

Частые провалы конвейера

Список составлен по фактическим повторяющимся ошибкам, а не гипотетически:

Принципы

Karpathy guidelines

Четыре поведенческих правила против типичных ошибок LLM при написании кода:

  1. Think Before Coding — не угадывать. Допущения проговариваются явно; если возможно несколько трактовок задачи — они показываются, а не выбираются молча; если есть путь проще — об этом говорится вслух; неясность — повод остановиться и спросить, а не продолжать.
  2. Simplicity First — минимум кода, решающего задачу. Без фич сверх запрошенного, без абстракций ради одноразового кода, без «гибкости про запас», без обработки невозможных сценариев. Написал 200 строк, а могло быть 50 — переписать.
  3. Surgical Changes — трогать только то, что нужно. Не «улучшать» соседний код, комментарии или форматирование по пути, не рефакторить рабочее, сохранять существующий стиль. Чужой мёртвый код — упомянуть, не удалять.
  4. Goal-Driven Execution — определить проверяемый критерий успеха до реализации и крутить цикл до его выполнения. «Исправь баг» превращается в «напиши тест, воспроизводящий баг, затем сделай его зелёным».

CLEAR — самопроверка результата

Перед тем как выдать нетривиальный результат — код, план, ресёрч, фактическое утверждение — он молча прогоняется по пяти буквам. Пункт не проходит — чинится; пункт нельзя проверить — это помечается явно, а не выдаётся как факт.

Karpathy-правила задают критерий до работы, CLEAR проверяет результат после — они дополняют друг друга, а не дублируют.

Терсе-режим (caveman)

ALWAYS-ON: режет преамбулы, пересказ вопроса, вежливые концовки и hedging, оставляя код, команды, пути, конфиги, ошибки и числа байт-в-байт. Не применяется к текстам, которые явно попросили развёрнуто, и к текстам для внешних адресатов (commit message, PR description, письма) — там обычный стиль. Выключается на сессию словами «caveman off» / «verbose».

Краткость касается только текста, который читает пользователь: работу в tool-loop режим не урезает, а субагентам как лимит длины не передаётся — в брифах сжимается стиль, а не информация. Основание — постмортем Anthropic от 2026-04-23: лимит «≤25 слов между tool calls» дал −3% качества кода и был откачен.

stop-slop — вычистка AI-следов

Прогоняется через любой текст перед тем, как он уйдёт наружу — в тикет-трекер, рабочие чаты, коммиты, PR, командную документацию. Вычищает: прямые упоминания AI/модели/ассистента; мета-ссылки на внутреннюю кухню ресёрча; характерные буззворды (delve, leverage, comprehensive, robust, seamless, streamline, consolidate, modernize, enhanced, utilize, facilitate, ensure, foster, unlock, empower — и их русские аналоги вроде «обеспечивает бесшовную интеграцию»); обращение к себе в третьем лице; сводочный тон («вот краткая сводка», «в заключение»); оверэксплейн там, где хватит строки; симметричные списки-ради-списков и эмодзи-заголовки. На выходе — только чистый текст, готовый к отправке.

Отдельное жёсткое правило, действующее всегда и без исключений: никаких упоминаний AI/Claude/GPT/нейросетей в коммитах, PR, комментариях к коду и Co-Authored-By. Весь код и все коммиты должны выглядеть как обычная работа разработчика.

Скиллы

В репозитории — полный набор: 89 директорий скиллов в skills/, а не только избранные. Сторонние скиллы, поставленные из апстрима целиком, несут файл .source: репозиторий, коммит и лицензия, если она указана. Скиллы Anthropic (docx, pdf, pptx, xlsx, skill-creator, docs, morning, import-memory) приходят автоматически из claude.ai в ~/.claude/skills/synced/ и в репозиторий не копируются (проприетарная лицензия); их публичные версии — github.com/anthropics/skills. Активны (не выключены через skillOverrides) — 36; ещё 53 припаркованы через skillOverrides в settings.json, чтобы не платить контекстом за скиллы, которые нужны редко (в основном маркетинг-пак: реклама, SEO, копирайтинг, пришлось выключить целиком — 8 августа 2026 они съедали заметную часть контекста каждой сессии просто на листинг). Каталог припаркованных — skills-parked.md в корне репы.

Ещё один рычаг экономии контекста, помимо парковки: справочные куски, которые раньше жили прямо в CLAUDE.md (внешние воркеры OpenRouter, Vaultwarden-анлок), вынесены в собственные скиллы (or-task, vaultwarden-unlock) — они грузятся по триггеру задачи, а в CLAUDE.md от них осталось по строке-указателю.

Механика самообслуживания: если задача пахнет доменом припаркованного скилла — не нужно ждать, пока кто-то включит его насовсем. Каталог skills-parked.md держит список имён и однострочных описаний; текущая сессия читает нужный SKILL.md напрямую и следует ему без активации харнесса. Если домен всплывает регулярно — имя скилла убирается из skillOverrides, и со следующей сессии он снова в общем листинге.

Ключевые активные скиллы:

Скилл Что делает
pm Оркестрация нетривиальных задач — декомпозиция, подбор агентов, TDD-цикл, сведение результата (см. раздел выше)
sec Хардкорный security-аудит — секреты, SAST, CVE зависимостей, контейнеры, сеть, TLS, авторизация; шире встроенного diff-only ревью
karpathy-guidelines Четыре поведенческих правила против типичных ошибок LLM в коде (см. раздел выше)
caveman Терсе-режим вывода, ALWAYS-ON (см. раздел выше)
stop-slop Вычистка AI-следов и буззвордов из любого текста перед отправкой наружу
or-task Делегирование рутинных задач дешёвым внешним воркерам через OpenRouter (см. раздел «Внешние дешёвые воркеры»)
vaultwarden-unlock Автоанлок Vaultwarden через keychain без интерактива для проектов, где это настроено
systematic-debugging Систематический разбор бага или неожиданного поведения перед тем, как предлагать фикс
test-driven-development TDD-цикл при реализации любой фичи или бага — тест до кода
verification-before-completion Обязательный прогон верификационных команд с подтверждённым выводом перед заявлением «готово»
code-quality Envelope качества вокруг нетривиального кода — типы тестов, покрытие, мутационное тестирование, quality gates
grilling Стресс-тест плана или решения через серию въедливых вопросов

Полный список — см. директорию skills/ и skills-parked.md.

ground-truth — проверяемая память проекта

skills/ground-truth строит для репозитория (или группы связанных репозиториев) память, которой новая агентная сессия может доверять без повторного исследования. Первый init один раз тщательно исследует проект и складывает результат в сам репозиторий: карту областей и зависимостей, STATUS.yaml с проверяемыми утверждениями (у каждого — путь в коде и тест или проба, которая краснеет, если утверждение перестало быть правдой), учёт долга и отпечатки источников, по которым видно, что знание устарело. Дальше работают дешёвые режимы: context выдаёт исполнителю короткий пакет только по нужной области, sync после правки обновляет затронутые знания и их потребителей, audit проверяет, не разошлись ли знания с кодом. Новые или повышенные утверждения принимаются только после цикла baseline green → осмысленная мутация red → восстановленный green. Установщик (pipeline/stages/i9_install.py) кладёт в репозиторий верификатор, хуки SessionStart/Stop/PreToolUse и CI-job; скилл вызывается только вручную (disable-model-invocation: true). Проверка самого скилла без модельных вызовов — selftest/run.py, selftest/hooks_smoke.sh, selftest/process_checks.py, selftest/memory_checks.py (нужны PyYAML, pytest и git; на macOS — GNU coreutils первыми в PATH).

Slash-команды

Не скиллы, а промпт-файлы в ~/.claude/commands/ — в репозитории лежат в commands/:

Команда Что делает
/handoff Пишет файл передачи сессии в docs/summaries/ по шаблону — для следующего окна или коллеги
/status Отчёт о состоянии проекта по brief’у и последнему handoff’у
/process-doc Разбирает входной документ в структурированное резюме источника (точные числа, требования, открытые вопросы)
/create-worktrees Создаёт git worktrees под открытые PR или переданные ветки и убирает stale-записи
/run-pre-commit Гоняет pre-commit и чинит падения, пока не станет зелёным, без --no-verify
/time-report Обёртка над scripts/time-report.py; ссылка на Grafana берётся из $OTEL_GRAFANA_URL

/handoff, /status и /process-doc рассчитаны на templates/claude-templates.md и docs/summaries/ в проекте — без них их нужно адаптировать.

Агент-флот

14 постоянных агентов, каждый — под конкретный домен, а не универсальный general-purpose. Принцип из description: конкретные триггер-фразы, а не общие формулировки — от этого зависит, сработает ли авто-делегация.

Агент Модель Назначение
ansible-devops opus, effort medium Playbooks, роли, inventories, vault, CI/CD, docker-compose оркестрация
code-reviewer opus, effort high Ревью диффов, MR/PR — корректность, безопасность, производительность, соответствие конвенциям проекта
database-administrator opus, effort medium PostgreSQL и Redis — репликация, тюнинг запросов, индексы, connection pooling, бэкапы
deep-explore opus, effort medium Разбор незнакомого кода через grepai — семантический поиск по смыслу и граф вызовов (trace); лежит на уровне общего воркспейса проектов, а не глобально
debugger opus, effort medium Баги в коде — стектрейсы, исключения, логические ошибки, гонки, утечки памяти (не инфраструктура)
dependency-manager opus, effort low Аудит зависимостей — CVE, версии, lockfile-гигиена, лицензии
docker-expert opus, effort medium Dockerfile, multi-stage сборки, размер образа, сканирование CVE/SBOM
fable-deep Fable 5.1, 1M контекст, effort xhigh, read-only (Read, Grep, Glob, Bash) Архитектурные решения по всему репозиторию, cross-cutting рефакторинг, сложная отладка, требующая всего кодбейса в одном окне — только по явному разрешению на конкретный вызов, никогда не авто-триггерится
git-workflow-manager opus, effort medium Ветвление, релизная автоматизация, changelog, pre-commit хуки, conventional commits
infra-debugger opus, effort medium Диагностика инфраструктуры и сервисов по строгому циклу S0-S6, факты прежде фиксов
network-engineer opus, effort medium Проектирование и хардненинг сети — VPN, файрвол, DNS, роутинг, NAT/hairpin, TLS
performance-engineer opus, effort medium Профилирование, поиск узких мест, нагрузочное тестирование, кэширование
security-auditor opus, effort high Глубокий анализ безопасности — auth-флоу, сессии, секреты, PII, доступы, криптография
terraform-engineer opus, effort medium Terraform — модули, ревью plan/apply, state backend, workspaces, дрифт

Хуки

Событие Скрипт Зачем
UserPromptSubmit track-time.sh Логирует работу/ожидание в JSONL для отчёта по времени
UserPromptSubmit warn-session-length.sh Счётчик запросов сессии (API-записи транскрипта): ≥1500 — предупреждение, ≥2500 — блок до /clear; префикс override: даёт +500 (максимум дважды за сессию)
PreToolUse (Bash) secret-scan-precommit.sh Перед git commit сканит staged-изменения на секреты; блокирует коммит, если найден токен внутри разрешённого пути
PreToolUse (Edit/Write/NotebookEdit) protected-paths-guard.sh Субагентам нельзя писать напрямую в конфиг Claude Code (agents/, skills/, hooks/, settings.json, CLAUDE.md) — только предлагать правку в отчёте, применяет главный поток
PreToolUse (Bash) protected-paths-guard-bash.sh То же для записи через шелл: редирект в защищённый путь, cp/mv/ln/install/rsync с ним последним аргументом (хвостовые редиректы не мешают) или через -t/--target-directory, curl -o, wget -O, tar -C, unzip -d (путь можно писать как ~, $HOME, "$HOME", ${HOME}), sed -i/tee/rm/chmod по нему, скрипт в heredoc или -c, открывающий файл на запись. Чтение (cat, ls, rg, 2>/dev/null, cp из защищённого пути) проходит: первая версия ловила любое упоминание пути рядом с > и давала сплошные ложные блоки
PostToolUse (Edit/Write) format-on-write.sh Best-effort автоформат только что записанного файла, если форматтер установлен; никогда не блокирует
PreCompact compact-state.sh Снимает снапшот состояния сессии (TODO дословно, последние правленые файлы, факты окружения из успешных команд, ветка, путь plan.md, последние промпты) в ~/.claude/compact-state/<session_id>.md с редактурой секретов. На stdout не печатает ничего намеренно: вывод PreCompact вклеивается в промпт суммаризатора
SessionStart scripts/active-router.sh Подтягивает индекс активных задач (.claude/pm/_active.md) в начало новой сессии. Файл до 8 КБ (ACTIVE_ROUTER_MAX_BYTES) идёт целиком, больше — только шапка и подсказка, как найти строку своей задачи
SessionStart (matcher compact) postcompact-inject.sh Возвращает снапшот в контекст после сжатия — единственный рабочий канал для этого (см. раздел «Память»)
Stop checkpoint-on-stop.sh, notify.sh, track-time.sh Атомарный git-checkpoint через stash create/stash store (без касания рабочего дерева и индекса), звуковое уведомление, лог времени
Stop uncommitted-reminder.sh Если рабочее дерево грязное — напоминает модели закоммитить логический шаг (только свои правки); то же грязное состояние повторно не напоминает (cksum статуса), при stop_hook_active молчит
SessionEnd track-time.sh Закрывает запись времени сессии

Три guard-хука PreToolUse подключены с "onFailure": "block" и "timeout": 10: хук, который упал или не уложился в таймаут, блокирует вызов, а не пропускает его молча.

Сняты и в settings.example.json не подключены:

Если вы не в bypassPermissions — эти два хука рекомендуется включить. Файлы лежат в hooks/, регистрация в settings.json:

"PreToolUse": [
  {
    "matcher": "Bash",
    "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/guard-destructive.sh" }]
  },
  {
    "matcher": "Read|Edit|Write",
    "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/guard-sensitive-files.sh" }]
  }
]

Что из защит осталось включённым и без них:

Скрипты и фоновые задания

13 скриптов в scripts/ (ещё два снятых — в scripts/disabled/):

Скрипт Что делает Когда запускается
active-router.sh Инжект _active.md с ограничением по размеру хук SessionStart
consult-opus.sh Headless second opinion для субагента (см. «Эскалация») вручную из агента
or-task.sh Внешний дешёвый воркер через OpenRouter вручную
ask Роутер claude / local (Ollama) / codex до запуска модели (см. «Локальная модель») вручную
golden-pr-replay.py Replay-эвал моделей на смёрженных PR вручную
time-report.py Отчёт «работа / ожидание» по дням и проектам: Claude Code (лог хуков track-time.sh) и Codex (его собственные rollout-логи), с дедупом resume-сессий и обрезкой турнов длиннее часа вручную или командой /time-report
git-sweep.sh Сводка по всем git-клонам на глубину 1–2 уровня: грязные файлы, непушнутое, ветка, возраст коммита, worktrees, stash вручную (PROJECTS_DIR, по умолчанию ~/Projects)
claude-mem-watchdog.sh Убивает зависшие headless-воркеры памяти сессий (>15 минут работы); сам демон и любой claude, чей родитель не воркер-сервис, не трогает cron, каждые 5 минут
semantic-stack-check.sh Разовая проверка Milvus (контейнер + реальный запрос) и возраста grepai-индекса вручную
grepai-resync.sh Инкрементальный resync общего grepai-индекса launchd, ежедневно в 05:30
disabled/semantic-stack-watch.sh, disabled/reindex-claude-context.py Сторож Milvus и индекса, батч-индексация claude-context без сессии Claude Code; сняты вместе с Milvus 2026-10-04 не запускаются
cred.sh Передаёт значения из *.env / *-openrc.sh в окружение дочернего процесса, не печатая их: cred.sh list — только имена ключей, cred.sh run KEY[,KEY2] -- CMD — экспорт и exec вручную (CRED_DIR, по умолчанию ~/.config/credentials)
telemetry-check.sh / telemetry-watch.sh Контур OTLP-телеметрии от конфигов Claude Code и Codex до приёма на сервере; без сети сторож молчит launchd, каждые 30 минут + при загрузке

TDD-governor (Probity)

Статус: снят со всех репозиториев 2026-09-02. За пилот (с конца августа) судья не поймал ни одной in-scope правки, а каждый вызов инструмента поднимал npx-процесс: около 8 000 спавнов дали примерно 55 минут чистой латентности. Ниже — как ставить, если TDD-гейт в конкретном репозитории действительно нужен.

Probity — принуждение TDD через PreToolUse-хук с LLM-судьёй, который читает транскрипт сессии и решает, не пропущена ли Red-фаза. Преемник tdd-guard от того же автора (tdd-guard в maintenance mode): вместо per-language тест-репортеров читает транскрипт и работает с несколькими агентами (Claude Code, Codex, Copilot CLI).

Подключение:

npm install -D @nizos/probity

probity.config.ts в корне проекта:

import { defineConfig, enforceTdd } from '@nizos/probity'

export default defineConfig({
  rules: [
    { files: ['src/**', '!**/tests/**'], rules: [enforceTdd()] },
  ],
})

Project-level .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit|NotebookEdit",
        "hooks": [{ "type": "command", "command": "npx @nizos/probity --agent claude-code" }]
      }
    ]
  }
}

Цена: судья гоняет пару моделей на каждую in-scope правку через подписку, а сам хук стоит спавна npx на каждый вызов инструмента под матчером. Ставить только туда, где тесты реально бегут локально и files в конфиге покрывают код, который правят агенты, — иначе остаётся одна латентность. Через неделю-две сверяться с телеметрией: сколько раз судья сработал по делу.

Semantic search стек

Статус: claude-context и Milvus сняты 2026-10-04. За 30 дней — 6 вызовов search_code, при этом Milvus держал около 1,9 ГБ RAM, а индексация каждого проекта грела ноутбук. Семантический поиск теперь только CLI grepai (ниже). Инструкция по установке claude-context сохранена — на случай, если векторный поиск через MCP действительно нужен.

Вариант с MCP — сервер claude-context поверх локального Milvus (векторная БД в Docker) и Ollama с моделью qwen3-embedding:0.6b. Полностью локально, без внешнего API — стоимость поиска нулевая. Индекс персистентный и обновляется инкрементально; при первой работе над проектом кодовая база индексируется один раз, дальше поиск идёт по готовому индексу.

Правило разделения инструментов: точный текст или известное имя символа — обычный grep/аналог с regex; поиск по смыслу («где у нас обрабатывается retry-логика для внешних вызовов») — semantic search.

Рабочий инструмент — CLI grepai (та же модель эмбеддингов через Ollama): поиск по смыслу grepai search и граф вызовов (grepai trace: кто вызывает функцию и что вызывает она) — он показывает зависимости, которые поиск по смыслу напрямую не видит; им пользуется агент deep-explore. Индекс один на всю папку проектов (~/Projects/.grepai, охват задаёт ~/Projects/.grepaiignore; новые исключения требуют полной пересборки). search/trace работают из любой подпапки, а grepai init/watch из подпапки запускать нельзя — появится второй индекс и второй скан.

Постоянный watcher не держится: grepai watch --background (0.37) убивает дочерний процесс, если индекс на ~3 ГБ не загрузился за 30 секунд, а живой watcher держит несколько гигабайт RAM. Вместо него scripts/grepai-resync.sh раз в сутки (launchd, 05:30) поднимает watcher на время инкрементального скана и гасит. Сторож свежести индекса (scripts/disabled/semantic-stack-watch.sh) снят вместе с Milvus: перед первым поиском проверяй возраст ~/Projects/.grepai/index.gob и, если он старше суток, запускай scripts/grepai-resync.sh вручную.

Установка

Эмбеддер локально, через Ollama:

ollama pull qwen3-embedding:0.6b
brew services start ollama            # или ollama serve

Milvus в Docker — standalone с встроенным etcd, конфиг и данные в ~/milvus-local:

mkdir -p ~/milvus-local/volumes/milvus
cat > ~/milvus-local/embedEtcd.yaml <<'EOF'
listen-client-urls: http://0.0.0.0:2379
advertise-client-urls: http://0.0.0.0:2379
quota-backend-bytes: 4294967296
heartbeat-interval: 100
election-timeout: 1000
snapshot-count: 10000
EOF
echo '# Extra config to override default milvus.yaml' > ~/milvus-local/user.yaml

docker run -d --name milvus-standalone \
  -e ETCD_USE_EMBED=true -e ETCD_DATA_DIR=/var/lib/milvus/etcd \
  -e ETCD_CONFIG_PATH=/milvus/configs/embedEtcd.yaml \
  -e COMMON_STORAGETYPE=local -e DEPLOY_MODE=STANDALONE \
  -v ~/milvus-local/embedEtcd.yaml:/milvus/configs/embedEtcd.yaml \
  -v ~/milvus-local/user.yaml:/milvus/configs/user.yaml \
  -v ~/milvus-local/volumes/milvus:/var/lib/milvus \
  -p 19530:19530 -p 2379:2379 -p 9091:9091 \
  --restart unless-stopped \
  --health-cmd="curl -f http://localhost:9091/healthz" \
  --health-interval=30s --health-start-period=90s --health-timeout=20s --health-retries=3 \
  milvusdb/milvus:v2.6.20 milvus run standalone

Только стабильные теги v2.6.x — beta-ветка 3.0 крашлупится (проверено в июле 2026).

MCP-сервер в ~/.claude.json, секция mcpServers:

"claude-context": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@zilliz/claude-context-mcp@0.1.15"],
  "env": {
    "EMBEDDING_PROVIDER": "Ollama",
    "EMBEDDING_MODEL": "qwen3-embedding:0.6b",
    "EMBEDDING_DIMENSION": "1024",
    "OLLAMA_HOST": "http://127.0.0.1:11434",
    "MILVUS_ADDRESS": "127.0.0.1:19530",
    "MILVUS_TOKEN": "local"
  }
}

Размерность вектора зашита в коллекцию Milvus: сменить модель эмбеддингов можно только вместе с полным реиндексом, поэтому удобный момент для смены — когда коллекций ноль. Выбор qwen3-embedding:0.6b (1024 измерения, 110 мс на чанк кода в 3000 символов на M1 Max) — компромисс между nomic-embed-text (768, 42 мс, вдвое короче вектор) и qwen3-embedding:4b (2560, 542 мс — 13 часов на полный реиндекс).

Первая индексация проекта — инструментом index_codebase с абсолютным путём к корню, проверка — get_indexing_status. Индекс персистентный, дальше обновляется инкрементально. Батчем, без сессии Claude Code (например, после пересоздания Milvus, когда MCP-сервер подключается только на старте сессии), то же самое делает scripts/disabled/reindex-claude-context.py: он говорит с MCP-сервером по stdio и умеет --status, --search, --clear, --force.

Грабля, которая съедает вечер: Milvus уходит в крэш-луп с panic: etcdserver: leader changed сразу после became leader, exit 134, десятки рестартов. Причина не в «битом томе», а в гонке на старте: Milvus шлёт линеаризуемые чтения во встроенный etcd раньше, чем единственный узел выбрал себя лидером, получает ErrLeaderChanged и паникует. Окно гонки расширяется при увеличенных heartbeat-interval/election-timeout и под нагрузкой хоста — поэтому в конфиге выше стоят дефолты 100/1000, а не «повышенные для надёжности» значения, которые ровно эту проблему и усугубляют. snapshot-count: 10000 укорачивает реплей WAL на старте. Если луп всё же вернулся: docker stop milvus-standalone, дождаться падения нагрузки, docker start. Снос тома — последнее средство, а не первое: после него индексы пустые и всё надо переиндексировать.

Ещё две вещи, которые сбивают с толку при диагностике. Статус Connected у MCP-сервера ничего не доказывает — процесс поднимается независимо от базы и при мёртвом Milvus рапортует то же самое, а запросы уходят в никуда; проверять curl -s http://127.0.0.1:9091/healthz. И сессия, стартовавшая при мёртвом Milvus, инструментов поиска не получит вообще — после починки нужна новая сессия.

Память (четыре слоя)

Каждый слой хранит свой тип информации, факт не дублируется между слоями — только ссылка.

Слой Что хранит Кто пишет
pm/<slug>/plan.md + _active.md Состояние задач: шаги, следующее действие, решения по конкретной задаче PM-конвейер по ходу работы
Auto-memory (MEMORY.md + файлы) Долгоживущие факты проекта: доступы, особенности, контракты, «как тут устроено» Модель, когда факт переживёт задачу
Плагин памяти сессий Хроника сессий для recall — пишется автоматически Сам плагин, руками не трогается
docs/ репозитория Командное знание: гайды, разбор инцидентов, инвентарь По правилам конкретного репозитория

Правило записи: решение принято или факт установлен (где лежит доступ, от чего ломается сервис, что выбрали и почему) — строка уходит на диск в тот же ход, не «в конце сессии». Компактизация контекста может случиться в любой момент и ничего сама на диск не пишет.

Страховка на случай сжатия — два хука. PreCompact (compact-state.sh) снимает снапшот состояния в ~/.claude/compact-state/<session_id>.md: TODO дословно, последние правленые файлы, факты окружения из успешных команд, ветка и worktree, путь plan.md, последние промпты; секреты вырезаются, права файла 0600. Обратно в контекст снапшот возвращает SessionStart с matcher: "compact" (postcompact-inject.sh). Именно SessionStart, а не PostCompact: последний физически не может ничего доставить модели — его вывод идёт только в UI, поэтому привычный приём «в PostCompact сделать cat нужного файла» модель никогда не видит. Снапшот считается независимо от суммаризатора и переживает то, что тот решил выкинуть; но и после сжатия plan.md всё равно перечитывается, а не заменяется summary.

Факт, который уже есть в одном слое, в остальных живёт как ссылка, а не копия. Протух — чинится в источнике.

Token economy

Метрики использования (запросы, токены, стоимость по сессиям и проектам) собираются через OTLP-телеметрию Claude Code в self-hosted Grafana — без передачи данных куда-либо ещё, инструмент личный.

Выводы из аудита, которые определили архитектуру сетапа:

Плагины

Плагин Назначение
claude-mem Хроника сессий (memory) — автоматически пишет наблюдения по ходу работы, отдельный слой от plan.md/_active.md, см. раздел «Память»
claude-hud Кастомный statusline — темп расхода 5-часового и недельного лимита, модель, время работы прямо в строке статуса
codex Второе мнение другой моделью — делегирование ресёрча, диагностики или отдельной подзадачи через отдельный CLI прямо из сессии Claude Code
security-guidance Встроенные подсказки по безопасности поверх стандартного diff-only ревью
swift-lsp LSP для Swift — навигация и диагностики по коду iOS/macOS-проектов
frontend-design Гайдлайны визуального дизайна — типографика, композиция, отход от шаблонных дефолтов при работе над UI
i-have-adhd Альтернативный формат структурирования ответов — короче, с явной структурой, меньше когнитивной нагрузки на чтение

Бэкап собственного сетапа

Отдельным паттерном, без прямой ссылки: приватный бэкап-репозиторий всего ~/.claude с redaction-скриптами, вычищающими секреты и корп-контекст перед коммитом, и rolling-release веткой для тяжёлых бинарных данных (индексы, кэши). Такой репозиторий имеет смысл держать отдельно от публичного — он хранит личную конфигурацию целиком, а не только переиспользуемые куски.

Как взять себе

  1. Скопировать нужные директории (skills/, agents/, hooks/, scripts/, commands/) в ~/.claude/ — глобально, или в <project>/.claude/ — под конкретный репозиторий.
  2. Подключить хуки в settings.json — структура и матчеры показаны в settings.example.json; путь к скриптам поправить под свою систему.
  3. Забрать общие принципы (Karpathy guidelines, CLEAR, правило «никаких следов AI», матрицу моделей) — шаблон в CLAUDE.global.example.md, дальше редактируется под свой стиль работы.
  4. Проверить права на выполнение у скриптов (chmod +x) и наличие зависимостей, которые они вызывают (git, опционально gitleaks для сканирования секретов).
  5. Заводить агентов и скиллы по мере необходимости, а не копировать весь флот сразу — специалист, который не используется, только шумит в контексте на старте сессии.
This site is open source. Improve this page.