Extension taxonomy: карта расширений

1. Когда prompt перерастает сам себя

В начале работы с Claude Code обычно хватает обычного prompt, CLAUDE.md и аккуратной сессии — это нормальный и, более того, правильный старт. Но со временем появляется странный эффект: работать хуже вы не стали, просто всё чаще повторяете одно и то же. Каждый issue в Commerce OS разбираете одинаково: план, проверка scope, TASK_SPEC.md, verification. Те же ограничения вручную.

И в этот момент проблема уже не в модели и не в вашей памяти. Workflow дозрел до отдельного артефакта.

Представьте типичную ситуацию в Commerce OS. Вам регулярно прилетают задачи вроде «неправильная сортировка refund-запросов», «дубли в пагинации заказов», «медленный endpoint для dashboard-метрик». На каждую — один ритуал: читаете issue, фиксируете цель, scope, non-goals, способ проверки, риски. Вот как выглядит этот симптом в миниатюре:

Прочитай issue.
Выдели цель, scope, non-goals, критерии приёмки и план проверки.
Не меняй код.
Сначала покажи кандидатов на affected files и риски.

Один раз — это prompt. Два-три раза в неделю — кандидат в reusable workflow. Здесь и нужна extension taxonomy — карта механизмов расширения. Она нужна не ради красивых слов, а чтобы перестать чинить разные проблемы одним молотком. Молоток штука хорошая. Но не когда им лечат Wi‑Fi.

Очень важно зафиксировать главную мысль этой лекции. Базовый workflow никуда не исчезает: Task spec, контекст, evidence, Git, diff, review остаются вашим путём. Расширения не заменяют дисциплину — делают её повторяемой, переносимой и менее утомительной.

2. Одна карта вместо зоопарка возможностей

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

Точные названия, поля конфигов и команды в Claude Code меняются от версии к версии — но сами категории и задачи, которые они решают, остаются стабильными.

Эту таблицу удобно дополнить ещё и короткой схемой выбора. Здравый смысл она не заменяет, но отлично спасает от синдрома «давайте сразу поставим всё».

flowchart TD
    A[Появилась workflow-боль] --> B{Это разовая задача?}
    B -- Да --> P[prompt]
    B -- Нет --> C{Это постоянное правило?}
    C -- Да --> D{Для всего проекта?}
    D -- Да --> CM[CLAUDE.md]
    D -- Нет --> R[rule]
    C -- Нет --> E{Это повторяемая процедура?}
    E -- Да --> S[skill]
    E -- Нет --> F{Нужны внешние данные?}
    F -- Да --> M[MCP]
    F -- Нет --> G{Нужно автосрабатывание на событие?}
    G -- Да --> H[hook]
    G -- Нет --> I{Нужен отдельный контекст исследования?}
    I -- Да --> SA[subagent]
    I -- Нет --> J{Нужно раздать решение команде?}
    J -- Да --> PL[plugin]

Здесь важно видеть не только «что выбрать», но и «чего не выбирать». Если проблема в том, что Claude забывает команду запуска проекта, это не повод заводить skill или plugin. Если правило касается только каталога payments/, не надо раздувать весь CLAUDE.md. Если нужные данные уже есть в кодовой базе, MCP будет лишним. Очень часто лучший инженерный выбор — вообще не добавлять новый слой.

И да, для новичков это особенно важно. Когда открываете тему расширений, руки сами тянутся сделать красиво: rules, skills, agents, hooks, MCP, plugin, а если совсем войти во вкус — ещё обложку для README и немного драматической музыки. Но хороший workflow растёт постепенно. Иначе вместо полезного набора инструментов вы получите маленький зоопарк, в котором никто не понимает, кто за что отвечает.

3. prompt, CLAUDE.md и rule: типичная путаница

Именно здесь чаще всего возникает путаница. Кажется, будто prompt, CLAUDE.md и rule отличаются только местом, где лежит текст. На самом деле разница у них не географическая, а инженерная: у них разный срок жизни, разный scope и разная причина появления. Если это не различать, очень быстро получается либо раздутый CLAUDE.md, либо десять локальных правил вместо одной нормальной проектной инструкции.

Удобно сравнить их напрямую:

Посмотрите на такой фрагмент CLAUDE.md для Commerce OS:

## Команды проекта
- backend: ./gradlew test
- frontend: npm run test

## Общие правила
- Сначала показывай план для нетривиальных изменений.
- Не меняй public API без явного согласования.

Это хороший кандидат для CLAUDE.md, потому что правило относится ко всему проекту. Неважно, работаете ли вы с catalog/, orders/ или support/, — общая дисциплина одинакова.

А теперь другой случай:

# Правило для payments/**
- Перед изменениями сначала покажи план.
- Не меняй refund logic без regression evidence.
- Не трогай смежные файлы «заодно».

