Но после месяца реального использования я наткнулся на несколько существенных проблем, которых тот пост не покрывал. Главная из них — скрытая особенность Claude Code, на которую я наступил случайно, когда добавил Gmail MCP и он "исчез" из моего профиля через пять минут. Сегодня я переделал всё на новую архитектуру — XDG-совместимую, с symlink'ом и интерактивным выбором профиля через gum. Это v2 — эволюция из реального опыта, а не теоретическое улучшение.

Что начало напрягать

Четыре вещи. Первые три — про аккуратность, видимость и масштаб. Четвёртая — настоящая архитектурная каверза, которую я не увидел сразу. Разберу по очереди, потому что именно четвёртая в конце и заставила переделать всё.

1. Две отдельные папки в $HOME — это бардак

~/.claude и ~/.claude-promova — два dotfolder'а рядом в корне $HOME. XDG Base Directory Specification говорит, что конфиги должны жить в ~/.config/. Разбросанные dotfile-папки прямо в home — это антипаттерн, который со временем превращает $HOME в свалку. Косметически, но раздражало каждый раз, когда я видел ls -la ~.

2. Нет визуального подтверждения активного профиля

Запускаю claude и не знаю, какой профиль активен — пока не выполню claude config list уже внутри сессии. Если забыл, какой терминал где запустил — нужно проверять. Мелочь, но при параллельной работе personal + work в двух вкладках она набирает массу.

3. Алиасы не масштабируются

Два профиля — claude и claude-promova — это окей. Добавляешь третий (фриланс-клиент) — нужен третий алиас. Четвёртый — четвёртый. Через полгода я бы не помнил, какие именно алиасы у меня созданы.

4. Скрытая ловушка с ~/.claude.json

А вот это настоящая причина переделки. У Claude Code есть два разных места конфигурации, и документация об этом не кричит: ~/.claude/ — директория, где лежат projects/, sessions/, hooks/, skills/. И отдельно — ~/.claude.json, файл прямо в корне $HOME, где живут oauthAccount, mcpServers, история projects, skillUsage и ещё около 40 других полей настоящего live state.

Команда claude mcp add --scope user пишет именно в ~/.claude.json в home root, а не в ~/.claude/.claude.json или в профильную директорию. Я этого не знал. Пока в один прекрасный день не наступил.

Discovery: почему Gmail MCP "исчез"

Сегодня утром я ставил Gmail MCP в Claude Code. Сетап обычный: Google Cloud project, OAuth credentials, claude mcp add gmail --scope user -- npx -y @gongrzhe/server-gmail-autoauth-mcp. Всё ок. Перезапустил сессию — работает, читаю почту, отвечаю на письма. Через час начали рефакторить алиасы в функцию с gum-выбором профиля, а потом перенесли всё на XDG. Я сделал mv ~/.claude → ~/.config/claude-profiles/personal, перезапустил CC, выбрал personal в меню. И в новой сессии открыл /mcp:

figma            (failed)
playwright-test
claude.ai Notion

Не было gmail. Не было vaultforge. Только три сервера, из которых один даже failed. А я только что добавлял Gmail. Сессия в другом терминале (work-профиль) при этом показывала Gmail и Vaultforge без проблем.

Я начал копать и нашёл, что у меня на машине три разных файла с именем .claude.json:

Вот оно. Это и есть та самая архитектурная каверза:

1. claude mcp add --scope user всегда пишет в ~/.claude.json в home root, независимо от CLAUDE_CONFIG_DIR
2. Claude Code при наличии CLAUDE_CONFIG_DIR читает $CLAUDE_CONFIG_DIR/.claude.json — то есть файл внутри профиля
3. Записи "user-scope MCPs" и "профильные MCPs" живут в разных файлах с одинаковым именем — и их легко перепутать

В моём случае ~/.claude.json (home root, 113 KB) был живым, актуальным state — с gmail, vaultforge, oauth-сессией, всем. А ~/.config/claude-profiles/personal/.claude.json (29 KB) оказался старым snapshot'ом, который почему-то лежал в old ~/.claude/ ещё раньше — может, старая версия CC писала туда, может, плагин. jq -r 'keys[]' на обоих файлах показал, что в home-root версии есть 41 уникальный ключ, которого нет в snapshot'е.

И эти 41 ключ — это не мусор. Это настоящее состояние Claude Code:

• skillUsage — статистика использования skills
• githubRepoPaths — кэш репозиториев для project-навигации
• cachedGrowthBookFeatures + cachedStatsigGates — feature flags (без них CC ходит за свежими каждый раз при старте)
• hasShownOpus45Notice, hasShownOpus46Notice, hasShownS1MWelcomeV2 — UI флаги (без них модальные окна снова появятся при следующем запуске)
• lastPlanModeUse, feedbackSurveyState, installMethod — onboarding и UX state

Если просто mv ~/.claude ~/.config/claude-profiles/personal без merge — потеряешь всё это. Заново увидишь welcome-модалки, заново выполнит поиск githubRepoPaths, заново получишь все survey-просьбы. Как я чуть не сделал.

Новая архитектура

Всё живёт под одним родительским каталогом в ~/.config/, как того хочет XDG. Каждый профиль самодостаточен — имеет свой полный state, включая собственный .claude.json. ~/.claude остаётся как symlink на personal-профиль для обратной совместимости.

~/.config/claude-profiles/
├── personal/
│   ├── .claude.json          ← full live state + MCP list (113 KB)
│   ├── projects/, sessions/, hooks/, skills/, ...
│   └── CLAUDE.md
└── promova/
    ├── .claude.json          ← work state + work MCPs (41 KB)
    └── projects/, sessions/, agents/, skills/, ...

~/.claude  →  symlink to ~/.config/claude-profiles/personal/

Никакого .claude.json в корне $HOME. Каждый профиль — это отдельная изолированная директория, где лежит всё: и папки projects/sessions, и тот самый файл с MCP-серверами и oauth-токенами. Один источник правды на профиль.

Почему symlink именно на personal

Всё, что хардкодит путь ~/.claude/ — старые скрипты, плагины, IDE-расширения Claude Code, statusline-конфиги типа claude-powerline.json — продолжает работать без изменений. Symlink резолвится в personal-профиль. Если случайно запустишь command claude (без обёртки-функции) — тоже попадёшь в personal через default-path lookup. Personal становится "тихим default'ом", как было раньше, но теперь физически живёт в XDG-локации.

Интерактивный выбор при запуске — функция + gum

Вместо алиасов — функция claude() в ~/.zshrc, которая показывает меню со стрелками через gum (TUI-helper от Charm). Функция перехватывает вызов claude на shell-уровне, даёт выбрать профиль и запускает command claude с соответствующим CLAUDE_CONFIG_DIR. command важно — оно обходит функцию-обёртку и вызывает реальный бинарь.

# brew install gum

# Claude Code: profile picker on launch
claude() {
  local profile
  profile=$(gum choose \
    --header "Claude profile:" \
    --cursor "▸ " \
    --selected.foreground 212 \
    --cursor.foreground 212 \
    --header.foreground 244 \
    "personal" "promova") || return
  case "$profile" in
    personal) CLAUDE_CONFIG_DIR="$HOME/.config/claude-profiles/personal" command claude "$@" ;;
    promova)  CLAUDE_CONFIG_DIR="$HOME/.config/claude-profiles/promova"  command claude "$@" ;;
  esac
}

Вид при запуске:

Claude profile:
▸ personal
  promova

↑↓ для навигации, Enter — выбрать, Esc — отменить (Claude просто не запускается). Профиль виден всегда — забыть невозможно.

Скрипт миграции

Для тех, кто это читает и хочет переехать со старой схемы. Самый критичный шаг — второй: он сливает ~/.claude.json из home root с тем, что уже лежит в personal-профиле, объединяя списки mcpServers. Без этого шага профиль потеряет и MCP, и весь live state.

# 1. Move existing dotfolders into a new XDG-style parent.
#    APFS mv is an inode rename — safe even if claude --resume is open in
#    another terminal, file descriptors stay alive on the same inode.
mkdir -p ~/.config/claude-profiles
mv ~/.claude          ~/.config/claude-profiles/personal
mv ~/.claude-promova  ~/.config/claude-profiles/promova   # rename as needed

# 2. CRITICAL: merge ~/.claude.json (the live state — likely 100+ KB) into
#    the personal profile, unioning mcpServers so no MCP is dropped.
jq -s '.[0] * {mcpServers: (.[0].mcpServers + .[1].mcpServers)}' \
  ~/.claude.json \
  ~/.config/claude-profiles/personal/.claude.json \
  > /tmp/personal-merged.json
mv /tmp/personal-merged.json ~/.config/claude-profiles/personal/.claude.json

# 3. Fix permissions — jq+mv inherits umask (likely 644), but this file
#    holds OAuth tokens. Tighten to 600 immediately.
chmod 600 ~/.config/claude-profiles/personal/.claude.json

# 4. Back up the orphaned home-root file (delete once verified)
mv ~/.claude.json ~/.claude.json.migrated.bak

# 5. Symlink for backward compatibility (statusline configs, IDE plugins,
#    anything that hardcodes ~/.claude/ keeps working unchanged)
ln -s ~/.config/claude-profiles/personal ~/.claude

Третий шаг про права — отдельно важный. jq | mv создаёт файл с umask 644 (world-readable). В нём oauth tokens. Обязательно chmod 600 сразу после merge.

После миграции — закрой и открой все активные Claude сессии, перезагрузи shell (source ~/.zshrc или новый терминал), запусти claude, выбери профиль, проверь через claude mcp list, что все MCP на месте. Если всё ок — удали ~/.claude.json.migrated.bak. Если что-то не так — откат тривиален: mv ~/.claude.json.migrated.bak ~/.claude.json и убрать symlink.

Что ты получаешь

• Один родительский каталог вместо двух dotfolder'ов в $HOME — XDG-совместимо
• Symlink сохраняет совместимость со всем, что хардкодит ~/.claude/
• Каждый профиль самодостаточен — свой полный state и свои MCP в собственном .claude.json
• Один источник правды на профиль — больше нет orphan-конфига в home root, который тихо расходится с профильным
• Sensitive data (oauthAccount, tokens) гарантированно с правами 600
• Визуальное подтверждение активного профиля при каждом запуске — забыть, какой профиль активен, невозможно
• Добавить третий профиль = добавить одну строку в case функции, а не клонировать новый алиас и помнить его имя

Где это даёт слабину

Хочу честно. Это не бесплатное улучшение — несколько компромиссов пришли в комплекте, и о них стоит знать заранее.

