Раздел 8 — Кастомные слэш-команды, навыки, режим плана и итеративная доводка

Что покрывает этот раздел

Расширение Claude Code через кастомные слэш-команды и агентные навыки, выбор между режимом плана и прямым выполнением (и роль субагента Explore в этом), а также техники итеративной доводки. Sample Question 4 проверяет, где должна жить общая слэш-команда /review; Sample Question 5 проверяет выбор режима плана для перестройки монолита в микросервисы.

Исходный материал (из официального руководства)

3.2 Слэш-команды и навыки. Проектные команды в .claude/commands/ (общие через систему контроля версий) против пользовательских команд в ~/.claude/commands/ (личные). Навыки в .claude/skills/<name>/SKILL.md с YAML-фронтматтером, поддерживающим context: fork, allowed-tools, argument-hint. context: fork запускает навык в изолированном контексте субагента, чтобы многословный вывод не загрязнял основной диалог. Личная кастомизация: варианты в ~/.claude/skills/ с другим именем, чтобы не затрагивать товарищей по команде. Навыки — это специализированные под задачу инструкции по запросу; CLAUDE.md — это всегда загружаемые универсальные стандарты.

3.4 Режим плана против прямого выполнения. Режим плана нужен для сложных задач с масштабными изменениями, несколькими допустимыми подходами, архитектурными решениями, правками во многих файлах. Прямое выполнение — для простых, чётко ограниченных изменений (одна проверка валидации, правка в одном файле с понятным стек-трейсом). Режим плана позволяет безопасно исследовать прежде, чем коммититься к решению. Субагент Explore изолирует многословное исследование и возвращает сводки. Типичный паттерн: план для исследования, затем прямое выполнение для применения.

3.5 Итеративная доводка. Конкретные примеры ввода/вывода лучше прозы. Итерация на тестах: сначала тесты, затем итерации по падениям. Паттерн интервью: попросить Claude задать уточняющие вопросы в незнакомых доменах. Конкретные тестовые случаи для граничных условий (например, null в миграциях). Связанные проблемы объединяйте в одно сообщение; независимые — выполняйте последовательно.

Четыре примитива кастомизации

Claude Code предоставляет четыре механизма, подключающихся к разным частям агентного цикла. Знание того, к какому из них обращаться, — почти гарантированная цель на экзамене.

Anthropic объединила кастомные слэш-команды с навыками в конце 2025 года: файл по пути .claude/commands/deploy.md и навык по пути .claude/skills/deploy/SKILL.md оба создают /deploy и ведут себя идентично. Навыки — рекомендуемая форма, потому что они добавляют вспомогательные файлы, контроль вызова, динамическую инъекцию контекста и исполнение в субагенте (документация по слэш-командам).

Кастомные слэш-команды

Проектная и пользовательская область видимости

• .claude/commands/ — проектная область, под контролем версий, общекомандные рабочие процессы (/review, /security-review, /migrate-route).
• ~/.claude/commands/ — пользовательская область, только личные шорткаты (/scratch, /jira-link).

Sample Question 4 опирается именно на это: команда /review, которая «должна быть доступна каждому разработчику, когда он клонирует или подтягивает репозиторий», помещается в .claude/commands/ — не в ~/.claude/commands/, не в CLAUDE.md и не в вымышленный .claude/config.json.

Структура файла и фронтматтер

Команда — это markdown-файл с опциональным YAML-фронтматтером:

---
description: Run the team code-review checklist on the current diff
argument-hint: [path-or-PR]
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
model: sonnet
---

Review the changes in $ARGUMENTS using our checklist:

## Diff
!`git diff HEAD`

## Style guide
@docs/CODE_REVIEW.md

For each finding, output: severity, file:line, problem, suggested fix.

Ключевые поля фронтматтера (справочник):

Все поля опциональны.

Обработка аргументов, выполнение bash, ссылки на файлы

Внутри тела markdown работают три механизма подстановки:

• $ARGUMENTS — полная строка аргументов. $ARGUMENTS[N] индексирует по позиции; $N — краткая форма.
• !`cmd` — выполняет bash-команду в момент загрузки и подставляет её stdout (например, !`git diff HEAD`).
• @path — подставляет содержимое файла; @$0 подставляет файл, путь к которому задан первым аргументом.

Заметка к экзамену: старая документация использовала $1 для первого аргумента. В текущей документации нумерация с нуля ($0, $1, $2). Узнавайте оба варианта; предпочитайте $ARGUMENTS, когда порядок не важен.

