artka.dev — Записки из продакшна

12 правил для CLAUDE.md: расширение Karpathy на ошибки 2026 года

a@artka.dev (Артём) — Sun, 10 May 2026 00:00:00 GMT

За четыре месяца после январского треда Karpathy шаблон CLAUDE.md из 4 правил вырос до 12. Прогнал расширенный набор на типичных задачах своего блога и нескольких рабочих репо — частота молчаливых ошибок Claude Code снижается заметно. Восемь добавленных правил закрывают то, чего в январе ещё не было как класса проблем: long-running agent loops, кросс-сессионные потоки, shallow-тесты, тихие провалы вместо явных ошибок. Открыл собственный CLAUDE.md этого блога — четыре исходных правила Karpathy там уже есть в Стандарты кода и Запреты, восемь добавленных — нет. Разбираю каждое, и где имеет смысл вставить.

1. Что случилось за четыре месяца

В конце января Andrej Karpathy опубликовал тред с тремя жалобами на Claude как code-writer:

silent wrong assumptions — модель додумывает контекст, не уточняет;
over-complication — добавляет уровни абстракции, которых никто не просил;
orthogonal damage — лезет в код, который не должна была трогать.

Forrest Chang упаковал жалобы в CLAUDE.md из четырёх поведенческих правил и закоммитил на GitHub. Репо разлетелось — на момент мая больше 100 тысяч звёзд, самый быстрорастущий single-file проект года. Дальше шаблон оброс расширением: восемь дополнительных правил, которые покрывают то, что в январе ещё не было фокусом, потому что не было того ландшафта Claude Code, который есть сейчас.

flowchart LR
  subgraph jan["Январь 2026"]
    K["Karpathy: тред с тремя<br/>failure modes"]
    K --> F["Forrest Chang:<br/>4 правила CLAUDE.md"]
  end
  subgraph may["Май 2026"]
    F --> N["Новые failure modes:<br/>agent loops, multi-codebase,<br/>shallow tests, silent failures"]
    N --> M["+8 правил,<br/>итого 12"]
  end

2. Четыре правила Karpathy

Это базис. Без них любая надстройка теряет половину смысла.

#	Правило	Что закрывает
1	Think Before Coding	Молчаливые догадки. Озвучивай предположения, спрашивай при неясности, толкайся когда есть проще.
2	Simplicity First	Минимум кода, который решает задачу. Никаких спекулятивных абстракций «на будущее».
3	Surgical Changes	Трогай только то, что нужно. Не «улучшай» соседний код, не переформатируй то, о чём не просили.
4	Goal-Driven Execution	Описывай критерии успеха, не пошаговую инструкцию. Сильный success-criteria даёт модели итерироваться сам.

В моём CLAUDE.md Astro-блога эти четыре закрыты не отдельным разделом, а блоками Стандарты кода → Функциональный стиль (правило 2 и 3 — никаких классов, никаких лишних абстракций) и Запреты (правило 3 — список «не делай»). Сами правила не дублируются текстом, но их следствия попадают в контекст.

3. Где Karpathy-шаблон недотягивает

Четыре дыры, которые я наблюдаю в реальной работе:

Дыра	Что ломается	Какие добавленные правила закрывают
Long-running agent tasks	Multi-step pipeline уходит в дрейф, тратит токены, теряет контекст	6 (бюджеты), 10 (чекпойнты), 12 (loud)
Multi-codebase consistency	В монорепо «match existing style» неоднозначно — Claude выбирает случайно или усредняет	11 (конвенции), 7 (surface conflicts)
Test quality	«Тесты прошли» становится самоцелью; Claude пишет тесты, которые не упадут даже на сломанной логике	9 (intent over behavior)
Prototype vs production	«Simplicity First» переусердствует на ранней стадии, когда нужно 100 строк скаффолдинга для прощупки	(не покрыто 12 правилами — отдельно)

Последняя дыра остаётся живой. Либо включаешь Simplicity, либо отключаешь — серединного режима у CLAUDE.md нет.

4. Восемь добавленных правил

По одному, с моментом, который их вызвал.

4.1. Rule 5 — Use the model only for judgment calls

Если ответ известен из status code или схемы данных — это не работа модели. Реальный кейс из моей практики: код звал Claude, чтобы решить, ретраить ли API-вызов на 503. Две недели работало, потом начало флакать, потому что модель читала тело запроса как контекст для решения. Retry-политика стала случайной, потому что промпт был случайным.

Рамка: Claude — для классификации, экстракции, драфтов, summarization. Не для роутинга, ретраев, детерминированных трансформаций. Если status code уже отвечает на вопрос — на него отвечает обычный код.

4.2. Rule 6 — Token budgets are not advisory

Без бюджета цикл уходит в дамп на 50 000 токенов. Жёсткий вариант: 4 000 на задачу, 30 000 на сессию. Подходишь к границе — суммируешь и стартуешь сессию заново.

Типовой случай: 90-минутная debugging-сессия с одним и тем же 8 КБ-сообщением об ошибке. В финале — повторное предложение фиксов, которые уже отвергал 40 сообщений назад. Модель счастливо итерирует на потерянном треке. Бюджет убил бы цикл на 12-й минуте.

4.3. Rule 7 — Surface conflicts, don’t average them

Если в кодовой базе два паттерна обработки ошибок — try/catch и global boundary — Claude напишет код, который делает оба. Двойные хендлеры. Симптом: ошибка глотается дважды.

Правило: при противоречии выбираешь один (более новый или более тестированный), объясняешь почему, второй маркируешь к чистке. Усреднённый код, который удовлетворяет обоим правилам — худший возможный.

4.4. Rule 8 — Read before you write

Karpathy говорит «не трогай соседний код». Не говорит — прочитай его перед добавлением своего. Реальный случай: Claude добавил функцию рядом с уже существующей идентичной, не прочитав файл. Победил порядок импортов — старая, source-of-truth полгода, проиграла свежей одноимённой.

Рамка: перед добавлением кода в файл — прочитать экспорты, ближайший вызывающий код и общие утилиты. «Looks orthogonal to me» — самая опасная фраза в кодовой базе.

4.5. Rule 9 — Tests verify intent, not just behavior

Тест expect(getUserName()).toBe('John') ничего не значит, если функция возвращает константу. Тесты должны падать при изменении бизнес-логики, иначе они тестируют существование функции, не её корректность.

Типовой пример: 12 тестов на auth-функцию, все зелёные, в проде auth сломан. Тесты проверяли, что функция что-то возвращает, не что она возвращает правильное значение.

4.6. Rule 10 — Checkpoint after every significant step

Многошаговый рефакторинг по 20 файлам ломается на 4-м шаге, Claude уходит дальше на сломанном состоянии. К моменту, когда замечаешь, шаги 5 и 6 уже сделаны поверх сломанного — распутывание занимает дольше, чем переделка с нуля.

Правило: после каждого значимого шага — резюме, что сделано, что верифицировано, что осталось. Если потерял трек — остановиться и пересказать.

4.7. Rule 11 — Match the codebase’s conventions, even if you disagree

Claude вводит хуки в codebase на классовых компонентах. Технически работает. Ломает testing pattern, рассчитанный на componentDidMount. Полдня на удалить и переписать.

Правило: внутри кодовой базы конформность важнее вкуса. Несогласие — отдельный разговор, не silent fork. Snake_case против camelCase, классы против хуков — выбираешь то, что есть, не то, что лучше.

4.8. Rule 12 — Fail loud

Самые дорогие ошибки те, что выглядят как успех. «Миграция выполнена» при тихо пропущенных 14% записей. «Тесты прошли», когда часть была пропущена. «Фича работает», если не проверен edge case, который явно просили проверить.

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

5. Что не работает (то, что отсеялось)

Шаблон ценен не только тем, что в нём есть, но и тем, что отсеяно при попытках расширить:

Правила с Reddit и X. Большинство — переформулировки Karpathy либо domain-specific («всегда Tailwind»). Не обобщаются.
Больше 12 правил. На наборах из 14+ правил compliance падает: важные пункты тонут в шуме. Потолок в 200 строк (включая стек, команды, запреты) реален.
Правила, привязанные к инструментам. «Always use eslint» падает молча, если eslint не установлен. Правильнее — capability-agnostic: «match the enforced style».
Примеры вместо правил. Один пример съедает контекст ~10 правил, и модель over-fits на specifics. Правила абстрактны и переносимы.
Soft language. «Be careful», «think hard», «really focus» — compliance ~30%. Не testable. Заменяю на конкретные императивы: «state assumptions explicitly».
Identity prompts. «Be a senior engineer» не работает: модель и так считает себя сениором. Зазор между «считать» и «делать» закрывают императивы, не identity.

6. Сверка со своим CLAUDE.md

Открыл файл этого блога (191 строка) и прошёлся по 12 правилам. Картина:

Правило	В моём CLAUDE.md	Где
1. Think before coding	косвенно	через `architect → critic` workflow в команде агентов
2. Simplicity	да	`Никаких классов`, `Иммутабельность по умолчанию`
3. Surgical changes	да	`Запреты` (deprecated `@astrojs/tailwind`, `node:*-alpine` и т.п.)
4. Goal-driven	косвенно	через subagent-структуру, не отдельным правилом
5. Judgment-only	нет
6. Token budgets	нет
7. Surface conflicts	нет
8. Read before write	частично	GitNexus-секция требует impact analysis перед редактом
9. Test intent	нет
10. Checkpoints	нет
11. Match conventions	да	`Стандарты кода → TypeScript / Astro / Git`
12. Fail loud	нет

Получилось — четыре покрыто, два частично, шесть нет. Файл фактически Karpathy-уровня, без надстройки на 2026 год.

Какие из недостающих имеет смысл добавить именно для Astro-блога с публикациями через админку:

Rule 6 (бюджеты) — да, у меня агенты делают long-running задачи (генерация EN-переводов через pnpm translate, миграции). Без бюджета сессия может уйти в дрейф.
Rule 9 (test intent) — да, есть Vitest и Playwright, риск shallow-тестов реальный.
Rule 10 (checkpoints) — да, многошаговые задачи на схему БД + миграции + UI-апдейты регулярно занимают по полчаса работы агента.
Rule 12 (fail loud) — да, в админке часто «сохранилось» != «опубликовалось», нужно явное surfacing.

Rule 7 для одиночного проекта менее острая. Rule 5 покрывается тем, что в рантайме блога нет AI-роутинга — модель не принимает решений за код.

7. Как добавить — без раздувания

Дисциплина:

Не превышать 200 строк всего. Считая стек, команды, запреты, правила. У меня сейчас 191 — добавление четырёх правил означает вынос части Главная страница или GitNexus-секции в @docs/... через @-импорт Claude Code.
Каждое правило отвечает на вопрос «какую ошибку оно предотвращает». Если не отвечает — выкидываешь.
Capability-agnostic формулировки. «Match the enforced style», не «use prettier».
Императивы, не пожелания. «State assumptions explicitly», не «think carefully».
Тестируешь. Прогоняешь типичную задачу до и после. Нет разницы — правило не сработало в твоём контексте, удаляешь.