• gum — дополнительная зависимость (brew install gum, ~13 MB). Если принципиально не хочешь ставить — fallback на select в zsh или простой read. Работает, но выглядит не так красиво и не имеет стрелочной навигации.
• Один Enter при каждом запуске. Для тех, кто запускает claude десятки раз в день — может раздражать. Альтернатива ниже (direnv).
• Symlink ~/.claude → personal делает personal default'ом. Если нужно сделать default work-профиль — нужно перенаправить symlink (ln -sf). Несложно, но это не "забыл — ничего не сломается".
• Symlink теоретически может сломаться, если какой-то инструмент атомарно перезаписывает ~/.claude.json через temp+rename pattern (write-file-atomic). На практике Claude Code сам так не делает, но если ставишь сторонние плагины — проверь.
• Если у тебя на профилях разные Anthropic-аккаунты с разными планами — после переключения может быть sub-second лаг, пока Claude Code синкает OAuth state. В моём использовании незаметно, но это не ноль.

Альтернативы, которые рассматривал

direnv — автоматически выставляет CLAUDE_CONFIG_DIR в зависимости от .envrc в корне каждого проекта. Ноль интерактива, ноль кликов. Минус: нужно прописать .envrc в каждом work-root, и если запускаешь claude в нераспознанной папке — получаешь дефолтный профиль (может быть не тот, что нужно). Для тех, кто живёт в ограниченном количестве work-roots и хочет никогда не кликать — direnv реально лучше.

Symlink-based switch (единственный активный профиль через перенаправление ~/.claude symlink) я тоже рассмотрел и сразу отбросил. Не можешь иметь два терминала с разными профилями одновременно — глобальная "текущая" одна. Для меня это deal-breaker.

Вывод

v2 — это не просто лучший UX над v1. Это признание того, что Claude Code имеет скрытую архитектурную особенность (~/.claude.json как отдельный файл в home root, который пишется --scope user командами независимо от CLAUDE_CONFIG_DIR), которую нужно учесть, если хочешь настоящую изоляцию между профилями. Первый подход (~/.claude + ~/.claude-promova + алиас) работал на 80%, но те 20%, что остались, проявлялись молчаливым расхождением состояния между профилями. Теперь это учтено. Если ты только начинаешь — стартуй сразу с v2. Если уже сидишь на v1 — скрипт миграции выше, переезд занимает пять минут и ничего не ломает (именно jq merge — это тот шаг, который спасает тебя от потери state).

Два правила превратили мои хаотичные воркфлоу с галлюцинациями в надёжные пайплайны: один агент — одна специализация и всё, что можно выполнить как shell-команду, должно выполняться как shell-команда. Это не теория. Это то, что я делаю каждый день с Claude Code, и именно эти паттерны реально двигают дело.

Почему агенты-универсалы врут

LLM — это предсказатель следующего токена. Когда в промпте две роли — сделай X и проверь X — модель заканчивает первую роль, а затем предсказывает, как выглядел бы вывод второй, не выполняя её на самом деле. Самопроверка структурно слаба: тот же контекст, та же модель, те же слепые пятна. Прошло на проверке коррелирует с прошло на построении — они фейлятся вместе.

Модель не знает, что врёт. С её точки зрения, я всё тщательно проверил — это когерентное продолжение я написал код. По той же причине ты уверен? не ловит галлюцинации: модель так же уверена на втором проходе. Уверенность не коррелирует с правильностью — она коррелирует с тем, насколько правдоподобно звучит следующее предложение.

Решение — не лучший промпт. Будь осторожен, перепроверь, не галлюцинируй — эти инструкции не делают ничего. Решение структурное: специализируй агента так, чтобы он физически не мог притворяться, и пропускай количественную работу через shell, чтобы ответ приходил из реального состояния, а не из вероятности токенов.

Правило 1: один агент — одна специализация

Раздели работу на отдельных агентов с отдельными контекстами. У каждого — одна ответственность и узкий набор инструментов. Весь процесс становится эстафетой, а не одним агентом, который бегает по кругу:

• Builder-агент: берёт спек, пишет код. Это его единственная задача. У него Read, Edit, Write, Bash.
• Reviewer-агент: берёт спек плюс диф, проверяет по критериям. Чистый контекст. Не знает как код был написан — только что вышло. У него Bash, Read, Grep, Glob — никаких инструментов записи.
• Analytics-агент: отвечает на вопросы по данным, конструируя и запуская запросы. Только Bash. Не может дойти до ответа без запуска реальной команды.
• Оркестратор: основная сессия, которая вызывает каждого агента по очереди и никогда не просит одного делать работу другого.

Конкретный пример: вёрстка UI плюс визуальная проверка по макету в Figma. Builder пишет компоненты и коммитит диф. Затем оркестратор вызывает Reviewer с URL макета, дифом и чёткими acceptance criteria. Reviewer запускает Playwright, снимает скриншоты, диффит их с референсом и возвращает PASS или FAIL с реальными путями скриншотов и pixel diff. Builder вообще не приближается к шагу проверки — и именно поэтому проверка настоящая.

Антипаттерн — это мега-агент: один промпт вроде сверстай этот UI и убедись, что он совпадает с макетом. Гарантирую — он напишет, что всё совпадает. Не совпадает. Нарратив я проверил — это просто наиболее вероятная последовательность токенов после я сверстал.

Правило 2: shell вместо промпта, всегда

Всё количественное, всё что касается реального состояния, всё где ответ может быть неправильным так, что выглядит правильно — гони через sh. Задача агента — сконструировать и запустить команду, затем прочитать её вывод. Агент не является источником истины. Вывод shell является.

• Подсчёт: wc -l logs.txt — правда. Приблизительно 47 строк лога от модели — галлюцинация.
• Аналитика: psql -c "SELECT count(*) FROM events WHERE created_at > now() - interval '30 days'". Не оцени объём.
• Тесты: pnpm test --reporter=json | jq '.numFailedTests'. Не расскажи что зафейлилось.
• Git-состояние: git rev-list --count main..HEAD, git diff --stat. Не посчитай коммиты или опиши изменения.

Когда это усвоишь, начинаешь замечать каждое место, где агент только что собирался придумать число. Похоже, здесь около 200 записей... — нет. Запусти SELECT count(*). Большинство тестов проходит... — нет. Запусти тесты, распарси JSON. Модель отлично умеет конструировать команду. Она ненадёжна в том, чтобы быть командой.

Конкретные режимы фейла, которые я словил

Это не гипотетические примеры. Каждый из них стоил мне реального времени до того, как я сменил паттерн:

• Призрачная проверка. Агент сказал я проверил все 14 секций по макету. Не открывал макет. Не делал скриншот. Проверка была галлюцинированным шагом в нарративе.
• Уверенные неправильные числа. Запросил monthly active users из аналитических данных. Получил число, промахнувшееся примерно в 3 раза. Модель интерполировала по выборочным строкам вместо того, чтобы запустить реальный запрос.
• Выдуманные изменения файлов. Агент сказал я обновил config/feature-flags.json. Не обновлял. Он только собирался. git diff был пустым.
• Фейковые прогоны тестов. Все тесты проходят. Ни один тест не запускался. Агент даже не вызвал тест-раннер — он предсказал, как выглядел бы его вывод.

Все четыре решаются теми же двумя правилами: раздели агента, выталкивай в shell. У Reviewer нет Write, поэтому он не может фейково редактировать файлы. У Analytics-агента только Bash, поэтому он не может вернуть число, которое не пришло из запроса. Структурная невозможность бьёт добрые намерения каждый раз.

Как это структурировать в Claude Code