Это уже не общее правило проекта. Оно нужно только в чувствительной зоне. Если такое правило положить в общий CLAUDE.md, оно начнёт шуметь везде, даже там, где не нужно. А если, наоборот, правило для всего проекта спрятать в локальный rule, его просто не увидят в нужный момент.

Prompt здесь живёт совсем по другим законам. Он хорош, когда задача единичная и контекст сильно зависит от текущего вопроса. Например, вы хотите один раз попросить:

Проверь, почему /api/orders иногда возвращает дубли.
Сначала собери evidence и список затронутых файлов.
Код пока не меняй.

Это не проектное правило и не повторяемая процедура на каждый день. Это конкретный запрос под конкретную ситуацию.

Если совсем по-простому, prompt — это текущая реплика, CLAUDE.md — общий устав проекта, а rule — локальная табличка на двери конкретной комнаты. У каждой из этих вещей своя работа. Попытка заменить одну другой почти всегда заканчивается тем, что инструкции либо забываются, либо начинают слишком громко звучать там, где не нужны.

4. skill, subagent, MCP, hook, plugin

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

Вот как эта карта обычно выглядит в структуре Workflow Kit:

workflow-kit/
├── .claude/
│   ├── CLAUDE.md
│   ├── rules/
│   ├── skills/
│   ├── agents/
│   ├── hooks/
│   └── mcp/
└── README.md

Эта структура важна не потому, что «так красиво». Она показывает, что Workflow Kit — это отдельный инженерный слой, а не секретный чулан внутри Commerce OS. Commerce OS — продуктовый код. Workflow Kit — надстройка, которая помогает с ним работать.

Начнём со skill. Это механизм для повторяемой процедуры. Если вы много раз проходите один и тот же workflow — например, превращаете issue в TASK_SPEC.md, — значит, перед вами уже не «удачный prompt», а почти готовый skill. У него есть триггер, вход, ограничения и ожидаемый результат. Skill отвечает не на вопрос «что мне сказать модели», а на вопрос «как воспроизводимо провести процедуру».

Subagent на этой карте нужен нам пока только как идея отдельного окна контекста. Не как «цифровой коллега, который всё сделает сам», а как способ сказать: «Эту тяжёлую исследовательскую работу лучше вынести отдельно, чтобы не засорять основную сессию». Подробно настраивать роли, права и контракты результата мы будем позже. Сегодня важно лишь одно: subagent — это не про правила проекта и не про внешние данные, а про изоляцию investigation.

MCP отвечает на совсем другой вопрос: как дать Claude доступ к внешним данным или действиям. Это история про issue tracker, мониторинг, документацию, базу данных, браузерные действия. Очень важная граница здесь такая: если информация уже находится в репозитории, MCP не нужен. Не надо тянуть внешний протокол ради того, что спокойно читается из кода и конфигов. MCP — это мост наружу, а не новый способ прочитать локальный файл.

Hook — это реакция на событие. Не правило, не процедура и не внешний источник данных. У hook другой характер: что должно произойти автоматически, когда срабатывает определённое событие. Например, после редактирования стоит прогнать форматирование. Или перед опасным действием заблокировать путь. Hook особенно легко переусердствовать. Если skill — это «сделай процедуру повторяемой», то hook — это «сделай реакцию автоматической». А автоматизация без аккуратных границ очень быстро превращается в небольшую, но надоедливую катастрофу.

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

5. Выбор механизма без гадания и лишнего энтузиазма

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

Ниже — несколько типичных ситуаций из связки Commerce OS + Workflow Kit:

Заметьте, чего в таблице нет. Нет «важная вещь — значит plugin». Нет «хочется автоматизации — значит hook». Нет «звучит солидно — подключим MCP». Очень часто правильный ответ выглядит скромно: решается через CLAUDE.md — не заводите rule; хватает rule — не делайте plugin; повторяемость не доказана — не спешите со skill.

Такие решения полезно фиксировать письменно — например, в README Workflow Kit или рядом с артефактом. Вот короткий формат, который реально помогает:

# Почему появился rule для payments/**

Проблема: Claude предлагал слишком широкие изменения рядом с refund logic.
Решение: отдельный scoped rule только для payments/**.
Почему не CLAUDE.md: ограничение не касается других модулей проекта.

Это кажется мелочью — но именно такие заметки превращают «набор файлов в .claude/» в понятную инженерную систему. Через месяц уже не вспомнить, почему правило живёт именно здесь. А короткое обоснование снижает шансы на хаос и священные войны в духе «давайте перенесём всё в одно место».

Когда у вас перед глазами есть эта карта, Claude Code перестаёт быть коробкой с загадочными фичами. Вы видите набор ответов на workflow-вопросы: где хватит обычного prompt, где нужен стабильный CLAUDE.md, где поможет локальный rule, а где лучше вообще ничего не добавлять. С этого и начинается взрослая работа с расширениями: не «что бы ещё включить», а «какую конкретную боль я сейчас решаю».