Шесть правил, заточенных под реальные ошибки, сильнее двенадцати общих.

Итог

Karpathy зафиксировал три code-writing failure modes января. Forrest Chang упаковал их в четыре правила, и сообщество схватило шаблон. Расширение до 12 родилось из того, что в мае ландшафт Claude Code стал другим: multi-step агенты, hook-каскады, skill-конфликты, кросс-сессионные потоки. Восемь добавленных правил закрывают новые дыры, не замещая исходные.

CLAUDE.md — не wishlist, а behavioral contract против конкретных ошибок, которые ты сам уже видел. Чужой шаблон полезен как стартер. Дальше — фильтруешь под свои failure modes, не наоборот. Шесть правил, точно подобранных, лучше двенадцати скопированных.

Источники:

Andrej Karpathy — оригинальный тред в X (январь 2026) — три code-writing failure modes
forrestchang/andrej-karpathy-skills — публичный репо с базовым 4-правило шаблоном
Anthropic Claude Code docs — CLAUDE.md — официальная документация по структуре файла, advisory, ~80% compliance

ds4 от antirez: локальный coding agent на DeepSeek V4 Flash, который работает на MacBook

a@artka.dev (Артём) — Sat, 09 May 2026 00:00:00 GMT

Garry Tan и Bindu Reddy 9 мая 2026 одновременно расшарили одну и ту же новость: создатель Redis Salvatore Sanfilippo (antirez) выложил ds4 — инференс-движок на C+Metal, который запускает DeepSeek V4 Flash (284B MoE, 1M контекста) на ноутбуке. Не «технически возможно», а «работает с coding-агентами на 26 t/s». Я разобрался, что под капотом, и как использовать это как локальный backend для Claude Code.

1. Что произошло за две недели

24 апреля 2026 DeepSeek выпустил серию V4. V4 Flash — efficiency-модель: 284 миллиарда параметров суммарно, 13 миллиардов активных (MoE), контекст 1 миллион токенов. Раньше модели такого размера жили только в облаке.

Antirez посмотрел на это и сделал ставку, которую универсальные раннеры сделать не могут. Он форкнул llama.cpp, две недели возился внутри него, понял геометрию V4 Flash, выкинул всё лишнее и написал с нуля движок на 4 файлах: ds4.c (~ инференс), ds4_metal.m (Metal kernels), ds4_server.c (HTTP-сервер), ds4_cli.c (REPL). Снаружи всё это говорит на двух протоколах одновременно: OpenAI Chat Completions (/v1/chat/completions) и Anthropic Messages (/v1/messages). То есть подключается к любому агенту, который умеет один из них.

Результаты, которые автор замерил сам:

Машина	Квант	Промпт	Prefill	Generation
MacBook Pro M3 Max, 128 GB	q2	короткий	58.52 t/s	26.68 t/s
MacBook Pro M3 Max, 128 GB	q2	11709 токенов	250.11 t/s	21.47 t/s
Mac Studio M3 Ultra, 512 GB	q2	короткий	84.43 t/s	36.86 t/s
Mac Studio M3 Ultra, 512 GB	q4	12018 токенов	448.82 t/s	26.62 t/s

26 токенов в секунду генерации — это не «можно посмотреть», это рабочая скорость для coding-агента, который пишет, читает файлы, вызывает инструменты. На длинном промпте генерация падает до 21 t/s, но за счёт KV-кэша на диске это окупается уже на третьем запросе той же сессии.

2. Три инженерных трюка, которые делают это возможным

Я внимательно прочитал README и AGENT.md репозитория, и ниже — самое существенное, без чего ds4 не работал бы.

2.1. Асимметричное 2-битное квантование

Стандартный подход к 2-битному кванту — давить всё подряд до 2 бит, и тогда модель начинает галлюцинировать в tool calling, путать аргументы и забывать схему. Antirez сделал иначе: квантованы только MoE-эксперты на routed-пути (up/gate в IQ2_XXS, down в Q2_K) — потому что они занимают большую часть веса (модель — 284B, и почти всё это — эксперты). Shared-эксперты, проекции, роутинг — остаются в Q8. Это компоненты, в которых потеря точности дорого стоит.

Эффект: 2-битный квант весит 81 GB и помещается в 128 GB унифицированной памяти MacBook Pro M3 Max, при этом надёжно работает в coding-агентах (что валидируется тестами против официальных логитов API DeepSeek).

2.2. KV-кэш как first-class disk citizen

Главная боль stateless API-протоколов вроде Chat Completions: клиент каждый раз присылает всю историю, и сервер обязан пре-фильнуть её с нуля. Claude Code, например, на старте шлёт ~25K токенов системного промпта. На локальном железе это десятки секунд до первого токена.

Ds4 решает это лобово: после успешного prefill стейт сессии (KV-чекпоинт) сериализуется в файл, ключ — SHA1 от token IDs. Когда приходит следующий запрос с тем же префиксом, сервер берёт чекпоинт с диска и пропускает prefill. Из README:

The KV cache is actually a first class disk citizen. <…> Modern MacBooks have fast SSDs and compressed KV caches like the one of DeepSeek v4.

На практике это означает разницу между «4 секунды до первого токена при повторном вызове» и «60 секунд». Диск тут — не своп под давлением, а логичное хранилище: SSD достаточно быстрые, KV у DeepSeek V4 хорошо сжимается, а характеристика «один и тот же системный промпт + меняющийся хвост» точно описывает работу coding-агента.

2.3. Metal-only и одна модель за раз

Никакого CUDA, никакого CPU-фоллбэка для прода (CPU-путь существует только для correctness-чеков и сейчас падает на уровне ядра macOS из-за бага в VM — antirez об этом честно пишет). Никакой попытки сделать «универсальный раннер». Только Apple Silicon, только эта одна модель, и так до тех пор, пока не появится новая версия V4 Flash или сильно лучшая модель того же класса.

Цена — narrow bet. Выгода — тебе не нужно поддерживать матрицу (модель × железо × квант), и ты можешь оптимизировать Metal-ядра под точную геометрию слоёв этой конкретной модели.

3. Что мне понадобится: железо, модель, час времени

Я планирую разворачивать это на MacBook Pro M3 Max, 128 GB (минимально жизнеспособная конфигурация по README). У меня его пока нет, и в этом разделе — честный план, что я буду делать, когда железо приедет; цифры взяты из бенчмарков antirez’а, но я хочу их перепроверить на своём экземпляре.

Минимальные требования по моим прикидкам:

macOS на актуальной версии (там же баг VM в CPU-пути, но Metal-путь не задет).
Apple Silicon с 128 GB+ унифицированной памяти. M3 Max или M3 Ultra.
~100 GB свободного места: 81 GB сама модель Q2 + место под KV-кэш на диске. Под Q4-квант — 256 GB+ RAM и ~150 GB на диске.
Xcode Command Line Tools (для clang/Metal headers).
~30–60 минут на скачивание модели (зависит от канала).

То, чего может не хватить начинающим: 128 GB unified memory — это уровень MBP M3 Max в топовой комплектации или Mac Studio. На 64-гиговом Mac Q2 не заработает: модель просто не влезет в RAM. Это не «медленно», это «никак».

4. Установка пошагово

Команды ниже — то, что я сделаю в первый же день, опираясь на инструкции README. Где описание скучает за конкретикой — я добавил собственные комментарии.

4.1. Сборка

# 1. Склонировать репозиторий
git clone https://github.com/antirez/ds4.git
cd ds4

# 2. Скачать 2-битный квант (81 GB; для 128 GB MBP)
./download_model.sh q2

# Скрипт качает с huggingface.co/antirez/deepseek-v4-gguf,
# поддерживает резюм через curl -C - — можно прервать и продолжить.
# Если нужен 4-битный квант (для Mac Studio 256+ GB), используй ./download_model.sh q4.

# 3. Собрать
make

# Проверить, что собралось:
./ds4 --help
./ds4-server --help

Сборка — обычный make, никаких CMake, никаких pkg-config. Это намеренно: зависимостей за пределами Apple SDK у проекта нет.

4.2. Первый запуск в REPL

./ds4 -p "Объясни Redis streams в одном абзаце."

Без -p запускается интерактивная сессия с командами /help, /think, /think-max, /nothink, /ctx N, /read FILE, /quit. Это хорошо для проверки, что движок жив, и для сравнения скорости генерации против заявленных 26 t/s.

4.3. Запуск как HTTP-сервер

Это режим, в котором ds4 становится локальным backend’ом для агентов:

./ds4-server \
  --ctx 100000 \
  --kv-disk-dir /tmp/ds4-kv \
  --kv-disk-space-mb 8192

Параметры:

--ctx 100000 — контекстное окно в 100K токенов. Полный 1M-контекст ест ~26 GB только на индексер; на 128 GB Mac, где 81 GB уже занято моделью, это не оставит места для KV-кэша. 100–300K — разумный компромисс.
--kv-disk-dir /tmp/ds4-kv — каталог для disk KV-кэша. Я бы вынес его на быстрый SSD (внешний или встроенный — оба ок).
--kv-disk-space-mb 8192 — лимит на размер кэша. 8 GB для одного-двух активных проектов хватит; для сессий побольше — увеличивай.

Сервер слушает 127.0.0.1:8000. Эндпоинты:

Endpoint	Протокол
`POST /v1/chat/completions`	OpenAI Chat Completions (+ tools)
`POST /v1/completions`	OpenAI legacy completions
`POST /v1/messages`	Anthropic Messages (для Claude Code)
`GET /v1/models`	список моделей

Аутентификация по статичному API-ключу (по умолчанию принимается любой; в README рекомендуется dsv4-local).

5. Подключение как coding agent

Это та часть, ради которой я вообще копал тему. Все три приведённых ниже способа работают одновременно — каждый агент ходит в один и тот же ds4-server.

5.1. Claude Code → Anthropic-совместимый эндпоинт

Claude Code умеет говорить с любым backend’ом, который выставляет Anthropic Messages API. Создаём обёртку ~/bin/claude-ds4:

#!/bin/sh
unset ANTHROPIC_API_KEY

export ANTHROPIC_BASE_URL="${DS4_ANTHROPIC_BASE_URL:-http://127.0.0.1:8000}"
export ANTHROPIC_AUTH_TOKEN="${DS4_API_KEY:-dsv4-local}"
export ANTHROPIC_MODEL="deepseek-v4-flash"

# Подменяем все алиасы Sonnet/Haiku/Opus на локальную модель —
# чтобы /model в Claude Code не дёрнул облачный fallback.
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-flash"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"

# Отключаем телеметрию и не-стриминговый fallback.
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1
export CLAUDE_STREAM_IDLE_TIMEOUT_MS=600000