Claude Code поддерживает sub-агентов, описываемых в .claude/agents/*.md. Каждый файл агента декларирует имя, описание, разрешённый набор инструментов и системный промпт. Оркестратор (твоя основная сессия) вызывает их через инструмент Agent. Вот тип определения, который я использую для reviewer — короткий, узкий, физически неспособный писать код:

---
name: reviewer
description: Reviews a diff against acceptance criteria. Cannot edit code.
tools: Bash, Read, Grep, Glob
---

You are a strict code reviewer. You receive:
- A diff (already produced by the builder)
- Acceptance criteria

Your job:
1. Run the build, the tests, the linter — through Bash.
2. Read the changed files directly.
3. Compare the actual behavior to the criteria.
4. Report PASS or FAIL with concrete evidence (command output, file excerpts).

You must NOT:
- Trust the builder's summary
- Assume anything was verified just because it was claimed
- Mark something PASS without running the actual check

Обрати внимание на набор инструментов: Bash, Read, Grep, Glob. Никакого Write, никакого Edit, никакого Agent. Reviewer может запускать команды, читать файлы, искать паттерны — и ничего больше. Если он попытается выдать галлюцинированный диф за проверенный, форма его вызовов инструментов делает это очевидным: реальных проверок не было. Можно заоудитить вызовы и увидеть ровно то, что инспектировалось.

Паттерн оркестрации: основная сессия вызывает Builder → ждёт → сама запускает git diff, чтобы зафиксировать реальное изменение → вызывает Reviewer со спеком и дифом → читает вердикт. Основная сессия никогда не просит одного агента делать оба. Ограничения инструментов сильнее инструкций в промпте: не фейкай проверку — это пожелание. Отсутствие Write — это факт.

Антипаттерны, которые пора выкинуть

То, что вижу в промптах и что не делает ничего — или, хуже, даёт ложное ощущение безопасности:

• Будь осторожен и перепроверь свою работу. Не генерирует никакого дополнительного поведения. Модель и так выдаёт то, что выглядит как тщательная работа.
• Убедись, что ты действительно проверил. Слово действительно не добавляет семантики, на которую модель может среагировать. Она действительно заявит, что проверила.
• Не галлюцинируй. Мем в prompt engineering. Галлюцинация — не переключатель, который модель может выключить.
• Доверять модели на маленьких числах. Именно на маленьких числах она врёт увереннее всего. Порога честности не существует.
• Добавление правил в промпт, чтобы заставить честность. Структурные решения (разделить + shell) бьют твики промпта каждый раз. Если правило нужно энфорсить — закодируй его в доступе к инструментам, а не в тексте.

Если твоя стратегия ловить галлюцинации — это подбирать более эмфатичные формулировки, то у тебя нет стратегии. У тебя есть надежда.

Ментальная модель

Агент — не коллега. Это функция: prompt → tokens. Функция отлично пишет код и плохо интроспектирует, сделала ли она правильную вещь. Воспринимай её утверждения о собственной работе как гипотезу. Диф, exit-код, скриншот, row count — вот доказательства. Итоговый саммари в конце хода — самая лживая поверхность во всей системе.

Специализация — твоя страховка от нарративного дрейфа. Shell — твой единственный источник истины. Builder пишет. Reviewer проверяет. Bash решает.

Вывод

Если запомнить одно: не позволяй одному агенту и производить, и судить собственный вывод; и не позволяй ни одному агенту отвечать на количественный вопрос без запуска команды. Всё остальное — следствие этих двух правил. Настраивай доступ к инструментам агрессивно, аудитируй вызовы инструментов вместо саммари — и поверхность галлюцинаций сжимается с повсюду до нескольких конкретных мест, где ты уже знаешь смотреть.

Проблема

Claude Code по умолчанию хранит всё в ~/.claude — OAuth-токен, историю разговоров, глобальный CLAUDE.md, память проектов, конфиги MCP-серверов и настройки. Когда у тебя два аккаунта, нужны два полностью изолированных окружения:

• Личный аккаунт: собственная подписка Max/Pro, персональный CLAUDE.md с твоими предпочтениями, твои MCP-серверы (Obsidian, личные инструменты)
• Корпоративный аккаунт: план компании, рабочий CLAUDE.md с инструкциями для Jira/Slack, корпоративные MCP-серверы
• Разные OAuth-сессии: невозможно быть залогиненным в два аккаунта в одной директории конфигурации
• Разная память проектов: ты не хочешь, чтобы контекст рабочих проектов попадал в личные сессии и наоборот

Разлогиниваться и логиниться каждый раз при смене контекста — не вариант. Теряешь состояние сессии, и это просто больно.

Решение: CLAUDE_CONFIG_DIR

Claude Code поддерживает одну переменную окружения: CLAUDE_CONFIG_DIR. Укажи любой путь — и Claude будет использовать эту директорию вместо ~/.claude для всего: авторизации, истории, настроек, памяти. Весь процесс занимает 60 секунд.

Шаг 1: Создать вторую директорию конфигурации

Выбери имя, соответствующее твоему случаю:

mkdir ~/.claude-work

Всё. Claude заполнит её необходимой структурой при первом запуске.

Шаг 2: Авторизовать второй аккаунт

Запусти Claude с новой директорией конфигурации для OAuth-логина:

CLAUDE_CONFIG_DIR=~/.claude-work claude

Откроется браузер. Залогинься корпоративным аккаунтом. OAuth-токен сохранится в ~/.claude-work — полностью отдельно от личной сессии в ~/.claude.

Шаг 3: Добавить shell alias

Добавь это в конфиг шелла, чтобы не запоминать переменную:

alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

Перезагрузи шелл:

source ~/.zshrc

Что получаешь

Теперь у тебя два полностью изолированных окружения Claude:

• claude — запускает с личным аккаунтом, персональным CLAUDE.md, личной памятью
• claude-work — запускает с корпоративным аккаунтом, рабочим CLAUDE.md, отдельной памятью
• Изолированная история: рабочие разговоры остаются в работе, личные — в личном
• Отдельные MCP-серверы: твой Obsidian vault MCP не появляется в рабочих сессиях
• Независимые настройки: разные разрешённые инструменты, разные уровни прав, разные предпочтения моделей для каждого аккаунта

Как это работает под капотом

Директория конфигурации — единственный источник истины для состояния Claude Code. Вот что живёт внутри каждой:

~/.claude/              ← personal account
├── CLAUDE.md           ← personal global instructions
├── projects/           ← personal project memory
├── settings.json       ← personal permissions & MCP servers
└── ...                 ← OAuth session, history, cache

~/.claude-work/         ← corporate account
├── CLAUDE.md           ← company-specific instructions (Jira, Slack, etc.)
├── projects/           ← separate project memory
├── settings.json       ← different MCP servers, permissions
└── ...                 ← separate OAuth session

Когда запускаешь claude-work, Claude читает всё из ~/.claude-work. Он не знает о существовании ~/.claude. Два инстанса полностью независимы — можешь даже запускать их одновременно в разных вкладках терминала.

Масштабирование на N аккаунтов

Паттерн расширяется на любое количество аккаунтов. Фрилансер с несколькими клиентами? Добавь больше alias'ов:

# Personal (default — no alias needed)
# Just run: claude

# Corporate
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

# Freelance client
alias claude-client='CLAUDE_CONFIG_DIR=~/.claude-client claude'

Каждый alias получает собственную директорию конфигурации, собственную OAuth-сессию, собственный CLAUDE.md с инструкциями для конкретного клиента.

Практические советы

• Называй директории чётко: ~/.claude-work, ~/.claude-clientname — скажешь себе спасибо, когда их будет три-четыре
• Пиши отдельный CLAUDE.md для каждого: рабочий может включать инструкции компании (как создавать Jira-тикеты, Slack-каналы, процедуры деплоя). Личный остаётся минимальным.
• Разные MCP-серверы для каждого аккаунта: настрой рабочие инструменты (Jira MCP, Slack MCP, внутренние API) только в рабочем конфиге. Личный держи чистым.
• Проверь какой аккаунт активен: запусти claude config list в сессии — покажет путь к директории конфигурации

Где этот подход ломается

CLAUDE_CONFIG_DIR разделяет по аккаунту, а не по проекту. Внутри одного профиля Claude видит все MCP-серверы, которые ты когда-либо зарегистрировал для этого аккаунта — по всем своим проектам. Для соло-использования это обычно не проблема. Но как только под одним аккаунтом появляется несколько production-критичных проектов, особенно в пересекающихся доменах (биллинг, админка, инфраструктура), возникает реальный cross-project риск: AI-ассистент может вызвать tool из проекта A во время работы над проектом B — особенно когда оба экспонируют похожие по названию операции.

Профиль отвечает на вопрос which account am I in?. Он не отвечает на вопрос which project's tools should be active right now?. Для работы с более высокими ставками — добавь второй слой изоляции поверх разделения по аккаунтам:

• Один профиль на каждый production-критичный проект, а не только на аккаунт: вместо ~/.claude и ~/.claude-work создай ~/.claude-work-billing и ~/.claude-work-admin. Каждый профиль видит только те MCP-серверы, которые ему действительно нужны.
• Project-scope MCP через .mcp.json: положи .mcp.json в корне проекта с MCP-серверами только этого проекта. Claude подхватит их, когда запущен из этой директории. Держи глобальный конфиг минимальным — только универсальные инструменты (заметки, поиск), никаких production-эндпоинтов.
• Именуй MCP-серверы однозначно: избегай generic-названий типа admin, billing, mcp-server. Префиксуй именем проекта: acme_billing_prod, acme_admin_stage. Описательное имя заставляет остановиться, когда что-то вот-вот вызовется из неправильного контекста.
• Перечитывай каждый MCP tool call перед approve: вызовы вроде *_create_*, *_delete_*, *_charge_* заслуживают осознанного второго взгляда. Скорость, которую даёт blanket auto-approval, испаряется в первый же раз, когда tool из не того проекта выстрелит в production.

Общее правило: дроби профили агрессивно, держи production-grade MCP подальше от default-профиля, и любое пересечение имён tools между проектами считай smell'ом, который стоит отрефакторить.

Вывод

Одна переменная окружения. Один alias. Полная изоляция между аккаунтами. Никакого logout/login, никаких конфликтов конфигураций, никакой утечки контекста. Решение, которое почти разочаровывающе простое — но именно это делает его хорошим. Настрой один раз и больше никогда не думай об этом.

Что такое MCP и почему это не так просто

MCP (Model Context Protocol) — открытый протокол от Anthropic, который позволяет Claude подключаться к внешним инструментам и данным. Принцип прост: запускается локальный сервер, экспонирующий "инструменты" (tools), а Claude их вызывает во время разговора.

Для Obsidian теоретически есть масса MCP-серверов. На практике — у каждого свои проблемы.

Главная проблема экосистемы Obsidian: Obsidian — закрытое приложение без официального MCP. Сообщество заполнило пробел, но каждая имплементация идёт своим путём, и "официального благословения" нет ни у одной.

Попытка 1: MarkusPfundstein/mcp-obsidian

Первый инструмент, который находится при поиске. 3400 звёзд на GitHub, во всех туториалах. Кажется безопасным выбором.

Как работает: Python-сервер на основе плагина Local REST API в Obsidian. Сервер обращается к плагину через HTTPS, плагин выполняет операции через Obsidian API.

Что пошло не так

• Не обновлялся 17 месяцев
• 85 открытых issues
• Нет move/rename — только read, write, append, delete
• Local REST API имеет документированный data-loss баг: POST endpoint может молча перезаписать файл при append

Для рефакторинга не годится — нам нужно перемещать файлы и сохранять ссылки. Идём дальше.

Попытка 2: aaronsb/obsidian-mcp-plugin

Нашёл вариант, который работает как нативный плагин Obsidian. Это означает прямой доступ к внутреннему API Obsidian — backlinks, Dataview, граф связей. Move через нативный API обновляет все вики-ссылки автоматически, потому что Obsidian сам это обрабатывает.

Сложности установки

• Плагин не в официальном каталоге Obsidian (PR висит с ошибками валидации)
• Устанавливать нужно через BRAT (Beta Reviewers Auto-update Tool)
• Claude Desktop не принимает Bearer token напрямую через UI — пришлось включать HTTPS в плагине
• Self-signed сертификат для localhost создаёт проблемы с доверием

Через все эти обходные пути наконец подключил. Базовый тест — vault.move действительно переписывает [[wikilinks]], работает как надо.

Что пошло не так в бою

Когда начал массовый рефакторинг (drag-and-drop десятков папок в Obsidian + одновременные MCP-операции), сервер завис на 4+ минуты. Почему: плагин работает внутри Obsidian. Когда Obsidian переиндексирует тысячи файлов после массового изменения структуры, плагин блокируется вместе с ним.

Вывод: зависимость от открытого Obsidian и его индекса — фатальна для bulk-операций.

Попытка 3: @bitbonsai/mcpvault

Логично — нужен сервер, который не зависит от Obsidian. Работает напрямую с файлами на диске. @bitbonsai/mcpvault — рекомендуется во многих обзорах. Прямой доступ к файловой системе, простая настройка (npx @bitbonsai/mcpvault@latest /path/to/vault), 14 инструментов. Obsidian вообще не нужно держать открытым.

Перед установкой проверил один критический момент — обновляются ли вики-ссылки при move. Нашёл отзыв пользователя:

Filesystem connector не знает, что он в Obsidian — видит папку с <code>.md</code> файлами и всё. Не знает, что имена файлов несут семантическую нагрузку, что каждый <code>[[wikilink]]</code> сломается в момент rename или move. Auto-update links срабатывает только когда rename происходит изнутри приложения. Я узнал это после того, как попросил Claude почистить имена файлов и вернулся к dashboard с половиной сломанных ссылок.

Подтвердилось в документации самого mcpvault: PR #101 (wiki link resolution) в review, не помержен. То есть move через mcpvault сломает половину vault. Не годится.

Попытка 4: VaultForge (финал)

blacksmithers/vaultforge — специально построен для AI-агентов, которые делают рефакторинг.

Архитектурно правильно

• Direct filesystem — не зависит от Obsidian
• Собственный wikilink engine — реализована логика резолвинга [[wikilinks]], обновляющая все формы (stem, полный путь, alias, embed)
• Dry run по умолчанию на всех разрушительных операциях — сначала показывает что изменится, потом подтверждаешь
• 27 инструментов против 8–14 у конкурентов: batch_rename, update_links, backlinks (impact analysis), prune_empty_dirs, frontmatter, smart_search (BM25), vault_themes (TF-IDF clustering)
• MIT лицензия, TypeScript, zero sub-dependencies
• Установка за 30 секунд через .mcpb (one-click extension для Claude Desktop)

Тест безопасности на изолированных файлах

Создал 4 тестовых файла с перекрёстными ссылками — stem-ссылки, ссылки с alias, ссылки с полным путём. Перемещаю один файл в подпапку:

delta.md → subfolder/delta-renamed.md

VaultForge показал dry run: "1 файл будет переименован, 3 ссылки будут обновлены". Выполнил по-настоящему.

Проверил после — все три типа ссылок обновились корректно. Это именно то, чего не хватало всем предыдущим инструментам.

Как установить VaultForge — финальная инструкция

Если у вас macOS и Claude Desktop:

Шаг 1

Скачайте .mcpb файл:

curl -fsSL https://github.com/blacksmithers/vaultforge/releases/latest/download/vaultforge.mcpb \
  -o /tmp/vaultforge.mcpb && open /tmp/vaultforge.mcpb

Шаг 2

Claude Desktop откроет диалог установки расширения. Введите абсолютный путь к vault — без backslashes, с нормальными пробелами:

/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault

Шаг 3

Нажмите Save. Claude Desktop сам добавит расширение в конфиг. Перезапуск не нужен — .mcpb extensions подхватываются автоматически.

Шаг 4

Проверьте: в новом чате спросите: "Какой статус моего Obsidian vault?" — должно вернуться что-то вроде totalFiles: 416, totalDirs: 135, ...

Что я понял про MCP-экосистему Obsidian

Во-первых, "самый популярный" не значит "рабочий". MarkusPfundstein/mcp-obsidian имеет 3400 звёзд и его ставят по умолчанию, но он устарел и не имеет ключевых операций.

Во-вторых, нативный плагин имеет скрытую цену. Aaronsb plugin выглядел идеально — graph, Dataview, нативные move. Но зависимость от открытого Obsidian и его индекса делает его непригодным для серьёзных массовых операций.

В-третьих, direct filesystem без link-engine — ловушка. Mcpvault быстрый и простой, но "просто перемещение файлов" разрушает структуру vault. Ссылки — это навязанная семантика, о которой файловая система не знает. Без собственной реализации wikilink-логики инструмент превращается в мину.

В-четвёртых, проверяйте на изолированных данных. Прежде чем доверять инструменту массовый рефакторинг — создайте тестовую папку с 4–5 файлами с перекрёстными ссылками и посмотрите, что происходит. 5 минут тестов экономят часы восстановления из backup.

В-пятых, держите git-бэкап vault. Самое важное из всего. Один git init внутри vault и периодические коммиты — это страховка от любых ошибок AI-агента или инструмента. Если что-то сломается — git reset --hard вернёт всё назад.

Заключение

Путь занял несколько часов и три неудачных попытки. Финальная архитектура выглядит так:

• VaultForge — основной рабочий инструмент. Direct filesystem + собственный wikilink engine + 27 инструментов = стабильный рефакторинг любого масштаба.
• Git — версионирование vault. Бесплатный откат для любой ошибки.

Теперь можно делать то, ради чего всё затевалось: попросить Claude разложить 400 заметок по нормальной архитектуре PARA, объединить дубли, добавить frontmatter, построить MOC-карты. Каждая операция безопасна, ссылки сохраняются, dry run показывает что будет до того, как что-то изменится.

Если вы тоже смотрите на свой захламлённый Obsidian и хотите AI-помощника — начинайте сразу с VaultForge. Не повторяйте мой маршрут через мёртвые проекты, beta-плагины и filesystem-серверы без link-логики.

Что если каждая чёрная дыра — это Большой Взрыв новой вселенной? Эта статья исследует идею о том, что наша вселенная может быть одним узлом в бесконечном рекурсивном дереве — где чёрные дыры порождают дочерние вселенные, энергия возвращается через излучение Хокинга, а фундаментальные законы физики намеренно устроены так, чтобы контакт между вселенными был невозможен.

Чёрная дыра = вселенная

Идея пришла в момент размышлений: чёрная дыра образуется, когда достаточно массы и давления концентрируется в одной точке. Эта сингулярность — бесконечная плотность, бесконечная кривизна — подозрительно напоминает условия, которые мы описываем для Большого Взрыва.

Что если это одно и то же событие, но наблюдаемое с разных сторон? Снаружи мы видим чёрную дыру, поглощающую материю. Изнутри — новую вселенную, взрывающуюся к жизни. Масса и энергия, схлопнувшиеся в чёрную дыру, становятся сырьём для совершенно нового космоса — со своими звёздами, планетами и, возможно, собственными чёрными дырами.

Каждая чёрная дыра в нашей вселенной может содержать целую вселенную. А наша вселенная может существовать внутри чёрной дыры родительской вселенной.

Почему вселенные не могут контактировать друг с другом

Вот в чём элегантность: как только вы пересекаете горизонт событий — обратного пути нет. Общая теория относительности это гарантирует — будущее родительской вселенной лежит целиком за пределами горизонта событий, недостижимое изнутри. С точки зрения дочерней вселенной, родительская уже закончилась. Вся её временная линия уже прошла.

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

Цикл энергии: заимствование и возврат

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

1. Родительская вселенная создаёт чёрную дыру, передавая энергию в дочернюю вселенную
2. Дочерняя вселенная проживает весь свой жизненный цикл на протяжении триллионов лет
3. Чёрная дыра медленно испаряется, возвращая энергию родительской вселенной через излучение Хокинга
4. Родительская вселенная получает свою энергию обратно — с процентами

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

Рекурсия до самого дна

Если вы программист, паттерн безошибочен. Это рекурсия. Каждая вселенная вызывает universe() с меньшей энергией, создавая дочерние вселенные, которые создают вложенные вселенные, пока энергии не остаётся достаточно для формирования чёрных дыр — базовый случай.

universe(energy)
  ├── creates black holes
  │     ├── universe(energy - n)
  │     │     ├── universe(energy - n - m)
  │     │     │     └── base case: not enough energy for black holes
  │     │     └── returns energy via Hawking radiation
  │     └── returns energy via Hawking radiation
  └── receives all energy back

Физик Ли Смолин формализовал похожую идею как Космологический Естественный Отбор: вселенные «размножаются» через чёрные дыры, и каждое поколение имеет слегка отличающиеся физические константы — оптимизированные за бесчисленные циклы для создания большего количества чёрных дыр, большего числа вселенных.

Где мы в этом цикле?

Нашей вселенной примерно 13,8 миллиарда лет. Звучит внушительно, но в контексте полного срока её жизни мы наблюдаем лишь самое начало:

Мы существуем приблизительно на 0,00000000...01% общей продолжительности жизни нашей вселенной. Эра звёзд — всё, что мы можем наблюдать — это краткая вспышка в самом начале. Подлинная история вселенной — это медленная, терпеливая эра чёрных дыр, создающих и испаряющих дочерние вселенные.

Вопрос высших измерений

Всё обсуждённое до сих пор укладывается в рамки нашего трёхмерного понимания. Но если наша вселенная — это «срез» чего-то многомерного, то всё рекурсивное дерево чёрных дыр и дочерних вселенных может быть лишь тенью структуры, которую мы не способны воспринять.

В 1884 году Эдвин Эбботт написал «Флатландию» — историю о двумерных существах, неспособных представить третье измерение. Сфера, проходящая через Флатландию, выглядит как круг, который растёт и уменьшается. «Флатландцы» могут описать это математически, но никогда не поймут по-настоящему, что именно они наблюдают. Мы можем находиться в точно таком же положении по отношению к нашей вселенной.

Что такое сознание? Почему существует субъективный опыт? Дэвид Чалмерс назвал это «трудной проблемой» — и это может быть сильнейшим свидетельством того, что нечто действует за пределами нашей мерности.

Всё заблокировано на фундаментальном уровне

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

• Хотите увидеть родительскую вселенную? Заблокировано горизонтом событий
• Хотите понять сознание? Заблокировано — система не может полностью проанализировать саму себя (теоремы Гёделя о неполноте)
• Хотите узнать, что было «до»? Заблокировано — время началось с Большого Взрыва
• Хотите воспринять высшие измерения? Заблокировано когнитивными ограничениями трёхмерного существа

Философ Колин Макгинн называет это когнитивным закрытием: некоторые вопросы закрыты для человеческого разума не из-за недостатка данных, а из-за самой архитектуры разума. Разница между «мы ещё не знаем» и «мы не можем знать» — колоссальна.

Единственное, что остаётся: самосовершенствование

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

Этот вывод пришёл не из религии и не из учебников философии. Он пришёл из логики чёрных дыр, рекурсии, теории информации и пределов познания. Экзистенциалисты, буддисты, стоики и физики — все приходят к одной точке разными путями: смысл существования, возможно, заключается в совершенствовании того существа, которое существует.

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

Литература

• Ли Смолин — Космологический Естественный Отбор
• Стивен Хокинг — Излучение Хокинга
• Дэвид Чалмерс — Трудная Проблема Сознания
• Эдвин Эбботт — Флатландия: Роман о Многих Измерениях (1884)
• Курт Гёдель — Теоремы о Неполноте

Для простых сайтов — портфолио, блогов, лендингов, сайтов малого бизнеса — традиционная CMS превращается в лишнюю нагрузку. AI-инструменты вроде Claude Code, Cursor и GitHub Copilot теперь могут редактировать кодовую базу напрямую, понимать контекст, переводить контент и деплоить изменения через git. Слой абстракции, который давала CMS, заменяется более умным интерфейсом: естественным языком.

Налог CMS, который вы платите

Любая CMS несёт скрытую стоимость. Не только подписку — целую экосистему сложности, которая оборачивает ваш простой сайт:

• Инфраструктура: база данных для хостинга, API для поддержки, панель управления для защиты. Один WordPress составляет ~43% веба и ~90% атак, направленных на CMS.
• Производительность: динамическая генерация страниц, API-запросы на каждый реквест, клиентская гидрация данных CMS. Ваше портфолио из 3 страниц теперь имеет архитектуру SaaS-продукта.
• Привязка к вендору: ваш контент живёт в чужой схеме базы данных. Миграция с Contentful на Sanity? Это проект, а не изменение конфигурации.
• Переключение контекста: редактируете код в IDE, потом переключаетесь на браузерную панель CMS, чтобы поменять заголовок. Две разные ментальные модели для одной и той же операции.
• Стоимость: цены headless CMS часто масштабируются с API-запросами или записями контента. Персональному блогу не нужна контент-инфраструктура за $99/месяц.

Для маркетингового сайта, где 50 человек ежедневно редактируют контент, эти затраты оправданы. Для портфолио разработчика или лендинга малого бизнеса? Вы строите мост через лужу.

Что изменилось: AI понимает ваш код

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

AI фундаментально изменил это уравнение. Современные AI-инструменты для кода не просто автодополняют — они понимают структуру проекта, читают существующие паттерны и делают контекстуально верные правки. Сдвиг рабочего процесса — колоссальный:

# Old workflow: CMS
1. Open browser → log into CMS dashboard
2. Navigate to content → find the right page
3. Edit in WYSIWYG editor → fight with formatting
4. Preview → looks different from production
5. Hit publish → pray the cache invalidates

# New workflow: AI
1. Tell AI: "Change the pricing on the landing page to $29/month"
2. AI edits the file, you review the diff
3. Push to git → deploy

Это не гипотеза. Этот блог работает на SolidStart с контентом в TypeScript-файлах. Каждая статья — включая эту — создана через AI: я говорю что написать, проверяю результат и пушу в git. Никаких панелей CMS. Никаких баз данных. Никакого API-слоя между контентом и кодом.

Реальные примеры с этого сайта

Этот сайт поддерживает 10 языков, имеет блог, динамически генерирует OG-изображения, RSS-ленты и карты сайта. Вот как выглядит контентный слой — чистый TypeScript:

// This blog post you're reading right now is a TypeScript file.
// No database. No API. No CMS dashboard.
// Just a typed object that AI can read and edit directly.

export const myPost: BlogPost = {
  slug: "ai-killed-cms",
  date: "2026-04-17",
  translations: {
    en: {
      title: "Why I stopped using a CMS",
      description: "AI understands my codebase better than any CMS UI.",
      content: makeContent(proseEn),
    },
    uk: { /* ... */ },
    de: { /* ... */ },
    // 10 languages — AI translates them all
  },
};