Пример: /review

Команда /review проектной области для Sample Question 4 — закоммитьте этот файл в .claude/commands/review.md, и каждый член команды получит /review после следующего pull:

---
description: Run our PR review checklist on a diff or PR
argument-hint: [pr-number-or-path]
allowed-tools: Read, Grep, Glob, Bash(gh pr view:*), Bash(git diff:*)
---

## Diff
!`git diff origin/main...HEAD`

## Checklist
@.claude/docs/review-checklist.md

Apply each checklist item. For every finding, report severity
(block/major/nit), file:line, the issue, and a concrete fix.
End with a one-paragraph overall verdict.

Агентные навыки

Структура файлов

.claude/skills/pr-summary/
  SKILL.md          # required: frontmatter + instructions
  checklist.md      # optional supporting files
  example-good.md

Навыки обнаруживаются на четырёх уровнях — корпоративном, пользовательском (~/.claude/skills/), проектном (.claude/skills/) и плагинном. Корпоративный перекрывает пользовательский, пользовательский перекрывает проектный; плагинные навыки живут в пространстве имён plugin-name:skill-name (документация по навыкам).

Справочник по фронтматтеру

Помимо полей, общих с командами, у навыков добавляются:

context: fork — что это и когда применять

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

---
name: pr-summary
description: Summarize a PR's changes and risk surface
context: fork
agent: Explore
allowed-tools: Bash(gh *), Read, Grep, Glob
---

Summarize PR $ARGUMENTS. Read the diff with `gh pr diff $ARGUMENTS`,
group changes by subsystem, call out risky touches (auth, billing,
migrations), and end with a 3-bullet reviewer checklist.

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

Паттерн личного варианта

Чтобы кастомизировать общий навык, не затронув товарищей по команде, скопируйте его под другим именем в ~/.claude/skills/ (например, pr-summary-detailed/). Это позволяет избежать антипаттерна «я отредактировал общий навык, и теперь у всех мой вариант». Тот же трюк с переименованием работает для слэш-команд в ~/.claude/commands/.

Матрица решений: навыки против CLAUDE.md

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

Режим плана против прямого выполнения

Как войти в режим плана

Режим плана — один из шести режимов разрешений; Claude читает файлы и выполняет команды только для чтения, но не может править исходный код (документация по режимам разрешений). Четыре точки входа:

1. Циклический переключатель в сессии через Shift+Tab: default → acceptEdits → plan.
2. При запуске: claude --permission-mode plan (работает и с -p для headless-режима).
3. По умолчанию для проекта: permissions.defaultMode: "plan" в .claude/settings.json.
4. На один промпт: префикс /plan в сообщении.

Когда план готов, Claude предлагает (a) утвердить и переключиться в авто, (b) утвердить и просматривать каждую правку либо (c) продолжать планировать. Ctrl+G открывает план в редакторе; Shift+Tab выходит без утверждения.

Когда режим плана окупается

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

• Изменение охватывает много файлов или архитектурных швов (перестройка в микросервисы, миграция библиотеки, затрагивающая 45+ файлов).
• Несколько допустимых подходов с реальными компромиссами (Redis против in-memory против файлового кэша; вебхуки против опроса).
• Объём неизвестен — вопрос «насколько большое?», а не «реализуй вот это».
• Высокий радиус поражения: миграции схем, рефакторинги аутентификации, межкомандные контракты.

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

Когда правильное прямое выполнение

• Однофайловый баг с чётким стек-трейсом и очевидным исправлением.
• Одна проверка валидации, одна строка лога, один feature flag.
• Механический рефакторинг с известной целью (переименование во многих файлах — используйте acceptEdits).
• У вас уже есть план с предыдущего хода.

У режима плана есть накладные расходы — дополнительные токены на исследование для Claude, время на просмотр плана у разработчика. Не платите их на изменениях из трёх строк.

Субагент Explore для многословного исследования

Даже вне режима плана делегируйте фазу исследования встроенному субагенту Explore — только чтение, на Haiku, с доступом к Glob/Grep/Read/Bash, но без Write/Edit. Каждый вызов работает в собственном контекстном окне и возвращает только сводку (документация по субагентам).

Используйте Explore (напрямую или через навык с context: fork и agent: Explore) для вопросов «где определён X?» / «как работает Y?», для многофазных задач, которые сожгут контекстный бюджет на исследовании, и для широких поисков, чей сырой вывод вы не будете перечитывать. Указывайте тщательность: quick, medium или very thorough.