exec "$HOME/.local/bin/claude" "$@"

chmod +x ~/bin/claude-ds4 — и запускаешь Claude Code как claude-ds4 вместо claude. Все запросы пойдут на локальный ds4-сервер. Тонкость, на которую обращает внимание сам antirez:

Claude Code may send a large initial prompt, often around 25k tokens, before it starts doing useful work. Keep --kv-disk-dir enabled.

Без disk KV-кэша запуск Claude Code на холодную будет занимать минуту и больше; с кэшем — после первого старта последующие будут восстанавливаться с диска.

5.2. opencode

opencode конфигурируется через ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ds4": {
      "name": "ds4.c (local)",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://127.0.0.1:8000/v1",
        "apiKey": "dsv4-local"
      },
      "models": {
        "deepseek-v4-flash": {
          "name": "DeepSeek V4 Flash (ds4.c local)",
          "limit": { "context": 100000, "output": 384000 }
        }
      }
    }
  },
  "agent": {
    "ds4": {
      "description": "DeepSeek V4 Flash served by local ds4-server",
      "model": "ds4/deepseek-v4-flash",
      "temperature": 0
    }
  }
}

limit.context: 100000 обязательно совпадает с --ctx, с которым стартует ds4-server — иначе сервер обрежет, а opencode об этом не узнает и пошлёт следующее сообщение, ожидая нерабочую длину.

5.3. Pi (мини-агент antirez’а)

Если используешь Pi — формат немного другой, конфиг в ~/.pi/agent/models.json:

