Архитектура модов в Claude Code: расширение возможностей терминального ИИ-агента

Работа с терминальными ИИ-агентами долгое время напоминала использование черного ящика. Разработчик мог задать общие инструкции в конфигурационном файле, но внутренний цикл решений оставался закрытым. Если требовалось перехватить вызов команды, скрыть токены или добавить правила валидации, приходилось оборачивать утилиту во внешние скрипты либо контролировать каждый шаг вручную.

С выходом релиза Claude Code 2.1.28.7 компания Anthropic представила систему модов (Claude Code Mods). Это модульная архитектура на базе TypeScript и JavaScript, позволяющая управлять агентом на любом этапе жизненного цикла без форка основного ядра.

Четыре вектора контроля: как моды управляют рантаймом

В отличие от пассивных хуков, моды предоставляют доступ к ключевым точкам исполнения агента:

1. Модификация промптов (prompt:before): мод может динамически внедрять контекст проекта или правила кодстайла перед отправкой запроса к модели.
2. Перехват вызова инструментов (tool:before): анализ аргументов команд и блокировка небезопасных операций до обращения к операционной системе.
3. Автоматизация подтверждений: программное одобрение рутинных действий без лишних всплывающих окон.
4. Фильтрация вывода и кастомный UI: маскирование секретов и вывод виджетов в консоли (например, индикатора расхода контекста Token Weather или анализатора рисков Blast Radius).

Создание защитного мода: от манифеста к перехвату команд

Соберем защитный мод safe-guard, который проверяет команды терминала на наличие опасных паттернов (rm -rf, drop table, git reset --hard) и добавляет правила типизации в промпты.

Сначала в директории .claude/mods/safe-guard/ создается конфигурационный манифест mod.json:

{
  "name": "safe-guard",
  "version": "1.0.0",
  "description": "Перехват деструктивных команд и внедрение корпоративных правил",
  "entrypoint": "index.ts",
  "hooks": [
    "prompt:before",
    "tool:before"
  ]
}

В файле index.ts реализуется логика перехватчиков жизненного цикла:

import { ModContext, ToolExecutionEvent, PromptEvent } from '@anthropic-ai/claude-code-mod-types';

export default function registerMod(context: ModContext) {
  // Добавление проектных стандартов в системный контекст
  context.on('prompt:before', async (event: PromptEvent) => {
    event.systemPrompt += '\n[Правило]: используй строгую типизацию TypeScript.';
  });

  // Защита от опасных shell-операций
  context.on('tool:before', async (event: ToolExecutionEvent) => {
    if (event.toolName === 'bash') {
      const command = String(event.parameters.command || '');
      const dangerousPatterns = [/rm\s+-rf/u, /drop\s+table/iu, /git\s+reset\s+--hard/u];

      for (const pattern of dangerousPatterns) {
        if (pattern.test(command)) {
          event.preventExecution();
          const confirmed = await context.ui.confirm({
            title: 'Предупреждение Blast Radius',
            message: `Попытка запуска опасной команды: "${command}". Разрешить?`,
          });
          if (!confirmed) {
            throw new Error('Команда заблокирована пользователем.');
          }
        }
      }
    }
  });
}

После сохранения файлов расширение активируется при запуске сессии:

claude --mod ./claude/mods/safe-guard

Статус подключенных модулей и активных хуков внутри сессии проверяется командой /mods status.

Эксплуатационные риски и границы применимости

Поскольку моды исполняются в том же процессе, что и агент, они обладают правами текущего пользователя ОС. Установка непроверенных модов несет прямые риски, поэтому в корпоративных тарифах Enterprise предусмотрена их централизованная блокировка. Создание модов оправдано в командных проектах со строгими регламентами безопасности, тогда как для простых правок кода достаточно базового файла CLAUDE.md.