Вещи, которые я делаю через AI и которые раньше потребовали бы CMS:

• Добавить новую статью: "Напиши новую статью про X, следуй структуре существующих постов" — AI создаёт файл, добавляет переводы, регистрирует в индексе
• Обновить текст лендинга: "Измени заголовок героя на Y" — AI находит нужный файл и обновляет его
• Перевести контент: "Добавь немецкий перевод для страницы цен" — AI читает английскую версию и создаёт культурно адаптированный перевод, а не дословный
• Исправить опечатку: "На странице about опечатка, 'recieve' должно быть 'receive'" — сделано за 3 секунды, закоммичено в git с осмысленным сообщением

Что CMS на самом деле решала — и как AI это заменяет

Давайте будем честны о том, что CMS принесла, и как каждая возможность соотносится с AI-воркфлоу:

Ключевой инсайт: git уже является лучшей системой контроля версий, чем любая CMS когда-либо создавала. А естественный язык — лучший интерфейс, чем любой WYSIWYG-редактор — потому что он несёт намерение, а не только форматирование.

Смена парадигмы: код — это контентный слой

Мы наблюдаем инверсию. Двадцать лет тренд был отделять контент от кода — класть контент в базу данных, отдавать через API, рендерить на фронтенде. Это имело смысл, когда код было сложно редактировать, а контент должен был быть доступен нетехническим людям.