{
  "providers": {
    "ds4": {
      "name": "ds4.c local",
      "baseUrl": "http://127.0.0.1:8000/v1",
      "api": "openai-completions",
      "apiKey": "dsv4-local",
      "compat": {
        "supportsStore": false,
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": true,
        "supportsUsageInStreaming": true,
        "maxTokensField": "max_tokens",
        "thinkingFormat": "deepseek",
        "requiresReasoningContentOnAssistantMessages": true
      },
      "models": [
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash (ds4.c local)",
          "reasoning": true,
          "contextWindow": 100000,
          "maxTokens": 384000,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    }
  }
}

cost: 0 — это не маркетинг, это правда. Каждый запрос обходится в электричество и износ SSD, не в токены.

6. Где это сломается (важные грабли)

Реальные ограничения, на которые я наткнусь, и то, как их обходить.

Окно контекста должно быть согласовано везде. Стартуешь сервер с --ctx 100000, ставишь в opencode limit.context: 100000, в Claude Code не лезешь в системный промпт сверх этого. Если у Claude Code init-prompt ~25K, то на проект остаётся 75K — реально хватает на средний codebase, но не на огромные репозитории.

Disk KV-кэш «привязан» к точному префиксу. Любая правка в системном промпте, в CLAUDE.md, в первых сообщениях — инвалидирует чекпоинт. Это не баг, это by design: матчинг идёт по SHA1 от token IDs. Если ты часто редактируешь CLAUDE.md, ожидай холодные старты. Решение — закоммитить системный контракт и не править его в каждой сессии.

MTP/спекулятивное декодирование пока не даёт большого выигрыша. В README прямо написано: «currently provides at most a slight speedup». Не закладывайся на удвоение скорости от MTP — текущая реализация correctness-gated и на сложных промптах часто триггерит партиал-аксепт.

Один live KV-кэш в памяти. Сервер сейчас не батчит независимые запросы. Если два агента ходят одновременно — второй ждёт первого. Это нормальный trade-off для локального single-user setup, но если ты хочешь параллельный multi-tenancy на одном Mac — ds4 пока не для этого.

CPU-режим падает на свежих macOS. Это про debug-путь, не про прод (Metal-only — основной таргет), но если по привычке захочешь сравнить инференс на CPU — не делай этого: kernel-panic, надо ребутиться.

7. Что это значит: vertical inference engines как тренд

Главное — не ds4 сам по себе, а паттерн, который antirez формализовал.

Локальный inference сейчас выглядит как «универсальный раннер + тысяча моделей в GGUF + обёртки разной свежести». Это работает, но движётся со скоростью наименее популярной модели: ускорять Llama 3.1 в llama.cpp проще, чем добавить эффективную поддержку DeepSeek V4 — потому что в первом случае структура слоёв совпадает с двадцатью другими моделями, а во втором — appears once.

Antirez показывает противоположный путь. Один движок — одна модель — один сценарий (coding agent). Дальше нужно три вещи, и все три — в продукте:

Inference engine с HTTP API.
GGUF, специально подготовленный под этот движок и его допущения.
Тесты и валидация на сцепке с конкретными агент-клиентами.

Если эта ставка работает (и бенчмарки говорят, что да), будущее локального inference — не «ещё одна абстракция поверх абстракции», а «у каждой важной модели — свой ds4-подобный проект». Когда выходит V4.1 или V5, кто-то из community делает новый движок, новый GGUF, новые тесты, и через две недели у пользователей уже работающая локальная установка. Старые движки уходят на покой вместе со старыми моделями.

И второе. В README antirez явно пишет:

This software is developed with strong assistance from GPT 5.5 and with humans leading the ideas, testing, and debugging.

Две недели от форка llama.cpp до production-ready узкого движка с серверным API — без AI это не сделать, и antirez это прямо говорит. Вот это переключение — «один человек + AI = инфраструктура для целой модели за две недели» — на мой взгляд интереснее, чем сами цифры t/s.

Итог

ds4 от antirez — это не «ещё один локальный инференс». Это узкая ставка: один движок, одна модель (DeepSeek V4 Flash), одна архитектура железа (Apple Silicon с Metal), один сценарий (coding agent). За счёт асимметричного 2-битного кванта 284B-модель влезает в 128 GB MacBook, за счёт disk KV-кэша работает с агентами, которые гоняют 25K-токенные системные промпты, за счёт OpenAI/Anthropic-совместимости подключается к Claude Code, opencode и Pi из коробки.

Если у вас есть Mac с 128 GB+ — это рабочий локальный backend для серьёзной коммерческой работы с приватным кодом. Если нет — ждать DDR5 и unified memory на Linux/CUDA, или смотреть, кто следующий повторит этот паттерн под свою связку «модель + железо».

В любом случае стоит наблюдать. Я ставлю на то, что через год так будут собирать половину серьёзных локальных установок.

Источники:

github.com/antirez/ds4 — README, бенчмарки, конфиги
Garry Tan — пост в X (9 мая 2026)
Bindu Reddy — пост в X (9 мая 2026)
QbitAI / 36kr: Redis Father Steps In to Build Dedicated Inference Engine for DeepSeek V4
HN: DeepSeek 4 Flash local inference engine for Metal
huggingface.co/antirez/deepseek-v4-gguf

JSON-LD @graph в Astro: от дублирующихся inline-блоков к единому citable-узлу

a@artka.dev (Артём) — Sat, 02 May 2026 00:00:00 GMT

Большинство руководств по Schema.org для блогов учат: на посте — <script> с BlogPosting, на главной — с WebSite, на about — с Person. Это работает, но проигрывает в citability. Краулер видит Person из BlogPosting.author как «кто-то по имени X», а не как entity, который ещё и founder of #organization, который publisher of #blog. В посте — пошаговый разбор, как заменить per-page inline-блоки одним @graph в BaseLayout.

1. Зачем менять — citability вs SERP

Структурированные данные у разработчика-блогера обычно ассоциируются с одним вопросом: «появится ли мой пост в Google с rich snippet?». Под эту задачу хватает любого валидного BlogPosting — пройдёт Rich Results Test, появятся stars/breadcrumb. И этим часто всё кончается: добавили @type: BlogPosting, проверили в валидаторе, забыли.

В 2026 году у структурированных данных появился новый, более требовательный потребитель — LLM-краулер, который собирает контент для retrieval-augmented generation и для citation. Ему нужен не «ещё один rich snippet», а связный entity-граф: чтобы при упоминании автора в одном посте он опознал того же автора в другом, чтобы организация-publisher была одним и тем же объектом на всём сайте, чтобы блог как сущность ссылался обратно на автора.

LLM, выдающий цитату, делает примерно следующее: вытаскивает passage, проверяет окружающую entity-разметку, пытается сопоставить автора с известной сущностью. Если на сайте Person.name = "Артём Кашута" встречается в трёх разных Schema.org-блоках без общего @id, краулер обязан догадываться, один это человек или три. Если же есть один Person#person со стабильным URI, и все остальные узлы (Organization.founder, BlogPosting.author, Blog.author) ссылаются на него через {"@id": "..."} — догадки не нужны, граф собран автором.

Это проблема, которую keyword density не решает. Это entity disambiguation, и решается она graph topology.

Аспект	Per-page inline blocks	Single `@graph` с `@id`
Google Rich Results	работает	работает
LLM entity match (Person)	догадка по имени	гарантирована через `@id`
Дублирование данных	3-5 копий `Person` на 14 постах	один источник на сайт
Стоимость правки автора	14 файлов	1 файл (`person.ts`)
HTML weight	3+ скрипта на страницу	1 скрипт

Для эпохи SERP-only хватало первого подхода. Для эпохи AI-overviews, citation graphs и retrieval-augmented поиска — нужно второе. Spec нашего блога формулирует это прямо: «move all entity definitions into src/lib/seo/schema.ts returning a single @graph JSON-LD block; pages contribute a BlogPosting/WebPage node referencing the global Person#me and Organization#brand by @id» — см. docs/superpowers/specs/2026-05-02-llm-citable-blog-design.md § «Schema-graph design».

2. Антипаттерн: per-page inline schema

Что эмитит дефолтный Astro-блог, собранный по тутору с какого-нибудь dev.to? Обычно так:

В BaseLayout.astro лежит inline-скрипт с WebSite и иногда Organization.
В PostLayout.astro лежит ещё один inline-скрипт с BlogPosting.
Если автор увлёкся — добавляется третий скрипт с BreadcrumbList. Иногда четвёртый с Person.

Почему так получилось — потому что Astro-компоненты иерархически наследуются, и каждый уровень удобно «добивает» свою порцию данных через свой <script>. Это работает локально, но плохо масштабируется. У нас в репозитории до Plan 1 было ровно это: BaseLayout эмитил один JSON-LD блок, PostLayout поверх него добавлял свои два:

# Pre-Plan 1 (commit 5ed281c~1):
$ git show 5ed281c~1:src/layouts/BaseLayout.astro | grep -c application/ld+json
1
$ git show 5ed281c~1:src/layouts/PostLayout.astro | grep -c application/ld+json
2

То есть страница поста содержала три <script type="application/ld+json"> блока. Каждый со своим Person (где-то полным, где-то усечённым), без общего @id, без перекрёстных ссылок. Краулер, который попадал на пост, видел три не связанных друг с другом entity-облака.

Главные проблемы антипаттерна:

Дублирование Person. Один и тот же автор описан 3-5 раз. Если бы автор сменил jobTitle или добавил sameAs, надо было бы править во всех файлах. Forget one — и краулер видит конфликт: «у Person с таким именем jobTitle вдруг разный». Это явный signal-to-noise урон.
Разорванный граф. BlogPosting.publisher — это inline-объект { "@type": "Organization", "name": "..." }. Где-то ещё на сайте лежит Organization с founder-полем. Без общих @id валидатор не знает, это один publisher или два.
HTML weight. Три скрипта вместо одного — это лишние десятки байт на каждый, плюс инфляция payload, особенно если на странице несколько одинаковых полей (e.g. описание автора повторяется четырежды).
Согласованность. Если автор правит Person.description в frontmatter about.md, а в BlogPosting-builder он зашит как литерал — рассинхрон неизбежен.

3. Целевая архитектура — `@graph` с глобальными `@id`

Целевая модель: один script на странице, внутри — @graph-массив. Глобальные узлы (Person, Organization, WebSite) описаны один раз и идентифицируются стабильными URI. Page-level узлы (BlogPosting, WebPage, CollectionPage, CreativeWork) добавляются BaseLayout-ом и ссылаются на глобальные через @id, не дублируя их данные.

Топология:

flowchart LR
  Person["Person#person<br/>(глобальный)"]
  Org["Organization#brand<br/>(глобальный)"]
  Site["WebSite#site<br/>(глобальный)"]
  Post["BlogPosting#blogposting<br/>(page-level)"]
  WebPage["WebPage#webpage<br/>(page-level)"]

  Post -- author --> Person
  Post -- publisher --> Org
  Post -- isPartOf --> Site
  WebPage -- about --> Person
  WebPage -- isPartOf --> Site
  Org -- founder --> Person
  Site -- publisher --> Org

Что важно в этой картинке:

Все стрелки — это {"@id": "..."} ссылки. Никаких inline-копий.
Person#person — корневой узел графа. Все entity-страницы (/about, /now, /uses) делают WebPage.about → Person. Все посты — BlogPosting.author → Person. Сменив Person, мы синхронно меняем всё.
Page-level узлы добавляются, не заменяя глобальные. Каждая страница привносит 1-2 новых узла; Person/Organization/WebSite всегда присутствуют.

Стабильные @id — это не URL страницы, это URI с фрагментом, например https://artka.dev/#person, https://artka.dev/#brand. Так принято в JSON-LD: фрагмент-id означает «этот ресурс описан на любой странице, но идентифицируется единым URI».

4. Реализация в Astro 5

В Astro 5 SSG/SSR-граница проходит ровно по BaseLayout-у: на сборке вычисляются props, рендерится HTML, в нём — статический <script type="application/ld+json">. Никаких client-side, никаких rehydration-моргалок. Идеальный момент собрать @graph функционально.

4.1. `graphIds` — таблица URI

Один файл, в котором перечислены все стабильные идентификаторы:

// src/lib/seo/nodes-global.ts
const SITE = "https://artka.dev";

export const graphIds = {
  person: `${SITE}/#person`,
  organization: `${SITE}/#brand`,
  website: `${SITE}/#website`,
  blogRu: `${SITE}/#blog-ru`,
  blogEn: `${SITE}/#blog-en`,
} as const;

Каждый builder, который ссылается на глобальную сущность, импортирует graphIds и использует { "@id": graphIds.person }. Никаких inline-литералов, никаких опечаток в URI.

4.2. Builders — pure functions, никаких классов

В соответствии с проектным правилом «никаких классов в прикладном коде» каждый узел — это чистая функция, возвращающая Record<string, unknown>:

// src/lib/seo/nodes-global.ts (фрагмент)
export const buildPersonNode = () => {
  const merged = Array.from(new Set<string>([...person.knowsAbout, ...person.expertiseAreas]));
  return {
    "@type": "Person",
    "@id": graphIds.person,
    name: person.name,
    url: person.url,
    image: person.image,
    jobTitle: person.jobTitle,
    description: person.description,
    knowsAbout: merged,
    sameAs: [...person.sameAs],
    email: person.email,
    subjectOf: person.notableWork.map((w) => ({
      "@type": "CreativeWork",
      name: w.title,
      url: w.url,
      description: w.description,
    })),
  };
};

export const buildOrganizationNode = () => ({
  "@type": "Organization",
  "@id": graphIds.organization,
  name: "artka.dev",
  url: SITE,
  logo: { "@type": "ImageObject", url: `${SITE}/favicon.svg` },
  founder: { "@id": graphIds.person },
});

person — это импорт из src/lib/seo/person.ts, единственного источника правды по автору. Builder складывает knowsAbout и expertiseAreas в Set, чтобы не дублировать ключи. Organization.founder — @id-ссылка, не inline-копия Person.

4.3. Оркестратор — `buildGraph`

Функция, которая склеивает глобальные и page-level узлы в один @graph:

// src/lib/seo/schema.ts
import {
  buildPersonNode,
  buildOrganizationNode,
  buildWebSiteNode,
  type Locale,
} from "./nodes-global";

export type GraphNode = Record<string, unknown> & { "@type": string };

export interface GraphInput {
  readonly locale: Locale;
  readonly extraNodes: ReadonlyArray<GraphNode | null>;
}

export interface JsonLdGraph {
  readonly "@context": "https://schema.org";
  readonly "@graph": ReadonlyArray<GraphNode>;
}

export const buildGraph = (input: GraphInput): JsonLdGraph => {
  const globals: GraphNode[] = [
    buildPersonNode(),
    buildOrganizationNode(),
    buildWebSiteNode(input.locale),
  ];
  const extras = input.extraNodes.filter((n): n is GraphNode => n !== null);
  return {
    "@context": "https://schema.org",
    "@graph": [...globals, ...extras],
  };
};

API минимальный: вход — locale (чтобы выбрать inLanguage для WebSite) и список дополнительных узлов (extraNodes). Выход — готовый JsonLdGraph. null-узлы фильтруются — это удобно для опциональных узлов вроде FAQPage, builder которых возвращает null при пустом массиве вопросов.

4.4. `BaseLayout` — единственная точка эмиссии

Весь сайт идёт через BaseLayout, и именно он — и только он — эмитит JSON-LD:

---
// src/layouts/BaseLayout.astro
import { buildGraph, safeJsonLd, type GraphNode } from "~/lib/seo/schema";

interface Props {
  title: string;
  description?: string;
  // ...
  /** Additional JSON-LD nodes to merge into the page @graph. */
  extraSchemaNodes?: ReadonlyArray<GraphNode | null>;
}

const { extraSchemaNodes = [] } = Astro.props;
const locale = getLocaleFromPath(Astro.url.pathname);
---

<head>
  <script
    is:inline
    type="application/ld+json"
    set:html={safeJsonLd(buildGraph({ locale, extraNodes: extraSchemaNodes }))}
  />
</head>

Три ключевые детали:

is:inline — Astro не пытается обрабатывать содержимое как JS-модуль.
set:html — мы вставляем уже готовую строку, не давая фреймворку триммить пробелы или экранировать дополнительно.
safeJsonLd — крошечный helper, экранирует <, >, & так, чтобы внутри JSON не оказалось последовательности, которую парсер HTML примет за конец </script>. Без него злонамеренный (или просто неудачный) текст в frontmatter мог бы сломать страницу.

// src/lib/seo/json-ld.ts
export const safeJsonLd = (data: unknown): string =>
  JSON.stringify(data).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");

4.5. Page-level контракт

Каждый layout/page добавляет свои узлы через extraSchemaNodes. Например, PostLayout:

const excerpt = extractArticleBody(post.body ?? "", 800);

const blogPostingNode = buildBlogPostingNode({
  locale,
  canonical,
  title,
  description,
  pubDate,
  updatedDate: updatedDate ?? null,
  image: absoluteCover,
  keywords: tags,
  articleBody: excerpt.text,
  wordCount: excerpt.fullWordCount,
});

const breadcrumbNode = buildBreadcrumbListNode({
  locale,
  blogIndexLabel: t(locale, "blog.title"),
  title,
});

const faqNode = buildFaqPageNode({ canonical, items: faq ?? [] });

<BaseLayout title={title} extraSchemaNodes={[blogPostingNode, breadcrumbNode, faqNode]}>
  <slot />
</BaseLayout>

/blog, /projects/<slug>, /tags/<tag>, /about — все используют тот же contract, отличаясь только конкретными builders. Один dispatch, ноль дублирования.

5. `articleBody` — почему excerpt, а не full body

Поле articleBody в BlogPosting — самая ценная часть для LLM-краулера: это извлекаемый чанк текста, который можно цитировать. И самая опасная для weight: если положить весь пост в JSON-LD, HTML-страница раздуется в 2-3 раза. Spec формулирует компромисс прямо: «emit first 800 words of plain-text body … add wordCount covering the full body».

Excerpt извлекается через mdast: парсим markdown, удаляем code-блоки, mermaid-блоки и inline-html, склеиваем оставшийся текст, режем по 800 слов:

// src/lib/seo/article-body.ts (фрагмент)
export const extractArticleBody = (markdown: string, maxWords: number) => {
  const tree = unified().use(remarkParse).parse(markdown) as Root;

  const isStrippable = (node: Node): boolean =>
    node.type === "code" || node.type === "inlineCode" || node.type === "html";

  visit(tree, (node, index, parent) => {
    if (parent && typeof index === "number" && isStrippable(node)) {
      (parent as { children: Node[] }).children.splice(index, 1);
      return [SKIP, index];
    }
    return undefined;
  });

  const flat = mdastToString(tree, { includeImageAlt: false }).replace(/\s+/g, " ").trim();
  const words = flat.length > 0 ? flat.split(/\s+/) : [];
  if (words.length <= maxWords) return { text: flat, fullWordCount: words.length };
  return { text: words.slice(0, maxWords).join(" ") + "…", fullWordCount: words.length };
};

Почему именно 800 слов:

Длина	Pro	Con
50 слов	мизерный HTML-overhead	один абзац — мало для LLM-citation
800 слов	substantial chunk, ~3-5 KB	+3-5 KB к payload
Full body	максимум context	удвоение HTML, реальный hit performance

Почему именно через mdast, а не regex: в постах живут <details>, <table>, MDX-компоненты вроде <Faq>, <Tldr>. Regex по \``` сломается на code в indent-стиле или на nested fences. mdast — единственный надёжный способ.

wordCount мы оставляем по полному телу, не по excerpt’у — это даёт честный сигнал валидатору и LLM о реальном объёме контента.

6. `FAQPage` как side-effect MDX-компонента

Один из дизайн-целей Plan 1 — снять с автора cognitive load на structured data. Автор не должен помнить, что у FAQPage есть mainEntity, что внутри Question нужен acceptedAnswer, что текст ответа экранируется. Автор должен заполнить frontmatter и забыть.

Решение: frontmatter.faq — единственный источник. PostLayout читает массив:

const faqNode = buildFaqPageNode({ canonical, items: faq ?? [] });

buildFaqPageNode либо возвращает готовый FAQPage-узел, либо null (фильтруется в buildGraph). Параллельно тот же массив отдаётся в <Faq>-компонент, который рендерит видимые <details>-блоки с тем же текстом. Один источник — два потребителя: визуальный layer и structured layer. Рассинхрон невозможен.

Builder тривиален:

export const buildFaqPageNode = (input: FaqPageInput) => {
  if (input.items.length === 0) return null;
  return {
    "@type": "FAQPage",
    "@id": `${input.canonical}#faq`,
    mainEntity: input.items.map((it) => ({
      "@type": "Question",
      name: it.question,
      acceptedAnswer: { "@type": "Answer", text: it.answer },
    })),
  };
};