Совмещённый паттерн: сначала план, потом выполнение

Рекомендуемый рабочий процесс для нетривиальной работы — explore → plan → execute → commit (лучшие практики): делегируйте обзор Explore, попросите Claude написать план, просмотрите/отредактируйте его через Ctrl+G, утвердите в acceptEdits, затем коммитьте. Режим плана для исследования, прямое выполнение — для правок.

Плейбук итеративной доводки

1. Дайте примеры ввода/вывода

Когда узким местом является неоднозначность прозы (извлечение, преобразование, форматирование), давайте 2–3 конкретные пары ввод/вывод вместо новых прилагательных. Claude обобщает от примеров надёжнее, чем от прозы вроде «дружелюбно, но профессионально». Примеры заодно служат регрессионными случаями.

2. Итерация на тестах

Тесты — это однозначный сигнал верификации. Цикл: попросите Claude написать набор тестов, покрывающий happy path, граничные случаи и бюджеты производительности до того, как появится реализация; запустите его и поделитесь падениями; попросите Claude реализовать минимум, нужный для того, чтобы упавший тест стал зелёным; повторяйте до зелёного; рефакторите, опираясь на набор тестов как на страховочную сетку. Это конкретное воплощение принципа «дайте Claude способ проверить свою работу».

3. Паттерн интервью

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

4. Связанные правки объединяйте, независимые — выполняйте последовательно

Когда всплывает несколько проблем, решите, взаимосвязаны ли они:

• Связанные — правка в одном месте меняет правильный ответ в другом (смена формата даты влияет на парсинг, отображение, записи в БД). Сложите все в одно подробное сообщение, чтобы Claude рассуждал целостно.
• Независимые — опечатка в хелпере, отсутствующая null-проверка в другом месте. Чините последовательно, по одной за ход — небольшие диффы, свежий контекст, легко атрибутируемые падения.

Для одного падающего граничного случая (null в миграции) дайте конкретный ввод/ожидаемый вывод именно для этого случая — не переписывайте весь скрипт.

Ключевые акценты для экзамена

• Общекомандные команды живут в .claude/commands/<name>.md в репозитории. Не в ~/.claude/commands/, не в CLAUDE.md, не в вымышленном config.json.
• Навыки — по запросу, CLAUDE.md — всегда загружается. Постоянные стандарты идут в CLAUDE.md; специализированные под задачу рабочие процессы — в навыки.
• context: fork изолирует многословный или исследовательский вывод навыка в субагенте; сочетайте с agent: Explore для исследования только на чтение.
• allowed-tools предодобряет список инструментов, пока навык активен; он не блокирует другие инструменты — правила разрешений всё равно применяются.
• argument-hint управляет автодополнением; $ARGUMENTS/$N подставляют фактические значения в тело промпта.
• Режим плана активируется циклом Shift+Tab, --permission-mode plan, префиксом /plan или defaultMode: "plan". Он только для чтения.
• Выбирайте режим плана для архитектурной / многофайловой / многовариантной работы; выбирайте прямое выполнение для однофайловых, чётко ограниченных изменений.
• Субагент Explore встроен, работает на Haiku, только для чтения, возвращает сводки — используйте его, чтобы держать исследование вне основного контекста.
• Итерация: примеры ввода/вывода лучше прозы; тесты — самая рычажная петля обратной связи; интервью в незнакомых доменах; связанные правки объединяйте, независимые — выполняйте последовательно.

Ссылки

• Слэш-команды — https://docs.anthropic.com/en/docs/claude-code/slash-commands
• Навыки — https://docs.anthropic.com/en/docs/claude-code/skills
• Режимы разрешений (режим плана) — https://docs.anthropic.com/en/docs/claude-code/permission-modes
• Субагенты (Explore) — https://docs.anthropic.com/en/docs/claude-code/sub-agents
• Хуки — https://docs.anthropic.com/en/docs/claude-code/hooks
• Лучшие практики — https://docs.anthropic.com/en/docs/claude-code/best-practices
• Расширение Claude Code — https://docs.anthropic.com/en/docs/claude-code/features-overview
• Стандарт Open Agent Skills — https://agentskills.io/
• Репозиторий Claude Code — https://github.com/anthropics/claude-code
• Официальные плагины — https://github.com/anthropics/claude-plugins-official