AI не сделал CMS устаревшей, став лучшей CMS. Он сделал CMS устаревшей, сделав код таким же доступным, как панель управления.

Эволюция управления веб-контентом следует чёткой траектории:

1. 2000-е: Монолитные CMS (WordPress, Drupal) — контент и представление связаны в одной системе
2. 2010-е: Headless CMS (Contentful, Strapi) — контент отделён через API, рендерится фронтенд-фреймворками
3. 2020-е: Генераторы статических сайтов + Markdown (Hugo, Astro) — контент как файлы, собираются при деплое
4. 2025+: Код-как-контент + AI — контент живёт в типизированном коде, AI — интерфейс редактирования

Когда CMS всё ещё нужна

Это не позиция "CMS мертва". CMS решает реальные проблемы на масштабе. Она по-прежнему нужна, когда:

• Большие редакционные команды: 10+ контент-редакторов, которым нужен ролевой доступ, процессы утверждения и одновременное редактирование. Конфликты мёрджа в git — не проблема контент-редактора.
• Высокочастотный контент: новостным сайтам, публикующим 50+ статей в день, нужны оптимизированные редакционные пайплайны, а не git-коммиты.
• Сложные связи контента: каталоги e-commerce с тысячами SKU, вариантами товаров и динамическим ценообразованием нуждаются в структурированных базах данных.
• Регуляторное соответствие: отрасли, требующие аудит-трейлы, цепочки утверждения контента и юридически обязательные процессы проверки, нуждаются в специализированных системах.

Граница чёткая: если изменения контента требуют координации между несколькими нетехническими стейкхолдерами с высокой частотой — CMS заслуживает своей сложности. Если вы соло-разработчик, маленькая команда или управляете сайтом, который меняется раз в неделю, а не каждый час — AI + код проще, быстрее, дешевле и надёжнее.

Будущее: AI как универсальный интерфейс

Тренд выходит за пределы CMS. Каждый слой абстракции, который существовал потому что "базовая система слишком сложна для прямого взаимодействия", сжимается AI. Админ-панели, конфигурационные UI, визуальные редакторы баз данных — всё это интерфейсы, которые переводят человеческое намерение в системные изменения. AI выполняет этот перевод нативно.

Для простых сайтов будущее уже наступило. Ваш контент — это код. Ваш редактор — AI. Ваш контроль версий — git. Ваш деплой — это push. Весь слой CMS — панель управления, база данных, API, хостинг — был middleware между вашим намерением и вашим сайтом. AI устранил потребность в этом middleware.

Лучшая CMS — это отсутствие CMS. Не потому что управление контентом не важно — а потому что AI сделал сам код самым интуитивным интерфейсом управления контентом, который у нас когда-либо был.

Perplexity Desktop поддерживает MCP (Model Context Protocol) коннекторы. Добавив официальный @modelcontextprotocol/server-filesystem сервер, указывающий на ваш Obsidian vault, вы сможете естественным языком просить Perplexity читать, создавать и редактировать заметки — прямо из чата. Без плагинов, без расширений, без копирования.

Проблема

Perplexity отлично ищет — он просматривает интернет, суммаризирует источники и даёт ответы с цитатами. Но когда вы хотите сохранить находки в Obsidian vault, рабочий процесс ломается: копируете текст, переключаетесь на Obsidian, находите нужную заметку, вставляете, форматируете. Каждый. Раз.

Браузерные расширения вроде "Perplexity to Obsidian" помогают с экспортом, но они однонаправленные — ИИ не видит ваш vault, не может читать существующие заметки и не может решать куда что класть на основе структуры папок.

Что такое MCP?

Model Context Protocol (MCP) — это открытый стандарт, позволяющий AI-моделям взаимодействовать с локальными инструментами и источниками данных. Представьте USB-порт для ИИ — вы подключаете "сервер" (маленькую программу), и ИИ получает новые возможности. В нашем случае filesystem-сервер даёт Perplexity 14 инструментов для работы с файлами:

Perplexity Desktop (Mac App)
  │
  ├── MCP Connector: "Obsidian Vault"
  │     │
  │     └── @modelcontextprotocol/server-filesystem
  │           │
  │           ├── read_file()      → read any .md file
  │           ├── write_file()     → create or overwrite files
  │           ├── edit_file()      → patch existing files
  │           ├── list_directory() → browse vault structure
  │           ├── search_files()   → find files by pattern
  │           └── ... 14 tools total
  │
  └── Perplexity AI Model
        │
        └── "Save this to my daily note" → calls write_file()

Ключевой момент: AI-модель не имеет прямого доступа к вашим файлам. Она вызывает инструменты, предоставленные MCP-сервером, который работает локально на вашем компьютере. Ваши данные не покидают компьютер, пока вы явно не попросите ИИ что-то с ними сделать.

Требования

• Подписка Perplexity Pro (MCP-коннекторы доступны для платных пользователей)
• Perplexity Mac App из App Store (не браузерная версия)
• Node.js установленный на Mac (для работы npx)

Пошаговая настройка

Вся настройка занимает около 2 минут:

Команда

Команда для вставки в поле Command:

npx -y @modelcontextprotocol/server-filesystem "/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/Obsidian Vault"

Замените путь на фактическое расположение вашего Obsidian vault. Если vault синхронизируется через iCloud, путь будет под ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/. Обязательно оставьте кавычки — путь скорее всего содержит пробелы.

Как использовать

Когда коннектор покажет Running с 14 доступными инструментами, перейдите в любой чат Perplexity и начните общаться с вашим vault:

> Show me the structure of my Obsidian vault
> Add a new reflection to daily notes/2026-04-12.md: "Started using MCP today"
> Find all notes that mention "meditation"
> Create a new note in concepts/ about quantum computing
> List all files in my ideas/ folder

ИИ понимает структуру вашего vault, уважает ваши конвенции форматирования и может работать с существующим контентом. Вы можете попросить его найти тему в интернете и сохранить резюме прямо в конкретную заметку.

Почему MCP лучше других подходов

До MCP были ограниченные способы связать Perplexity и Obsidian:

Текущие ограничения

• Только Mac — MCP-коннекторы Perplexity сейчас работают только в версии из Mac App Store
• Без интеграции с Obsidian API — filesystem-сервер работает с файлами напрямую, а не через API Obsidian. Это значит, что он не активирует плагины Obsidian (Linter, Templater) при создании файлов
• Нужно подтверждение — чувствительные файловые операции могут требовать подтверждения в приложении Perplexity — это функция безопасности, а не баг

Выводы

Эта настройка превращает Perplexity из инструмента поиска в инструмент поиска-и-сохранения:

1. Ищите в интернете и сохраняйте в Obsidian в одном разговоре
2. ИИ видит структуру вашего vault и адаптируется к вашей системе организации
3. Ноль переключений между приложениями — всё происходит в чате Perplexity

Источники

• Model Context Protocol — official MCP specification
• MCP Filesystem Server — the server used in this setup
• Perplexity Help Center — Local and Remote MCPs for Perplexity
• Perplexity Blog — Everything is Computer