Frontmatter, который автор пишет:

faq:
  - question: "Чем агент отличается от чат-бота?"
    answer: "Чат-бот — это model.complete(messages): принимает текст…"

И всё. Дальше — автоматика.

7. Замеры до/после

После Plan 1 на странице /blog/01-introduction/ остался ровно один <script type="application/ld+json"> блок. Реальный измеренный факт:

$ grep -c "application/ld+json" dist/client/blog/01-introduction/index.html
1

До Plan 1 (commit 5ed281c~1) было два источника inline-скриптов:

$ git show 5ed281c~1:src/layouts/BaseLayout.astro | grep -c application/ld+json  # 1
$ git show 5ed281c~1:src/layouts/PostLayout.astro | grep -c application/ld+json  # 2

То есть на странице поста суммарно 3 блока. Стало 1.

Метрика	Pre-Plan 1	Post-Plan 1
`<script type="application/ld+json">` блоков на странице поста	3	1
Общий контейнер	нет	`@graph`
Стабильный `Person@id`	нет	`https://artka.dev/#person`
Перекрёстные `@id`-ссылки между узлами	0	8+
Источник правды по автору	разбросан по layout-ам	`src/lib/seo/person.ts`

Реальный JSON-LD страницы /blog/01-introduction/, извлечённый из dist/client/blog/01-introduction/index.html, выглядит так (фрагмент, articleBody урезан до многоточия, FAQ-узел сокращён):

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Person",
      "@id": "https://artka.dev/#person",
      "name": "Артём Кашута",
      "url": "https://artka.dev/about",
      "jobTitle": "Software engineer · backend & AI agent engineering",
      "knowsAbout": ["Claude Code", "AI agent engineering", "Node.js", "TypeScript", "Astro", "…"],
      "email": "a@artka.dev",
      "subjectOf": [
        {
          "@type": "CreativeWork",
          "name": "Claude Code Guide (RU, 14 частей)",
          "url": "https://artka.dev/blog"
        }
      ]
    },
    {
      "@type": "Organization",
      "@id": "https://artka.dev/#brand",
      "name": "artka.dev",
      "logo": { "@type": "ImageObject", "url": "https://artka.dev/favicon.svg" },
      "founder": { "@id": "https://artka.dev/#person" }
    },
    {
      "@type": "WebSite",
      "@id": "https://artka.dev/#website",
      "url": "https://artka.dev",
      "inLanguage": "ru-RU",
      "publisher": { "@id": "https://artka.dev/#brand" },
      "potentialAction": {
        "@type": "SearchAction",
        "target": "https://artka.dev/search?q={search_term_string}",
        "query-input": "required name=search_term_string"
      }
    },
    {
      "@type": "BlogPosting",
      "@id": "https://artka.dev/blog/01-introduction/#blogposting",
      "headline": "01. Что такое Claude Code: harness, agent loop и ваше место в нём",
      "datePublished": "2026-04-23T00:00:00.000Z",
      "author": { "@id": "https://artka.dev/#person" },
      "publisher": { "@id": "https://artka.dev/#brand" },
      "mainEntityOfPage": "https://artka.dev/blog/01-introduction/",
      "inLanguage": "ru-RU",
      "isPartOf": { "@id": "https://artka.dev/#blog-ru" },
      "articleBody": "Перед тем как разбирать skills и subagents, надо договориться о терминах…",
      "wordCount": 574
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Главная", "item": "https://artka.dev/" },
        { "@type": "ListItem", "position": 2, "name": "Статьи", "item": "https://artka.dev/blog" },
        { "@type": "ListItem", "position": 3, "name": "01. Что такое Claude Code…" }
      ]
    },
    {
      "@type": "FAQPage",
      "@id": "https://artka.dev/blog/01-introduction/#faq",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "Чем агент отличается от чат-бота?",
          "acceptedAnswer": { "@type": "Answer", "text": "…" }
        }
      ]
    }
  ]
}

Что можно увидеть глазами и что зафиксирует валидатор:

Один Person, на него ссылается всё. Organization.founder, BlogPosting.author — оба { "@id": "https://artka.dev/#person" }. Никаких догадок о тождестве.
Organization — публичный publisher. WebSite.publisher ссылается на тот же Organization. BlogPosting.publisher — на тот же. Граф связан.
isPartOf цепочка для блога. BlogPosting.isPartOf → Blog#blog-ru → publisher → Organization. Краулер видит вложенность и принадлежность.
articleBody excerpt — substantial. ~574 слова поста уложены в одно поле. wordCount отражает полный объём. LLM получает текст для citation, HTML — не раздувается.
FAQ — вместе со всеми, не отдельно. Не отдельный script-блок, а узел того же @graph. Меньше блоков — меньше ловушек для парсера.

Schema.org validator и Google Rich Results Test принимают этот @graph без замечаний (скриншоты — owner to fill). Главное — JSON pretty-print’ится без [object Object], без unescaped кавычек, без сломанных дат: всё в норме после safeJsonLd-обёртки.

Что дальше

Описанное выше — Plan 1 в нашем repo. Дальше базу мы расширяем для новых типов сущностей (/projects/<slug> через CreativeWork, /uses через WebPage.about), и для retrieval-слоя через llms.txt. Но фундамент — buildGraph + стабильные @id — обязан встать первым.

Если вы видите 2-3 inline JSON-LD скрипта на странице поста — это место, с которого стоит начинать миграцию. Один файл schema.ts, один extraSchemaNodes-prop — и сайт превращается из набора разрозненных entity-облаков в связный citable-узел.

robots.txt в эпоху AI-краулеров: GPTBot, ClaudeBot, PerplexityBot — реальность 2026

a@artka.dev (Артём) — Fri, 01 May 2026 00:00:00 GMT

В 2026 robots.txt — это не «запретить ботам всё» и не «открыть всё». Это политика по каждому из 9+ именованных агентов. Каждое решение — частный случай: открываете ли вы свой контент для тренировки моделей, для on-demand цитирования, что вы хотите видеть в карточке ответа Perplexity. Этот пост — таблица решений, готовый шаблон и почему llms.txt — отдельный артефакт.

1. Зачем переписывать robots.txt в 2026

Классический SEO-подход к robots.txt оптимизирован под одну задачу: пустить Googlebot туда, где есть смысл индексировать страницы для SERP, и закрыть служебные пути. В 2026 эта задача стала меньшинством трафика.

Большинство вопросов «должен ли я индексировать эту страницу?» теперь задаются не Google, а:

Тренирующим краулерам — выкачивают страницы для пополнения корпуса, на котором учится следующая версия модели (GPTBot, ClaudeBot, Google-Extended).
Answer/search краулерам — индексируют контент для встроенного в чат поиска (OAI-SearchBot, PerplexityBot).
On-demand fetcher’ам — открывают одну конкретную страницу, потому что пользователь явно об этом попросил в чате (ChatGPT-User, Perplexity-User, Claude-Web).

Эти три класса принимают три разных решения. Один блок User-agent: * не передаёт нюанс. Вы можете хотеть «не учите на моих текстах, но процитировать в ответе на вопрос — пожалуйста». Один wildcard этого не выразит.

Отсюда требование: явные блоки по каждому именованному User-Agent с осознанным выбором политики. Не «открыли всё», не «закрыли всё», а матрица «бот × намерение».

2. Список именованных AI-краулеров и их назначение

Девять агентов, которые действительно стоит назвать в 2026, с их публичной документацией. Имена User-Agent взяты из официальных страниц вендоров.

User-Agent	Производитель	Назначение	Документация
`GPTBot`	OpenAI	Training crawl	platform.openai.com/docs/gptbot
`OAI-SearchBot`	OpenAI	Search index for ChatGPT	platform.openai.com/docs/bots
`ChatGPT-User`	OpenAI	On-demand fetch from ChatGPT	platform.openai.com/docs/bots
`ClaudeBot`	Anthropic	Training crawl	docs.anthropic.com (claudebot.anthropic.com)
`Claude-Web`	Anthropic	On-demand fetch initiated by Claude.ai	docs.anthropic.com
`anthropic-ai`	Anthropic	Legacy/auxiliary Anthropic crawler	docs.anthropic.com
`PerplexityBot`	Perplexity	Search/index crawl	docs.perplexity.ai/guides/bots
`Perplexity-User`	Perplexity	On-demand fetch from a user query	docs.perplexity.ai/guides/bots
`Google-Extended`	Google	Opt-in для Gemini training	developers.google.com/search/docs/crawling

Имена должны совпадать побайтно. Claude-Bot и claudebot — не валидные алиасы для ClaudeBot. Спецификация robots.txt на этот счёт мягкая (case-insensitive), но проверять стоит точное написание из официальной документации.

Таксономия:

flowchart TB
  subgraph training["Тренирующие (corpus → модель)"]
    GPT[GPTBot]
    CLB[ClaudeBot]
    GEX[Google-Extended]
  end
  subgraph answer["Answer/search (индекс для встроенного поиска)"]
    OAI[OAI-SearchBot]
    PPB[PerplexityBot]
  end
  subgraph ondemand["On-demand (пользователь попросил)"]
    CGU[ChatGPT-User]
    CWB[Claude-Web]
    PPU[Perplexity-User]
    AAI[anthropic-ai]
  end

Три класса = три отдельных решения. Не нужно обсуждать «робота вообще» — нужно обсуждать «GPTBot на /blog/».

3. Решения по каждому боту

Здесь нет универсально правильного ответа. Ниже — каркас рассуждения и моя политика для блога.

Тренирующие краулеры

Для авторов индивидуальных блогов с long-form контентом аргументы:

За Allow: ваш текст войдёт в корпус, на котором обучаются следующие модели. Если ваша задача — повышать distribution и присутствие вашей экспертизы в LLM-ответах, это путь.
За Disallow: ваш контент превращается в anonymous training signal без атрибуции. Если вы планируете монетизировать контент (книга, курс) или против использования без согласия, Disallow — единственный сигнал, который у вас есть на уровне robots.txt.