6-строчный bash-скрипт, который запускает Claude Code CLI в headless-режиме каждое утро в 9:00. Он ищет новости по 11 настраиваемым темам, фильтрует шум и записывает форматированный markdown-дайджест прямо в Obsidian vault, синхронизированный через iCloud. Ноль зависимостей. ~100 строк конфигурации.

Проблема

Как разработчик, следить за множеством технологий — это ежедневный налог. RSS-ленты шумные, Twitter отнимает время, рассылки приходят когда ты глубоко в потоке. Мне нужно что-то, что делает исследование за меня и показывает результаты там, где я уже работаю — в Obsidian vault.

Типичное решение — построить пайплайн скрапинга: планировщик, краулер, NLP-пайплайн, базу данных, сервис уведомлений. Это недели работы для чего-то, что сломается когда сайт поменяет HTML. Мне нужно что-то, что можно сделать за один вечер.

Архитектура

Вся система — 4 файла и ноль зависимостей:

macOS launchd (9:00 AM daily)
  │
  └── digest.sh
        │
        └── claude -p "$(cat prompt.md)" --max-turns 20 --allowedTools Read,WebSearch,WebFetch,Write
              │
              ├── Reads topics.yaml (11 configurable topics)
              ├── WebSearch → finds news for each topic (last 24-48h)
              ├── WebFetch → reads full articles
              ├── Filters noise: old tutorials, promos, AI spam
              └── Write → saves digest to Obsidian Vault
                    │
                    └── ~/Obsidian Vault/digests/2026-04-12.md
                          │
                          └── iCloud sync → available on all devices

Код (весь)

Проект намеренно минимальный. Каждая строка заслуживает своё место.

Точка входа: digest.sh

Всё приложение — это 6-строчный bash-скрипт:

#!/bin/bash
DIGEST_DIR="$HOME/Developer/news-digest"

claude -p "$(cat "$DIGEST_DIR/prompt.md")" \
  --max-turns 20 \
  --allowedTools Read,WebSearch,WebFetch,Write

Ключевые флаги: -p запускает Claude в headless-режиме, --max-turns 20 даёт агенту достаточно ходов, --allowedTools ограничивает агента чтением, поиском и записью.

Мозг: prompt.md

Здесь живёт интеллект. Промпт превращает Claude в агента исследования новостей:

# News Digest Agent

You are a news research agent. Your job is to find today's most important
and interesting news for a senior frontend developer.

## Instructions

1. Read the topics file at ~/Developer/news-digest/topics.yaml
2. For EACH topic, search the web for news from the last 24-48 hours
3. Filter: only include genuinely new and noteworthy items
4. Write the digest as a markdown file to Obsidian Vault digests/YYYY-MM-DD.md
5. IMPORTANT: Use the Write tool to save the file. Do NOT output to stdout.

## Rules

- Language: Ukrainian for summaries, English for titles and technical terms
- If there's no real news for a topic — SKIP IT ENTIRELY
- Prioritize: releases > breaking changes > security > new patterns > discussions
- Max 5 items per topic, sorted by importance
- Include direct links to sources
- Skip promotional content, generic tutorials, and AI-generated spam

Конфигурация: topics.yaml

Темы полностью настраиваемые — добавь новую тему и она будет в завтрашнем дайджесте:

topics:
  - name: better-auth
    context: "auth library for TypeScript. New releases, breaking changes"

  - name: Next.js
    context: "GitHub issues, releases, App Router, Turbopack, performance"

  - name: SolidJS
    context: "SolidStart, releases, ecosystem, comparison with React"

  - name: Tailwind CSS
    context: "v4 updates, new utilities, plugins"

  - name: Claude AI
    context: "Anthropic announcements, Claude Code, new models, MCP, API"

  - name: GPT AI
    context: "OpenAI announcements, new models, ChatGPT features"

  - name: React
    context: "React 19+, Server Components, new patterns, ecosystem"

  - name: Apple
    context: "Hardware, software, WWDC, developer tools, Apple Intelligence"

  - name: Notable People
    context: >
      Latest tweets from: Elon Musk, Dario Amodei, Sam Altman,
      Jensen Huang, Andrej Karpathy, Simon Willison, Swyx...

  - name: AI Global
    context: "Major AI news, new models, regulations, open-source AI"

Планирование через launchd

На macOS launchd — нативный способ планирования повторяющихся задач:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.news-digest</string>

    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>/Users/you/Developer/news-digest/digest.sh</string>
    </array>

    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>9</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>

    <key>StandardOutPath</key>
    <string>/Users/you/Developer/news-digest/logs/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/you/Developer/news-digest/logs/stderr.log</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
        <key>HOME</key>
        <string>/Users/you</string>
    </dict>
</dict>
</plist>

Установка: launchctl load ~/Library/LaunchAgents/com.news-digest.plist. Скрипт запускается каждый день в 9:00 — launchd запустит пропущенные задачи когда система проснётся.

Как выглядит результат

Каждое утро в Obsidian vault появляется новый markdown-файл:

---
date: 2026-04-12
---

# News Digest — 2026-04-12

## Next.js