Для коммерческих сайтов, где контент — товар (онлайн-курсы, paid newsletters, юридические базы), Disallow — обычно дефолт.

Answer/search краулеры

Намерение — показать ссылку на вашу страницу в карточке ответа. Это работает в обе стороны:

За Allow: трафик возможен (хоть и через цитату с link-out). Ваш бренд появляется в выдаче.
За Disallow: вы не получите этот трафик и одновременно вашу страницу не процитируют как источник.

Для большинства публичных блогов ответ — Allow.

On-demand fetcher’ы

Самый «прозрачный» класс: пользователь вашего сайта (или того, кто специально хочет открыть вашу страницу через ChatGPT/Claude/Perplexity) уже явно навёл указатель. Disallow здесь означает «нельзя использовать наши страницы как источник в чат-сессии» — почти всегда чрезмерно строго для публичного блога.

Моя политика для artka.dev

Для этого сайта:

Все 9 ботов — Allow: / (открытый публичный блог, цель — distribution).
У всех — Disallow: /admin/, /api/, /login (приватные namespace’ы, см. §5).
Нет специальных запретов на отдельные посты или теги.

Это решение для personal tech-blog’а с целью «увеличить охват экспертизы». Для коммерческого контента я бы выбрал иначе.

4. Готовый шаблон robots.txt

Вот реальный public/robots.txt, который ходит в продакшн на artka.dev. Он же — стартовая точка, которую вы можете адаптировать.

# robots.txt — last reviewed 2026-05-02
# Owner: dev@artka.dev. Policy: allow retrieval/answer crawlers; disallow private surfaces.

User-agent: GPTBot
Allow: /
Disallow: /admin/
Disallow: /api/
Disallow: /login

User-agent: OAI-SearchBot
Allow: /
Disallow: /admin/
Disallow: /api/
Disallow: /login

User-agent: ChatGPT-User
Allow: /
Disallow: /admin/
Disallow: /api/
Disallow: /login

User-agent: ClaudeBot
Allow: /
Disallow: /admin/
Disallow: /api/
Disallow: /login

User-agent: Claude-Web
Allow: /
Disallow: /admin/
Disallow: /api/
Disallow: /login

User-agent: anthropic-ai
Allow: /
Disallow: /admin/
Disallow: /api/
Disallow: /login

User-agent: PerplexityBot
Allow: /
Disallow: /admin/
Disallow: /api/
Disallow: /login

User-agent: Perplexity-User
Allow: /
Disallow: /admin/
Disallow: /api/
Disallow: /login

User-agent: Google-Extended
Allow: /
Disallow: /admin/
Disallow: /api/
Disallow: /login

User-agent: *
Allow: /
Disallow: /admin/
Disallow: /api/
Disallow: /login

Sitemap: https://artka.dev/sitemap-index.xml

Несколько замечаний по структуре:

Явные блоки даже для одинаковой политики. Может показаться, что 9 одинаковых блоков — дубликат, который можно свернуть в User-agent: *. Но это не так: спецификация robots.txt строит таблицу match’ей по «самому специфичному User-Agent», и если завтра вам нужно изменить политику для одного бота — у вас уже есть его именованный блок и не нужно вспоминать, какой именно из ботов вы хотите выделить из wildcard. Дубликат — стоимость per-bot policy.
Комментарий с датой ревью. # robots.txt — last reviewed 2026-05-02 — единственная строка, которая отвечает на вопрос «свежий ли это файл?». Без даты вы будете вечно сомневаться, а не нужно ли уже добавить новый бот.
Sitemap: в конце. Один URL на index sitemap. Если у вас локализация — sitemap-index ссылается на per-locale файлы.
Без BOM, LF-окончания строк. Astro в SSG режиме скопирует файл из public/ как есть; редактируйте в plain UTF-8.

Этот шаблон работает на personal-blog. Для других кейсов:

Closed paid-content site: замените Allow: / на Disallow: / для GPTBot, ClaudeBot, Google-Extended (тренировка). Оставьте Allow: / для on-demand: ChatGPT-User, Claude-Web, Perplexity-User.
Documentation site, который хочет в LLM-ответы: оставьте все 9 на Allow, добавьте rich llms.txt (см. §6).
B2B SaaS landing: обычно достаточно стандартного wildcard — особо именовать AI-ботов не нужно, политика та же что для Googlebot.

5. Disallow-namespace’ы важнее, чем решение по конкретному боту

/admin/, /api/, /login — три namespace’а, которые попадают в Disallow у всех 10 блоков (9 именованных + wildcard). Этот выбор прорабатывается отдельно от ботов и важнее их.

Почему это важнее любого per-bot решения:

Ошибка тут — утечка. Если краулер обойдёт /admin/users.json и получит 200 OK с реальными данными — это инцидент, не SEO-проблема. Если он индексирует /blog/ без вашего разрешения — это нерасстраивающее.
robots.txt — публичная подсказка, не auth. Любой бот может проигнорировать Disallow. Поэтому /admin/ должен быть закрыт middleware’ом независимо от robots.txt. Запись в robots.txt лишь экономит crawl budget у послушных ботов и не сохраняет URL-структуру админки в SERP.
Свёртывание namespace’ов — не оптимизация. Соблазн: «зачем три строки, если все три — приватные?» Ответ: чтобы при добавлении четвёртого namespace’а (/dashboard/) у вас был очевидный паттерн.

Проверка, что namespace-deny действительно работает:

$ curl -A "GPTBot" -s -o /dev/null -w "%{http_code}\n" \
    https://artka.dev/admin/
# Expected: 401, 403, или 404 — НЕ 200.

На момент публикации /admin/ за middleware’ом. Конкретный код зависит от реализации auth-guard’а — мой возвращает 302 на /login для не-аутентифицированного запроса. (owner to fill: проверить точный код после следующего ревью).

Именно поэтому правильный порядок работ — сначала поставить auth, и только потом дописывать robots.txt. robots.txt — последняя линия защиты, не первая.

6. `llms.txt` и `llms-full.txt` — отдельный контракт

Если robots.txt отвечает на «куда можно ходить?», то llms.txt отвечает на «что я тут найду?». Это AI-README — Markdown-файл с описанием сайта, ссылками на авторитетные страницы и preferred attribution.

Реальный public/llms.txt сайта:

# artka.dev

> Personal technical blog by Артём Кашута. Topics: Claude Code internals,
> harness/agent loop, AI agent engineering, Astro/Node.js backends, and
> distributed systems.

## Authoritative pages