### Next.js 16.1 Released with Improved Turbopack Caching
Нова версія Next.js 16.1 включає покращене кешування для Turbopack,
що зменшує час холодного старту на ~40%.
[Посилання](https://nextjs.org/blog/next-16-1)

### Critical Memory Leak Fix in App Router
Виправлено витік пам'яті в App Router при частому перемиканні
між динамічними маршрутами.
[GitHub Issue](https://github.com/vercel/next.js/issues/...)

## Claude AI

### Claude Code 1.5 — MCP Server Auto-Discovery
Anthropic випустив оновлення Claude Code з автоматичним
виявленням MCP серверів у проєкті.
[Блог](https://www.anthropic.com/news/...)

В цифрах

Ключевые решения

• Claude Code CLI вместо API — не нужно управлять API-ключами, HTTP-клиентами или парсить ответы
• Obsidian вместо email — дайджесты можно искать, ссылаться на них, они хранятся вечно
• launchd вместо cron — нативный планировщик macOS с обработкой пропущенных запусков
• YAML для тем — новая тема это изменение в 2 строки
• Пропускать пустые темы — нет новостей = нет секции

Как сделать своё

Запустить за 10 минут:

1. Установить Claude Code CLI и авторизоваться
2. Клонировать репо: git clone https://github.com/oleksiimazurenko/news-digest
3. Отредактировать topics.yaml и prompt.md
4. Отредактировать plist-файл и launchctl load
5. Ждать 9:00 — или протестировать вручную через bash digest.sh

Выводы

Самое интересное в этом проекте — то, чего в нём нет. Ни базы данных, ни API-сервера, ни Docker, ни npm-пакетов, ни Python, ни HTML-парсера, ни NLP-пайплайна.

Вот как выглядит построение с AI-агентами на практике: вы определяете что и куда, агент обрабатывает как. Время разработки: около 2 часов.

Источники

• news-digest on GitHub — full source code
• Claude Code Documentation — headless mode and CLI flags
• Apple Developer — creating launchd jobs
• Obsidian — markdown knowledge base

next-themes рендерит тег <script> внутри React Client Component для предотвращения вспышки темы (FOUC). React 19 теперь предупреждает об этом — и подавить это невозможно. Библиотека не обновлялась с марта 2025. Решение: заменить next-themes на Zustand store + useServerInsertedHTML для инъекции скрипта вне дерева React. Ноль новых зависимостей. Ноль FOUC. Ноль предупреждений.

Проблема

Если вы используете next-themes с Next.js 15+ и React 19, вы получаете эту ошибку в консоли при каждой загрузке страницы:

Encountered a script tag while rendering React component.
Scripts inside React components are never executed when rendering on the client.
Consider using template tag instead.

src/providers/theme-provider.tsx (7:10) @ ThemeProvider

Это не ошибка гидратации. React 19 явно предупреждает, что теги <script>, отрендеренные React-компонентами на клиенте, никогда не выполнятся. Скрипт работает при SSR (он есть в HTML), но React помечает это как некорректное.

Почему это происходит

next-themes должен установить правильный класс темы на <html> до гидратации React — иначе будет вспышка неправильной темы. Для этого он инжектит inline <script> через React.createElement:

// next-themes renders a <script> inside a Client Component
return React.createElement(Provider, { value },
  React.createElement("script", {
    suppressHydrationWarning: true,
    dangerouslySetInnerHTML: { __html: `(...theme init code...)` }
  }),
  children
)

React 19 изменил поведение: теги script внутри компонентов теперь явно помечаются. До React 19 это молча игнорировалось. Проп suppressHydrationWarning на скрипте не помогает — он подавляет предупреждения гидратации, а не предупреждение "script в компоненте".

Что мы пробовали (и почему не сработало)

Мы систематически перепробовали все подходы перед нахождением решения:

Решение: Zustand + useServerInsertedHTML

Ключевой инсайт: useServerInsertedHTML — это хук Next.js, который инжектит HTML в SSR-поток вне дерева React-компонентов. Скрипт попадает в HTML, но React никогда не "видит" его при клиентском рендеринге — поэтому нет предупреждения. В сочетании с Zustand store для реактивного состояния темы, мы получаем полную замену без зависимостей.

Как это работает

SSR (server):
  useServerInsertedHTML → injects <script> into HTML stream
  ↓
  Browser receives HTML with theme script already in it
  ↓
  Script runs BEFORE React hydrates → correct class on <html>
  ↓
  No flash. No mismatch. No warning.

Client (after hydration):
  useEffect → _init() → Zustand store syncs with localStorage
  ↓
  useTheme() → reactive theme state for components

Шаг 1: Zustand Store

Store управляет состоянием темы, применяет классы к DOM, обрабатывает определение системной темы и синхронизируется между вкладками. Метод _init() возвращает функцию очистки для использования в useEffect:

import { create } from "zustand";

const STORAGE_KEY = "theme";
const MEDIA_QUERY = "(prefers-color-scheme: dark)";

function getSystemTheme(): "light" | "dark" {
  return window.matchMedia(MEDIA_QUERY).matches ? "dark" : "light";
}

function applyTheme(resolved: string, disableTransition: boolean) {
  const d = document.documentElement;

  if (disableTransition) {
    const style = document.createElement("style");
    style.appendChild(
      document.createTextNode(
        "*,*::before,*::after{transition:none!important}"
      )
    );
    document.head.appendChild(style);
    window.getComputedStyle(document.body);
    setTimeout(() => document.head.removeChild(style), 1);
  }

  d.classList.remove("light", "dark");
  d.classList.add(resolved);
  d.style.colorScheme = resolved;
}

interface ThemeState {
  theme: string;
  systemTheme: "light" | "dark";
  resolvedTheme: string;
  setTheme: (theme: string) => void;
  _init: (disableTransition: boolean) => () => void;
}

export const useThemeStore = create<ThemeState>((set, get) => ({
  theme: "system",
  systemTheme: "light",
  resolvedTheme: "light",

  setTheme: (newTheme) => {
    const { systemTheme, disableTransitionOnChange } = get();
    const resolved = newTheme === "system" ? systemTheme : newTheme;
    localStorage.setItem(STORAGE_KEY, newTheme);
    applyTheme(resolved, disableTransitionOnChange);
    set({ theme: newTheme, resolvedTheme: resolved });
  },

  _init: (disableTransition) => {
    const stored = localStorage.getItem(STORAGE_KEY) || "system";
    const system = getSystemTheme();
    const resolved = stored === "system" ? system : stored;

    set({ theme: stored, systemTheme: system, resolvedTheme: resolved });
    applyTheme(resolved, disableTransition);

    // System theme changes
    const mq = window.matchMedia(MEDIA_QUERY);
    const onChange = (e: MediaQueryListEvent) => {
      const newSystem = e.matches ? "dark" : "light";
      const { theme } = get();
      set({ systemTheme: newSystem,
            resolvedTheme: theme === "system" ? newSystem : theme });
      if (theme === "system") applyTheme(newSystem, disableTransition);
    };
    mq.addEventListener("change", onChange);

    // Cross-tab sync
    const onStorage = (e: StorageEvent) => {
      if (e.key !== STORAGE_KEY || !e.newValue) return;
      const system = getSystemTheme();
      const resolved = e.newValue === "system" ? system : e.newValue;
      set({ theme: e.newValue, resolvedTheme: resolved });
      applyTheme(resolved, disableTransition);
    };
    window.addEventListener("storage", onStorage);

    return () => {
      mq.removeEventListener("change", onChange);
      window.removeEventListener("storage", onStorage);
    };
  },
}));

export function useTheme() {
  return useThemeStore((s) => ({
    theme: s.theme,
    setTheme: s.setTheme,
    resolvedTheme: s.resolvedTheme,
    systemTheme: s.systemTheme,
  }));
}

Шаг 2: ThemeProvider

Provider делает две вещи: инжектит скрипт предотвращения FOUC через useServerInsertedHTML и инициализирует Zustand store при монтировании:

"use client"

import { useEffect } from "react"
import { useServerInsertedHTML } from "next/navigation"
import { useThemeStore } from "@/store/use-theme-store"

const THEME_INIT_SCRIPT = `(function(){
  try {
    var t = localStorage.getItem("theme") || "system";
    var r = t;
    if (t === "system") {
      r = window.matchMedia("(prefers-color-scheme: dark)").matches
        ? "dark" : "light";
    }
    document.documentElement.classList.remove("light", "dark");
    document.documentElement.classList.add(r);
    document.documentElement.style.colorScheme = r;
  } catch(e) {}
})()`

export function ThemeProvider({
  children,
  disableTransitionOnChange = false,
}) {
  // Injects script into SSR HTML outside the React tree
  // — prevents FOUC without triggering React 19 warning
  useServerInsertedHTML(() => (
    <script dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }} />
  ))

  useEffect(() => {
    return useThemeStore.getState()._init(disableTransitionOnChange)
  }, [disableTransitionOnChange])

  return <>{children}</>
}

Шаг 3: Layout

import { ThemeProvider } from "@/providers/theme-provider"

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider disableTransitionOnChange>
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

Шаг 4: Использование

import { useTheme } from "@/store/use-theme-store"

export function ThemeSwitch() {
  const { theme, setTheme } = useTheme();

  return (
    <button onClick={() => setTheme(
      theme === "dark" ? "light" : "dark"
    )}>
      {theme === "dark" ? "☀️" : "🌙"}
    </button>
  );
}

Миграция с next-themes

API намеренно идентичен. Миграция — это одно изменение импорта на файл:

- import { useTheme } from "next-themes"
+ import { useTheme } from "@/store/use-theme-store"

  // API is identical — no other changes needed
  const { theme, setTheme, resolvedTheme, systemTheme } = useTheme()

Сравнение

Почему не другие альтернативы?

@wrksz/themes

Drop-in замена, которая тоже использует useServerInsertedHTML. Работает, но это ещё одна зависимость от одного мейнтейнера. Если next-themes нас чему-то научил — зависимости бросают. С ~100 строками кода вы можете полностью владеть решением.

next-themes@1.0.0-beta.0

Существует на npm, но без даты релиза, без changelog и без чёткого указания, что предупреждение React 19 исправлено. Ставить продакшн-код на бессрочную бету — неоправданный риск.

CSS-only (prefers-color-scheme)

Работает для определения системной темы, но не может обработать сохранение выбора пользователя (localStorage), ручное переключение темы или опцию "system". Для этого нужен JavaScript.

Выводы

1. next-themes фактически заброшен — последний релиз март 2025, предупреждение React 19 не исправлено
2. useServerInsertedHTML — правильный примитив Next.js для инъекции скриптов без предупреждений React
3. Zustand обеспечивает реактивное состояние темы с меньшим количеством кода, чем Context provider
4. Всё решение — ~100 строк, ноль новых зависимостей, и вы контролируете каждую строку

Источники

• shadcn/ui #10104 — Dark mode guide should address React 19 script warning
• next-themes #296 — React 19 support request (open since 2024)
• React #34008 — Script tags not executing in components (by design)
• @wrksz/themes — Drop-in replacement using useServerInsertedHTML
• Next.js Docs — useServerInsertedHTML API

Наше приложение (Promova) использует Next.js 16 с Landing Builder — CMS-системой, которая собирает маркетинговые страницы из ~90 различных секционных компонентов (герои, FAQ, цены, отзывы и т.д.). Архитектура использует sectionRegistry.tsx, который маппит названия секций на вызовы next/dynamic():

// sectionRegistry.tsx — imports all 90 sections
export const sectionRegistry = {
  HeroSection: dynamic(() => import('./HeroSection/HeroSection')),
  FAQSection: dynamic(() => import('./FAQSection/FAQSection')),
  ReviewsSection: dynamic(() => import('./ReviewsSection/ReviewsSection')),
  // ... 87 more
}

Одна лендинг-страница рендерит только 5-8 секций. Но Lighthouse показывал:

Eliminate render-blocking resources
  94 CSS resources (~330 KB)
  Potential savings: 5,440 ms

Почему? Turbopack видит все 90 путей import() как достижимые и генерирует <link rel="stylesheet"> для каждого SCSS-модуля. Даже секции, которые никогда не рендерятся на странице, получают свой CSS в <head>. Это подтверждённое, ожидаемое поведение Next.js App Router. CSS не разделяется для dynamic() импортов из Server Components. Мейнтейнеры считают это осознанным компромиссом для предотвращения FOUC. Исправление не планируется.

Всё, что я перепробовал (и почему это не работает)

Я потратил дни, перебирая каждый подход, который смог найти. Вот полный список:

Ловушка inlineCss

Next.js имеет флаг experimental.inlineCss, который заменяет все <link rel="stylesheet"> на инлайн <style> теги. Звучит идеально, правда?

Проблема: это всё или ничего. Нельзя включить по маршруту. Если у вас есть SSR (force-dynamic) страницы, каждый запрос пересобирает весь CSS инлайн. Мы попробовали — наша headless CMS не выдержала нагрузку и упала. Чтобы это работало безопасно, 100% страниц должны быть force-static или ISR. С 20+ SSR-страницами (авторизация, дашборды, динамические страницы) — это масштабная миграция.

Открытие: Turbopack Import Attributes

Копаясь в релиз-нотах Next.js 16.2, я нашёл плохо задокументированную фичу: Turbopack Import Attributes. Она позволяет переопределить встроенный пайплайн бандлера для конкретного импорта с помощью TC39 синтаксиса with {}:

import { cssText, styles } from './hero.module.scss' with {
  turbopackLoader: '@promova/scss-to-inline-loader',
  turbopackAs: '*.js'
}

Это говорит Turbopack: "Не обрабатывай этот импорт как стили. Пропусти его через мой кастомный лоадер и обработай результат как JavaScript."

Это ключевой инсайт. Вместо того чтобы Turbopack генерировал <link rel="stylesheet">, блокирующий рендеринг, наш лоадер компилирует SCSS и экспортирует его как JS-строку. Затем мы инжектим его как инлайн <style> тег прямо в компоненте. Результат: только CSS для секций, которые реально рендерятся, попадает в HTML страницы.

Решение

1. Кастомный Turbopack Loader

~70-строчный Node.js скрипт как yarn workspace пакет (@promova/scss-to-inline-loader):

const { createHash } = require('node:crypto')
const sass = require('sass')
const postcss = require('postcss')
const postcssModules = require('postcss-modules')
const path = require('path')

const SHARED_STYLES = path.resolve(__dirname, '../shared/styles')

// Same prependData as sassOptions.prependData in next.config.ts
const PREPEND_DATA = `
@use "sass:math" as math;
@use "sass:list" as list;
@use "${SHARED_STYLES}/_variables.scss" as *;
@use "${SHARED_STYLES}/_breakpoints.scss" as *;
@use "${SHARED_STYLES}/_mixins.scss" as *;
`

module.exports = function scssToInlineLoader(source) {
  const callback = this.async()
  processScss(source, this.resourcePath)
    .then((js) => callback(null, js))
    .catch((err) => callback(err))
}

async function processScss(source, resourcePath) {
  // 1. Compile SCSS → CSS (with global variables, mixins, breakpoints)
  const sassResult = sass.compileString(PREPEND_DATA + '\n' + source, {
    loadPaths: [path.dirname(resourcePath), SHARED_STYLES],
    style: 'compressed',
    sourceMap: false,
    url: new URL('file://' + resourcePath),
  })

  // 2. Scope class names with postcss-modules (CSS Modules compatible)
  let classNames = {}
  const result = await postcss([
    postcssModules({
      generateScopedName(name, filename) {
        const file = path.basename(filename, path.extname(filename))
          .replace('.module', '')
        const hash = createHash('md5')
          .update(filename + name)
          .digest('base64url')
          .slice(0, 6)
        return `${file}__${name}__${hash}`
      },
      getJSON(_, json) { classNames = json },
    }),
  ]).process(sassResult.css, { from: resourcePath })

  // 3. Export as JS module — same interface as CSS Modules
  return [
    `export const cssText = ${JSON.stringify(result.css)};`,
    `export const styles = ${JSON.stringify(classNames)};`,
    `export default styles;`,
  ].join('\n')
}

Что он делает: styles — та же карта скоупованных классов как в стандартных CSS Modules. cssText — скомпилированный CSS как строка.

2. Компонент InlineStyle

Использует встроенный API React 19 <style href precedence> для автоматической дедупликации:

export function InlineStyle({ css, id }: { css: string; id: string }) {
  return (
    <style href={id} precedence="default">
      {css}
    </style>
  )
}

React 19 гарантирует: одинаковый href → только один <style> в DOM.

3. Миграция по компонентам (~6 строк на секцию)

// BEFORE: Turbopack → <link rel="stylesheet"> (render-blocking)
import styles from './hero_section.module.scss'

// AFTER: Custom loader → JS module → inline <style> (non-blocking)
import { cssText, styles } from './hero_section.module.scss' with {
  turbopackLoader: '@promova/scss-to-inline-loader',
  turbopackAs: '*.js'
}
import { InlineStyle } from '@promova/scss-to-inline-loader/InlineStyle'

export function HeroSection() {
  return (
    <section className={styles.hero}>
      <InlineStyle css={cssText} id="hero-section" />
      {/* ... component JSX, className usage is identical */}
    </section>
  )
}

Файлы .module.scss остаются точно такими же. Никакого переписывания CSS.

Почему это лучше, чем inlineCss: true

Вот критическая разница:

С inlineCss: true страница всё равно получает ВСЕ 94 стиля инлайн. С нашим подходом только CSS, который реально рендерится, попадает в HTML.

Подводный камень Turbopack: нет глобальных правил для .module.scss

Ловушка, в которую я попал: может показаться, что можно добавить правило Turbopack в next.config.ts для глобального применения лоадера:

// ❌ THIS CAUSES A FATAL PANIC
turbopack: {
  rules: {
    '**/components/**/*.module.scss': {
      loaders: ['@promova/scss-to-inline-loader'],
      as: '*.js'
    }
  }
}

Не делайте этого. Встроенный пайплайн CSS-модулей Turbopack перехватывает .module.scss файлы до применения кастомных правил, вызывая:

FATAL PANIC: inner asset should be CSS processable

Атрибуты with {} работают, потому что они инструктируют Turbopack в месте импорта полностью обойти пайплайн CSS-модулей.

Результаты

Мигрировали 127 секционных компонентов в Landing Builder. Продакшн-сборка проверена.

Ограничения

• with {} для каждого импорта — многословно — каждый импорт требует 3 дополнительные строки.
• Только Turbopack — атрибуты with {} не поддерживаются Webpack.
• Хеширование имён классов — наш лоадер использует другой алгоритм хеширования, чем встроенный в Turbopack.
• Размер HTML увеличивается — CSS инлайн в HTML вместо кеширования как отдельных файлов.

Когда это использовать

Эта техника наиболее эффективна, когда:

1. У вас есть registry/barrel паттерн — один файл импортирует много компонентов, но только несколько рендерятся на странице
2. Вы на Turbopack — Import Attributes специфичны для Turbopack
3. Вам нужен контроль по компонентам — не флаг всё-или-ничего
4. Ваш SCSS сложный — переменные, миксины, брейкпоинты, вложенность — всё поддерживается
5. Вы не можете использовать experimental.inlineCss — потому что у вас SSR-страницы или нужен гранулярный контроль

Связанные GitHub Issues

Если вас затронула проблема render-blocking CSS в Next.js App Router — вы не одиноки:

Основная проблема

• #62485 — Render blocking CSS (maintainers: "expected behavior")
• #61066 — Dynamic imports from Server Components are not code-split
• #54935 — Server-side dynamic imports don't split client modules
• #61574 — JS/CSS code splitting doesn't work as documented
• #57634 — Add support for critical CSS inlining with App Router
• #50300 — next/dynamic on server component does not build CSS modules

Фича inlineCss и проблемы

• PR #72195 — experimental: css inlining (the implementation)
• PR #73182 — Don't inline CSS in RSC payload for client navigation
• #75648 — WhatsApp preview broken with inlineCss + Tailwind
• #83612 — Turbopack wrong font URL with inline CSS

Сообщество ищет решения

• Discussion #82894 — How to prevent render-blocking with CSS Modules? (2025)
• Discussion #70526 — Ideas for reducing render-blocking CSS
• Discussion #59814 — Render blocking styles with Tailwind
• Discussion #49691 — How to deal with render-blocking modular CSS
• Discussion #59989 — Critical CSS inlining with App Router
• Discussion #80486 — Is optimizeCss still in use?
• Discussion #85465 — Turbopack plugin API (doesn't exist)

Баги CSS в Turbopack

• #68412 — Incorrect CSS modules load order with external components
• #76464 — Turbopack sometimes strips SCSS imports
• #82497 — SCSS module not loading when not-found.tsx is present
• #88544 — Exporting Sass variables from CSS modules doesn't work with Turbopack

Создано в Promova — платформе для изучения языков, обслуживающей миллионы пользователей.

Next.js патчит глобальный fetch и добавляет кеш-слой, который держит ссылки на response data после того как они должны были быть освобождены. Каждый вызов fetch добавляет память, которая никогда не возвращается GC. В Docker/Kubernetes это приводит к OOM crash каждые несколько часов. Баг существует с Next.js 14 (апрель 2024) и до сих пор не решён в 16.2.x (март 2026). На Vercel проблема не проявляется из-за ephemeral serverless функций.

Как работает нормальный fetch

Request → fetch → got data → response to user → GC cleans up → memory free

Как работает fetch в Next.js

Next.js перехватывает глобальный fetch и оборачивает его своим кеш/трекинг слоем:

Request → Next.js fetch wrapper → creates:
  - Performance entry (speed tracking)    ← not cleaned
  - Request metadata object               ← not cleaned
  - Internal promise wrapper              ← not cleaned
  - Cache lookup entry                    ← not cleaned
  - Response body (for unique URL)        ← not cleaned
→ Response to user
→ GC sees objects are still referenced → doesn't touch them
→ Memory grows indefinitely

Что происходит на продакшне

Self-hosted (Docker/K8s):
  Request 1:      fetch → +100KB → RAM: 100KB
  Request 2:      fetch → +100KB → RAM: 200KB
  Request 1000:   fetch → +100KB → RAM: 100MB
  Request 50,000: fetch → +100KB → RAM: 5GB → OOM Kill 💀
  → Kubernetes restarts the pod → cycle repeats

Vercel (Serverless):
  Request 1: [start] → fetch → +100KB → [process dies] → 0 KB ✅
  Request 2: [start] → fetch → +100KB → [process dies] → 0 KB ✅
  → Memory never accumulates

Затронутые версии

Next.js — все версии с App Router

Node.js

Тестировали на Node.js 20, 22, 24, 25 — течёт на всех.

Что не работает

Что работает (workarounds)

Ограничение workaround с axios

Свои API-запросы можно заменить на axios. Но Next.js внутренне использует пропатченный fetch для:

• ISR (Incremental Static Regeneration)
• revalidatePath / revalidateTag
• Server Components data fetching с дедупликацией
• use cache (Next.js 16)

То есть даже без единого fetch в своём коде — Next.js всё равно использует его под капотом.

Почему Vercel не фиксит

Бизнес-логика

Vercel — компания, которая зарабатывает на хостинге Next.js. На их платформе проблема не проявляется (serverless = ephemeral). Баг затрагивает только self-hosted (Docker, K8s, VPS) — тех, кто не платит Vercel.

Официальная позиция

Tim Neutkens (мейнтейнер Vercel) провёл анализ и заявил что это проблема undici (Node.js fetch библиотека), а не Next.js. Issue #90433 закрыли. При том что:

• axios и node-fetch на том же Node.js работают без утечек
• Утечка появляется только когда fetch проходит через Next.js обёртку
• Баг открыт 2 года без фикса

Приоритеты

За эти 2 года команда Next.js выпустила:

• Turbopack (2-5x быстрее билды) — маркетинговое преимущество
• Cache Components / use cache — уменьшает нагрузку на серверы Vercel
• proxy.ts вместо middleware — упрощает edge-деплой на Vercel
• DevTools MCP — AI-хайп

Memory leak в self-hosted? Не в приоритетах.

Решение: AWS Lambda (SST + OpenNext)

Что это

OpenNext — open-source адаптер, который превращает Next.js build в формат для AWS Lambda. SST — фреймворк, автоматизирующий инфраструктуру.

Архитектура

Next.js build
  → OpenNext
    → AWS Lambda (SSR, API routes)
    → S3 (static, assets)
    → CloudFront (CDN)
    → SQS + DynamoDB (ISR revalidation)

Почему это решает memory leak

Lambda функция обрабатывает запросы и recycled через 5-15 минут неактивности. Память не успевает накопиться.

Деплой

npx sst@latest init
npx sst deploy --stage production

Сравнение

Нюансы Lambda

• Cold starts — первый запрос медленнее (~200-500ms)
• Безопасность — включить OAC (Origin Access Control), иначе Lambda URL публичный
• OpenNext — community проект, не официальный Vercel. Новые фичи Next.js могут ломаться
• Wallet attack — при DDoS автоскейлинг Lambda может привести к большому счёту

Почему исправить нереально

1. Архитектурная проблема

Утечка — не случайный баг, а следствие дизайн-решения: Next.js перехватывает глобальный fetch и добавляет кеш/трекинг поверх. Чтобы пофиксить — нужно переделать как App Router взаимодействует с fetch. Это затрагивает ISR, revalidation, data cache, request deduplication — ядро фреймворка.

2. Конфликт интересов

Vercel не мотивирован фиксить то, что не затрагивает их платформу. Self-hosted конкурирует с их бизнесом. Чем больше проблем в self-hosted — тем больше людей мигрируют на Vercel.

3. Blame shifting

Официальная позиция — "это undici, не мы". Пока она не изменится — над фиксом работать не будут.

4. Нет community fix

AGPL-3.0 лицензия Next.js позволяет форки, но кодовая база огромна и тесно связана с инфраструктурой Vercel. Community PR с фиксом fetch обёртки потребовал бы глубокого понимания внутренней архитектуры и одобрения мейнтейнеров — которые уже закрыли issue.

Выводы

1. Если на Vercel — проблемы нет, ничего делать не нужно
2. Если self-hosted и нужен serverless — SST + OpenNext на AWS Lambda
3. Если self-hosted Docker — заменить fetch на axios где возможно, мониторить RAM, настроить автоматический рестарт подов
4. Если начинаешь новый проект — рассмотреть SvelteKit или Nuxt как альтернативу без этой проблемы

Источники

• Issue #64212 — Memory Leak with global fetch (April 2024)
• Issue #68578 — Possible memory leak in Fetch API (August 2024)
• Issue #85914 — Memory Leak with fetch + standalone (November 2025)
• Issue #90433 — OOM in 16.0.10 (February 2026)
• Discussion #88603 — OOM in Docker/K8s (January 2026)
• Discussion #88078 — cacheMaxMemorySize behavior
• OpenNext
• SST — Next.js on AWS
• Secret knowledge to self-host Next.js
• Next.js Memory Usage Guide