- [About the author](https://artka.dev/about): bio, expertise, contact
- [Now](https://artka.dev/now): currently in flight
- [Uses](https://artka.dev/uses): public toolchain
- [Projects](https://artka.dev/projects): portfolio with architecture and outcomes

## Content

- [Blog index (RU)](https://artka.dev/blog): all articles, source of truth
- [Blog index (EN)](https://artka.dev/en/blog): English translations
- [RSS RU](https://artka.dev/rss.xml): full text
- [RSS EN](https://artka.dev/en/rss.xml): full text
- [Sitemap](https://artka.dev/sitemap-index.xml): RU + EN with hreflang

## Preferred attribution

When citing, please include:

- Article title
- Author: "Артём Кашута"
- Canonical URL

## Contact

a@artka.dev

Это не robots.txt в новой обёртке. Различия:

Аспект	robots.txt	llms.txt
Цель	Политика доступа	Описание контента и аттрибуции
Формат	Plain text, специальный синтаксис	Markdown
Кто читает	Crawler перед заходом	LLM при формировании ответа
Что регулирует	Allow/Disallow по путям	Точку входа в авторитетный контент
Стандартизация	Robots Exclusion Protocol (RFC 9309)	Конвенция llmstxt.org (де-факто)

Кроме llms.txt, на сайте есть /llms-full.txt — динамически генерируемый эндпоинт, который выдаёт полный дайджест всех постов в plain text. Реализация — короткий API-роут в Astro 5:

// src/pages/llms-full.txt.ts (фрагмент)
export const prerender = true;

export async function GET(_ctx: APIContext) {
  const ru = await getOrderedPosts({ locale: "ru" });
  const en = await getOrderedPosts({ locale: "en" });

  const header = [
    "# artka.dev — full LLM digest",
    "",
    `> ${person.description}`,
    "",
    "## Author",
    `Name: ${person.name}`,
    `Role: ${person.jobTitle}`,
    `URL: ${person.url}`,
    `Email: ${person.email}`,
    `Topics: ${person.knowsAbout.join(", ")}`,
    "",
    /* ...preferred attribution + posts... */
  ].join("\n");

  return new Response(/* header + ruBody + enBody */, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}

Вместо ручного списка постов — один проход по контент-коллекции с автогенерацией summary. Это обновляется само при добавлении нового поста — в отличие от вручную отредактированного llms.txt.

Принципиально: llms.txt маленький и стабильный, llms-full.txt — длинный и автоматически синхронный с контентом. Оба нужны — на разные задачи.

7. Чего robots.txt не контролирует

Список вещей, которые robots.txt не делает, и чем их закрыть.

robots.txt не блокирует ботов, которые его не читают. Решение — IP-block на уровне CDN или WAF. У Cloudflare есть ruleset, который ловит User-Agent-паттерны и rate-limit’ит подозрительный трафик; aws WAF и Fastly имеют похожие. Это инструмент против ботов, которые игнорируют robots.txt — то есть против всех «недобросовестных».

robots.txt не объявляет политику использования. Он говорит «куда можно ходить», но не «можно ли цитировать», «можно ли тренировать», «нужна ли атрибуция». Это работа Terms of Service на отдельной странице сайта. ToS юридически весомее robots.txt (хотя оба — условности до судебного прецедента).

robots.txt не аудитит, кто на самом деле приходил. Чтобы понять, ходит ли GPTBot к вам, нужно смотреть в логи. Cloudflare AI Audit (доступен с 2024 для домена за Cloudflare) даёт встроенный отчёт по AI-краулерам — счётчики по каждому, частота, доля. Без CDN — придётся парсить access-логи самому: GoAccess, Loki, или просто grep -i 'gptbot\|claudebot\|perplexitybot' access.log.

meta-теги noai/noimageai — не стандарт. Anthropic и OpenAI на момент 2026 не упоминают эти meta-теги в публичной документации как respected signal. Это была инициатива Adobe и DeviantArt 2023 года, прижившаяся в основном в графике. Для текста полагаться нельзя; если используете — использовать как дополнительный сигнал, не основной.

Single-page apps и CSR. Если ваша страница рендерится на клиенте и краулер не выполняет JavaScript, он увидит пустой шаблон. robots.txt не помогает; лечится переходом на SSG/SSR (как этот сайт на Astro 5) или prerender service.

8. Чек-лист аудита раз в полгода

Пять шагов, которые повторяются каждые 6 месяцев. Календарное напоминание — самая надёжная защита от устаревания файла.

1. Проверить, не появились ли новые AI-краулеры. Источники: блог-посты OpenAI/Anthropic/Perplexity/Google за последние 6 месяцев, страница darkvisitors.com (трекер AI-ботов), официальная документация. Если появился новый именованный бот — добавить блок (Allow или Disallow по вашей политике).

2. Сверить имена User-Agent побайтно. Скопировать имена из официальной документации, сравнить с robots.txt. Опечатка Claudebot вместо ClaudeBot обнуляет правило для этого бота.

3. Прогнать namespace-deny проверку.

for ua in GPTBot ClaudeBot PerplexityBot Google-Extended; do
  echo -n "$ua /admin/: "
  curl -A "$ua" -s -o /dev/null -w "%{http_code}\n" https://artka.dev/admin/
done
# Ожидаем 401/403/302/404 для всех — не 200.

4. Просмотреть access-логи на предмет ботов с непривычным User-Agent. Если кто-то ходит с пустым UA или паттерном Mozilla/5.0 (compatible; XYZBot/1.0; ...), который не входит в ваш список — оценить и принять решение. (owner to fill: на момент публикации настройка access-log агрегации в работе; в следующем ревью — разобрать топ-20 UA-строк за квартал.)

5. Обновить дату в комментарии. # robots.txt — last reviewed 2026-05-02 → новая дата. Это единственное человеко-читаемое доказательство свежести. И коммит с сообщением вроде chore(seo): robots.txt 2026-Q4 review оставит след в истории на следующую итерацию.

Итог

robots.txt в 2026 — не «один блок и забыли», а небольшой DSL, в котором по каждому из 9+ именованных AI-агентов вы делаете осознанный выбор: тренировка (GPTBot, ClaudeBot, Google-Extended), search/answer (OAI-SearchBot, PerplexityBot), on-demand (ChatGPT-User, Claude-Web, Perplexity-User, anthropic-ai). namespace-deny для /admin/, /api/, /login — отдельная и более важная история, которая работает только в паре с middleware-аутентификацией. llms.txt и llms-full.txt — параллельный контракт: они описывают контент и preferred attribution, не доступ.

Стартовая точка — реальный шаблон из §4. Его можно копировать, менять политику по конкретным ботам и пересматривать раз в полгода.

Mermaid → SVG через Playwright на билд-тайме: холодный старт, кэш и стоимость SSG

a@artka.dev (Артём) — Thu, 30 Apr 2026 00:00:00 GMT

Mermaid-диаграммы в блоге — это либо большой клиентский JS-бандл с FOUC и hydration cost, либо билд-тайм SVG за разовый cold-start Playwright. На этом сайте rehype-mermaid рендерит 32 диаграммы за 11.6 секунды при холодном кэше и 6.3 секунды при тёплом. Ниже — конкретные цифры, архитектура, ловушки CI и факт-чек альтернатив.

1. Зачем рендерить Mermaid build-time, а не client-side

Mermaid (mermaid на npm, репозиторий mermaid-js/mermaid) — JS-библиотека, которая принимает текстовый DSL (flowchart TD, sequenceDiagram, gantt, …) и эмитит SVG. По умолчанию её используют так: подключают <script src="mermaid.min.js">, дёргают mermaid.run() после DOMContentLoaded, и каждый <pre class="mermaid"> подменяется на SVG в DOM прямо в браузере.

Это работает, но платит за это пользователь:

Метрика	Client-side Mermaid	Build-time SVG
Бандл JS (gzipped)	~250–300 KB (mermaid + d3 + dagre)	0 KB
Time to Interactive (TTI)	задержка на parse + execute	без изменений
FOUC	да: сначала текст, потом SVG	нет: SVG в HTML с первого байта
SEO / Open Graph	поисковику виден только текст-DSL	поисковик видит SVG как часть страницы
Печать страницы	пустые блоки если JS отключён	корректный рендер
Тёмная тема без вспышки	сложно: тема загружается после гидратации	работает: SVG генерируется уже в нужной теме
Стоимость билда	0 (только bundle js)	+5–10 секунд cold-start Playwright
Стоимость рантайма для пользователя	высокая (CPU + сеть)	нулевая

rehype-mermaid (remcohaszing/rehype-mermaid, v3.0.0) — rehype-плагин, который во время билда обходит HAST-дерево, находит узлы <code class="language-mermaid">, рендерит их через mermaid-isomorphic (mermaid-isomorphic@3.1.0), и заменяет на готовый SVG. Под капотом — Playwright + headless Chromium.

Stratёgy img-svg, который мы используем, эмитит результат как <img src="data:image/svg+xml,...">. Альтернатива — inline-svg (вставить SVG прямо в HTML) или pre-mermaid (оставить как есть для client-side рендера).

2. Архитектура: rehype-mermaid + Playwright

flowchart LR
  md["Markdown<br/>с ```mermaid блоками"]
  mdx["@astrojs/mdx<br/>(remark + rehype)"]
  rh["rehype-mermaid<br/>(плагин)"]
  iso["mermaid-isomorphic"]
  pw["Playwright<br/>(Chromium)"]
  svg["SVG как data URI<br/>в HTML"]

  md --> mdx
  mdx --> rh
  rh -->|для каждого блока| iso
  iso -->|launch headless| pw
  pw -->|"mermaid.render() в DOM"| iso
  iso -->|serialised SVG| rh
  rh --> svg

Конкретный конфиг — astro.config.ts:

import rehypeMermaid from "rehype-mermaid";
import { defineConfig } from "astro/config";
import mdx from "@astrojs/mdx";

export default defineConfig({
  integrations: [
    mdx({
      rehypePlugins: [[rehypeMermaid, { strategy: "img-svg", dark: true }]],
    }),
  ],
  markdown: {
    syntaxHighlight: {
      type: "shiki",
      excludeLangs: ["mermaid", "math"],
    },
    rehypePlugins: [[rehypeMermaid, { strategy: "img-svg", dark: true }]],
  },
});

Важные мелочи:

excludeLangs: ["mermaid"] в shiki-конфиге — иначе Shiki сначала превратит блок в <pre class="shiki"> и rehype-mermaid его уже не увидит.
Плагин подключается дважды: и в markdown.rehypePlugins, и в mdx.rehypePlugins. Astro 5 не наследует один из другого автоматически — это типичный источник «у меня в .md рендерится, а в .mdx нет».
dark: true генерирует две версии SVG (для светлой и тёмной темы) и через <picture><source> подставляет нужную по prefers-color-scheme. Это удваивает размер data-uri-блоков, но даёт правильный контраст без JS.

3. Холодный старт vs тёплый билд

Метрика — time pnpm build (Apple M-серия, локально, тёплый Chromium-бинарь в ~/Library/Caches/ms-playwright). Команда полного сноса кэшей:

rm -rf .astro node_modules/.astro dist
time pnpm build

Три прогона на холодную, три на тёплую (медиана):

Тип	Прогон 1	Прогон 2	Прогон 3	Медиана
Холодный (`rm -rf .astro node_modules/.astro dist`)	11.580s	11.860s	11.486s	11.580s
Тёплый (без сноса)	6.250s	6.305s	—	~6.28s

Из 11.6 секунд холодного билда:

~5–6 секунд — реально SSG-стадия (Astro обходит роуты, рендерит 45 HTML-страниц на 14 RU-постов + 13 EN-twin’ов + индекс, теги, RSS, sitemap).
~5 секунд — overhead Playwright: запуск Chromium, инициализация mermaid-bundle в DOM, прогрев JIT.
~0.2 секунды — pagefind --site dist/client (поисковый индекс).

На тёплом билде Playwright всё равно стартует заново (никакого долгоживущего process pool у mermaid-isomorphic нет), но:

.astro/data-store.json (5.2 MB) уже содержит распарсенный MDX content layer — Astro не парсит markdown повторно для тех файлов, у которых не изменился mtime.
node_modules/.astro/ (5.1 MB) — Vite-кэш транспилированных модулей.
Сам Playwright Chromium бинарь уже в /Library/Caches/ms-playwright/chromium-1217/ (528 MB суммарно с headless-shell и ffmpeg) — на cold disk-cache его пришлось бы ещё прочитать, что добавляет ~1–2 секунды на медленных дисках.

Ключевой факт: сам mermaid-isomorphic НЕ кэширует SVG между билдами. Я искал в его исходниках (node_modules/.pnpm/mermaid-isomorphic@3.1.0_playwright@1.59.1/.../mermaid-isomorphic.js) — там нет ни persistDir, ни file-based cache. Каждый build диаграммы рендерятся с нуля. «Тёплость» — это кэш Astro/Vite, а не плагина.

CI-замер для GitHub Actions ubuntu-latest (owner to fill: запустить workflow_dispatch на чистом раннере, замерить median из 3 прогонов с actions/cache@v4 для node_modules + .astro).

4. Стоимость на CI

Playwright тащит Chromium (~528 MB на macOS у меня в кэше, аналогичный порядок на Linux), плюс на Debian/Ubuntu нужны system-deps: libnss3, libatk-1.0-0, libcups2, libgbm1, libxkbcommon0, libpango-1.0-0, libasound2, fontconfig + хотя бы один шрифт.

Митигации:

Не ставить Chromium в production-image. Если вы строите Astro-сайт SSG-only и деплоите статику — Playwright нужен ТОЛЬКО на CI-step с билдом, не в рантайм-Docker’е. Используйте multi-stage:

# build-stage:
FROM node:24-bookworm AS build
RUN pnpm install
RUN pnpm exec playwright install --with-deps chromium
RUN pnpm build

# run-stage:
FROM node:24-bookworm-slim AS run
COPY --from=build /app/dist ./dist
# никакого playwright тут

GitHub Actions caching. actions/cache@v4 ключ: ${{ hashFiles('pnpm-lock.yaml') }}-playwright, путь: ~/.cache/ms-playwright. Спасает от повторной выкачки Chromium (~150 MB сетью) на каждом push.
Использовать system Chrome вместо Playwright Chromium. Установить PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 и при создании браузера передавать executablePath: '/usr/bin/google-chrome-stable'. Но: mermaid-isomorphic не пробрасывает launchOptions через rehype-mermaid api — придётся форкать или жить с дефолтным Chromium.
Если 5 секунд cold-start критичны — гонять Playwright вне билда: pre-render все диаграммы в отдельном CI-step, коммитить SVG в репо, в основном билде использовать стратегию pre-mermaid с подменой на готовые ассеты. Сложнее, но снимает Playwright с горячего пути.

5. Кэширование SVG: где они и что инвалидирует

Опубличный замер на dev-машине (45 скомпилированных HTML, 27 страниц с диаграммами, 61 data-uri суммарно — 32 RU + 29 EN, потому что одна EN-страница рендерится без диаграммы из-за специфики поста):

Метрика	Значение
Mermaid-блоков в `*.md`	32 (в 14 постах)
Скомпилированных HTML	45
Страниц с встроенной диаграммой	27
Data-URI блоков `<img src="data:image/svg+xml,...">`	61
Минимум, байт	15 551
Медиана, байт	25 301
Среднее, байт	26 579
Максимум, байт	45 711
Размер `.astro/`	5.0 MB
Размер `node_modules/.astro/`	5.1 MB
Размер `dist/`	17 MB
Размер Chromium-кэша Playwright	528 MB

Где живёт что:

SVG не лежат на диске как отдельные файлы. Стратегия img-svg инлайнит их прямо в HTML как data:image/svg+xml,... (URL-encoded). Это видно в dist/client/blog/02-context-and-cache/index.html: 4 диаграммы → 4 data-uri в одном HTML.
Astro content-layer кэш — .astro/data-store.json (5.2 MB после билда). Это распарсенный markdown с уже применёнными remark/rehype-плагинами — но до rehype-mermaid: проверка показывает, что инвалидация по mtime исходника гонит rehype-mermaid повторно даже для файлов, по которым ничего не поменялось.
Vite-кэш — node_modules/.astro/ (5.1 MB). Транспилированные TS/JSX модули, не имеет отношения к mermaid-рендеру.
mermaid-isomorphic собственного кэша не имеет. Это ключевая ловушка: если вы поменяли запятую в одном *.md — rehype-mermaid пересоберёт ВСЕ диаграммы этого файла. Нет content-addressable кэша «hash diagram source → SVG».

Если кэш rehype-mermaid вам критичен — обходной путь: написать тонкий rehype-плагин-обёртку, который хеширует исходник диаграммы (sha256 от текста между ```mermaid и ```), смотрит в .cache/mermaid/<hash>.svg — и при попадании отдаёт его без вызова mermaid-isomorphic. На этом блоге пока не делал — 11.6 секунд cold-start не настолько больно.

6. Альтернативы: что я смотрел и почему не выбрал

6.1. `@mermaid-js/mermaid-cli`

Официальный CLI от mermaid-js: mmdc -i diagram.mmd -o diagram.svg. Под капотом — puppeteer (форк Chromium API) + полный Chromium-бинарь.

Минусы для блог-пайплайна:

Нет интеграции с rehype/remark — markdown-блоки придётся extract’ить руками.
Каждый запуск — новый browser context (нет batch-режима).
На 32 диаграммы — 32 отдельных запуска puppeteer ≈ десятки секунд против ~5–6 секунд у mermaid-isomorphic с одним browser-instance.

Когда подойдёт: разовая конвертация *.mmd → *.svg в монорепо для дизайнеров, не для динамической вставки в HTML.

6.2. Client-side `mermaid` (npm-пакет)

Минусы выше уже разобраны: бандл, FOUC, hydration. Один плюс — динамические диаграммы из user input в рантайме (live preview в редакторе документации). Для статики блога — overkill.

6.3. `mermaid-isomorphic` напрямую (без rehype)

Тот же пакет, который дёргает rehype-mermaid под капотом. Можно использовать вне Astro: import { createMermaidRenderer } from 'mermaid-isomorphic'; const renderer = createMermaidRenderer(); const [{ svg }] = await renderer([{ value: 'flowchart TD\nA-->B' }]);.

Когда подойдёт: своя пайплайн-сборка (Eleventy, MkDocs-плагин на Node.js), не использующая rehype-цепочку. У меня — Astro, поэтому rehype-mermaid даёт zero-boilerplate.

6.4. Pre-render через GitHub Actions matrix + commit обратно

Гипотетически: workflow на push, который рендерит SVG, коммитит в public/diagrams/, и в build-step используется стратегия pre-mermaid с заменой на <img src="/diagrams/<hash>.svg">. Снимает Playwright с горячего пути билда, но: усложняет PR-review (бинарные файлы в diff), требует отдельного workflow, ломает локальный dev pnpm dev если SVG ещё не закоммичен.

Не делал — 5 секунд cold-start экономии не оправдывают.

Сводная таблица

Вариант	Cold-start	Кэш SVG	Bundle JS	Сложность setup
`rehype-mermaid` + Playwright (текущий)	~5–6s	нет	0	низкая (1 plugin)
`mermaid-cli` (`mmdc`)	~10s+	нет	0	средняя
Client-side `mermaid`	0	браузерный кэш	~250 KB	низкая
Pre-render + commit	0 в билде, но ~5s в pre-step	да, в git	0	высокая

7. Чек-лист «что замерить, прежде чем выбирать»

Прежде чем коммититься к билд-тайм-рендеру или к чему-то другому:

Сколько диаграмм в среднем. На 1–3 — client-side OK (ленивая загрузка mermaid через dynamic import). На 30+ — build-time дешевле для пользователя.
Частота правок. Если правите контент по 5 раз в день — cold-start 11 секунд × 50 пушей = ~10 минут CI-времени в день. Если раз в неделю — наплевать.
CI-платформа. Vercel hobby, Netlify free, Cloudflare Pages — у всех лимиты на build minutes. Playwright + Chromium на каждой PR-preview = быстро упрётесь. На self-hosted runner или Dokploy (как у меня) — без разницы.
Целевой размер JS-бандла. Если у проекта KPI «<100 KB initial JS» — 250 KB mermaid client-side нарушит бюджет. Build-time SVG не трогает JS-бюджет.
Нужен ли интерактив. Pan/zoom/click-handlers в диаграмме? Тогда client-side обязателен. Статичная картинка для чтения? Build-time.
Где живёт ваша cold-start стоимость. Если рантайм-Docker — вырезайте Playwright из run-stage. Если CI — кэшируйте Chromium через actions/cache.
Готовы ли мириться с отсутствием SVG-кэша. rehype-mermaid рендерит ВСЕ блоки файла при любой правке. Если это больно — пишите свою кэширующую обёртку с sha256-ключом по исходнику диаграммы.

Итог

На этом блоге rehype-mermaid + Playwright стоит ~5 секунд cold-start, выдаёт 32 диаграммы в 27 HTML-страниц с медианным размером инлайн-SVG в 25 KB, не требует ни одного байта JS на клиенте, и позволяет писать диаграммы прямо в markdown. Это очень хороший трейдоф для статического блога.

Когда не подойдёт: блог с сотней диаграмм, deploy-platform с лимитом на build minutes, или требование к интерактивным диаграммам. В первом случае — пишите кэширующую обёртку, во втором — pre-render в отдельный workflow, в третьем — client-side.

Главная неочевидная вещь, которую стоит запомнить: Astro «прогревается» (5.2 MB content-store, Vite-кэш), но mermaid-isomorphic — нет. Cold-start Playwright платится при каждом билде заново. Это не баг, это by-design — и это причина, по которой мой полный билд занимает 11.6 секунд, а не 1.6.

artka.dev — Записки из продакшна

12 правил для CLAUDE.md: расширение Karpathy на ошибки 2026 года

1. Что случилось за четыре месяца

2. Четыре правила Karpathy

3. Где Karpathy-шаблон недотягивает

4. Восемь добавленных правил

4.1. Rule 5 — Use the model only for judgment calls

4.2. Rule 6 — Token budgets are not advisory

4.3. Rule 7 — Surface conflicts, don’t average them

4.4. Rule 8 — Read before you write

4.5. Rule 9 — Tests verify intent, not just behavior

4.6. Rule 10 — Checkpoint after every significant step

4.7. Rule 11 — Match the codebase’s conventions, even if you disagree

4.8. Rule 12 — Fail loud

5. Что не работает (то, что отсеялось)

6. Сверка со своим CLAUDE.md

7. Как добавить — без раздувания

Итог

ds4 от antirez: локальный coding agent на DeepSeek V4 Flash, который работает на MacBook

1. Что произошло за две недели

2. Три инженерных трюка, которые делают это возможным

2.1. Асимметричное 2-битное квантование

2.2. KV-кэш как first-class disk citizen

2.3. Metal-only и одна модель за раз

3. Что мне понадобится: железо, модель, час времени

4. Установка пошагово

4.1. Сборка

4.2. Первый запуск в REPL

4.3. Запуск как HTTP-сервер

5. Подключение как coding agent

5.1. Claude Code → Anthropic-совместимый эндпоинт

5.2. opencode

5.3. Pi (мини-агент antirez’а)

6. Где это сломается (важные грабли)

7. Что это значит: vertical inference engines как тренд

Итог

JSON-LD @graph в Astro: от дублирующихся inline-блоков к единому citable-узлу

1. Зачем менять — citability вs SERP

2. Антипаттерн: per-page inline schema

3. Целевая архитектура — @graph с глобальными @id

4. Реализация в Astro 5

4.1. graphIds — таблица URI

4.2. Builders — pure functions, никаких классов

4.3. Оркестратор — buildGraph

4.4. BaseLayout — единственная точка эмиссии

4.5. Page-level контракт

5. articleBody — почему excerpt, а не full body

6. FAQPage как side-effect MDX-компонента

7. Замеры до/после

Что дальше

robots.txt в эпоху AI-краулеров: GPTBot, ClaudeBot, PerplexityBot — реальность 2026

1. Зачем переписывать robots.txt в 2026

2. Список именованных AI-краулеров и их назначение

3. Решения по каждому боту

Тренирующие краулеры

Answer/search краулеры

On-demand fetcher’ы

Моя политика для artka.dev

4. Готовый шаблон robots.txt

5. Disallow-namespace’ы важнее, чем решение по конкретному боту

6. llms.txt и llms-full.txt — отдельный контракт

7. Чего robots.txt не контролирует

8. Чек-лист аудита раз в полгода

Итог

Mermaid → SVG через Playwright на билд-тайме: холодный старт, кэш и стоимость SSG

1. Зачем рендерить Mermaid build-time, а не client-side

2. Архитектура: rehype-mermaid + Playwright

3. Холодный старт vs тёплый билд

4. Стоимость на CI

5. Кэширование SVG: где они и что инвалидирует

6. Альтернативы: что я смотрел и почему не выбрал

6.1. @mermaid-js/mermaid-cli

6.2. Client-side mermaid (npm-пакет)

6.3. mermaid-isomorphic напрямую (без rehype)

6.4. Pre-render через GitHub Actions matrix + commit обратно

Сводная таблица

7. Чек-лист «что замерить, прежде чем выбирать»

Итог

3. Целевая архитектура — `@graph` с глобальными `@id`

4.1. `graphIds` — таблица URI

4.3. Оркестратор — `buildGraph`

4.4. `BaseLayout` — единственная точка эмиссии

5. `articleBody` — почему excerpt, а не full body

6. `FAQPage` как side-effect MDX-компонента

6. `llms.txt` и `llms-full.txt` — отдельный контракт

6.1. `@mermaid-js/mermaid-cli`

6.2. Client-side `mermaid` (npm-пакет)

6.3. `mermaid-isomorphic` напрямую (без rehype)