Claude Code: разработка, автоматизация и вайб-кодинг

Знакомство с Claude Code и настройка CLI

Обычный диалог с нейросетью в браузере напоминает консультацию через стекло: вы копируете фрагмент кода, описываете ошибку, получаете совет, вручную вставляете его в редактор и надеетесь, что ничего не сломалось. Но что, если модель перестанет быть советчиком и станет полноценным напарником, который сам читает репозиторий, правит файлы, запускает сборщик и исправляет собственные ошибки до тех пор, пока тесты не станут зелёными? Именно для этого компания Anthropic создала Claude Code — агентный инструмент командной строки (CLI), превращающий терминал в автономную рабочую среду.

В этой главе мы разберёмся, как устроен Claude Code, чем агентная парадигма отличается от привычных автодополнений и как развернуть CLI-клиент на своей машине за считаные минуты.

Парадигма вайб-кодинга и терминальный агент

Термин вайб-кодинг (vibe coding) описывает стиль разработки, в котором инженер формулирует замысел на естественном языке и управляет архитектурным вектором, а рутинную генерацию кода, рефакторинг и исправление синтаксических ошибок берёт на себя искусственный интеллект.

Claude Code выводит эту концепцию на новый уровень благодаря переходу от пассивного чата к агентному циклу (agentic loop).

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

В отличие от расширений для IDE (например, GitHub Copilot), которые в основном фокусируются на инлайн-дополнении текущей строки или функции, Claude Code работает на уровне всего проекта:

Параметр	Веб-чат (Claude.ai / ChatGPT)	Расширение для IDE	Claude Code CLI
Точка входа	Браузер	Редактор кода (VS Code, JetBrains)	Терминал операционной системы
Доступ к файлам	Только то, что скопировано вручную	Открытые вкладки и выделенные фрагменты	Вся файловая структура репозитория
Исполнение команд	Невозможно	Ограничено контекстом редактора	Прямой запуск bash-команд, тестов, линтеров
Автономность	Нулевая (генерация текста)	Низкая (подсказки при наборе)	Высокая (самостоятельный поиск и правка)

Когда вы даёте команду Claude Code, модель под капотом использует специализированные вызовы инструментов (tool use): она может запустить grep для поиска нужного метода, открыть файл, переписать функцию, запустить npm test или pytest, увидеть трассировку стека ошибки и повторить цикл исправлений без вашего вмешательства.

Системные требования и подготовка окружения

Claude Code распространяется как пакет для среды Node.js. Перед установкой необходимо убедиться, что ваша система соответствует базовым требованиям:

Операционная система: macOS (10.15+), Linux (Ubuntu 20.04+, Debian, Fedora, Arch) или Windows через WSL2 (Windows Subsystem for Linux).
Node.js: версия 18.0.0 или выше (рекомендуется LTS-версия 20.x или 22.x).
Менеджер пакетов: npm, pnpm или yarn.
Git: установлен и инициализирован в проекте.

Проверьте наличие и версии установленных компонентов в вашем терминале:

node -v
npm -v
git --version

Если Node.js не установлен, рекомендуется использовать менеджер версий nvm (Node Version Manager) или fnm (Fast Node Manager). Это предотвратит проблемы с правами доступа (EACCES) при глобальной установке npm-пакетов:

# Установка nvm и последней LTS-версии Node.js (macOS / Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts

Установка Claude Code

Установка выполняется одной командой через глобальный флаг npm:

npm install -g @anthropic-ai/claude-code

После завершения инсталляции проверьте доступность утилиты:

claude --version

Если команда возвращает номер версии (например, 0.2.x), инструмент готов к первоначальной конфигурации и авторизации.

Аутентификация и настройка API

Для работы Claude Code требуется связь с серверами Anthropic. Поддерживаются два основных способа авторизации: через персональный ключ Anthropic Console API или через корпоративную подписку Claude Pro/Max (OAuth).

Вариант 1. Авторизация через браузер (OAuth)

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

cd ~/projects/my-app
claude

При первом запуске Claude Code выведет в терминал приветственное сообщение и предложит войти через браузер:

Терминал сгенерирует уникальную ссылку и одноразовый код.
Нажмите Enter или откройте ссылку в браузере.
Войдите в свой аккаунт Anthropic и подтвердите предоставление доступа CLI-клиенту.
После успешного подтверждения токен аутентификации сохранится в конфигурационном каталоге вашей системы (~/.claude/ или системном хранилище ключей).

Вариант 2. Экспорт ключа API (ANTHROPIC_API_KEY)

Если вы используете API-ключ напрямую из консоли разработчика Anthropic Console:

Перейдите на портал Anthropic Console.
Откройте раздел API Keys и создайте новый ключ (например, с именем claude-code-cli).
Экспортируйте переменную окружения в текущую сессию терминала:

export ANTHROPIC_API_KEY="sk-ant-api03-..."

Чтобы не вводить ключ при каждом открытии терминала, добавьте строку экспорта в конфигурационный файл вашей оболочки (~/.zshrc для Zsh на macOS или ~/.bashrc для Bash на Linux):

echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.zshrc
source ~/.zshrc

Первый запуск и базовая интерактивная сессия

Claude Code оптимизирован для работы внутри конкретных проектов. Перейдите в корень любого существующего репозитория и вызовите команду:

cd ~/my-project
claude

Вы попадете в интерактивный REPL-интерфейс Claude Code. В нижней части экрана появится поле ввода с характерным приглашением.

Попробуйте выполнить первый ознакомительный запрос:

> Опиши структуру этого проекта и найди главную точку входа

В ответ Claude Code выполнит несколько параллельных операций:

Просканирует дерево файлов (исключая node_modules, .git и другие папки из .gitignore).
Прочитает конфигурационные файлы (package.json, Cargo.toml, pyproject.toml или go.mod).
Сформирует краткую архитектурную сводку с указанием ключевых модулей.

Чтобы выйти из сессии, введите /exit, exit или нажмите сочетание клавиш Ctrl + C.

Для выполнения разовых быстрых команд без входа в интерактивный режим можно передавать запрос напрямую аргументом флага -p (print mode):

claude -p "Проверь синтаксис в файле src/index.ts и покажи потенциальные уязвимости"

В таком режиме инструмент выведет ответ в стандартный поток вывода (stdout) и сразу вернет управление терминалу, что делает его удобным для интеграции в CI/CD и скрипты автоматизации.

Итоги

Мы установили Claude Code, связали его с аккаунтом через API-ключ и выполнили первый исследовательский запрос к кодовой базе. Теперь инструмент готов к глубокой интеграции в процессы разработки.

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

Управление правами доступа и навигация по файлам

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

Автономный агент силён именно тем, что может читать файлы, запускать тесты и вносить правки без постоянного участия человека. Чтобы эта автономия не превратилась в аварийную ситуацию, в Claude Code заложена многоуровневая система разрешений и экономная модель навигации по кодовой базе.

Архитектура безопасности: как Claude Code исполняет команды

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

Все встроенные инструменты CLI делятся на две категории по степени потенциального риска:

Инструменты чтения и исследования: View (просмотр содержимого файлов), GlobTool (поиск по маскам путей), GrepTool (поиск текста по регулярным выражениям). Эти операции безопасны для файловой системы: они не меняют состояние проекта и по умолчанию требуют минимум подтверждений.
Инструменты модификации и исполнения: FileEdit (запись и правка файлов) и Bash (произвольное выполнение команд shell). Любой запуск bash-скрипта, миграции, установка пакета или удаление файла могут привести к необратимым изменениям.

При попытке выполнить потенциально опасное действие агент приостанавливает работу и запрашивает явное подтверждение в REPL-интерфейсе. Пользователю выводится точный текст команды или diff изменений.

# Пример запроса подтверждения в интерактивной сессии
Claude wants to run: npm test -- --watchAll=false
Allow this command? [y/n/a/d] (y = yes, n = no, a = always allow this tool, d = details)

Ответ определяет сценарий выполнения:

y (yes) — однократное выполнение текущей операции.
n (no) — отклонение действия. Агент получает сообщение об ошибке отказа в доступе и пробует решить задачу альтернативным путём.
a (always) — добавление инструмента или конкретного шаблона команды в белый список текущей сессии.
d (details) — подробный разбор контекста вызова.

Уровни контроля и флаги запуска

Поведение системы разрешений можно калибровать под текущую среду: локальная разработка, изолированный Docker-контейнер или CI/CD-пайплайн.

Режим / Флаг	Как работает	Где применять	Риск
Интерактивный (по умолчанию)	Запрашивает подтверждение на все bash-команды и модификации файлов	Основная разработка на рабочей машине	Минимальный
Разрешённые инструменты (`--allowedTools`)	Автоматически одобряет только указанные типы операций (например, чтение)	Анализ и ревью кода без права правок	Низкий
Пропуск проверок (`--dangerously-skip-permissions`)	Отключает любые подтверждения; все действия выполняются мгновенно	Изолированные контейнеры, эфемерные VM	Критический

Никогда не используйте флаг полного пропуска проверок на основной рабочей машине с доступом к личным ключам SSH, токенам облачных провайдеров и рабочим базам данных. Агент может выполнить команду, которую посчитает логичной в контексте диалога, но которая перезапишет системные конфигурации.

Навигация по файлам и чтение кодовой базы

Главная ошибка при работе с ИИ в терминале — попытка отправить агенту весь репозиторий разом. При объёме проекта в десятки тысяч строк контекстное окно быстро забивается посторонним кодом, растёт стоимость запросов, а точность генерации падает из-за эффекта «иголки в стоге сена».

Claude Code исследует проект так же, как опытный разработчик: от общего к частному.

Постановка задачи ("Исправь ошибку 401 в auth-middleware")
   │
   ▼
1. GlobTool: поиск подходящих файлов (*auth*, *middleware*)
   │
   ▼
2. GrepTool: поиск сигнатур и вызовов (например, "jwt.verify")
   │
   ▼
3. View: точечное чтение только нужных фрагментов (строки 40–95)
   │
   ▼
4. FileEdit: точечный патч проблемного участка

Встроенные инструменты исследования

Поиск по маске (Glob): агент сканирует структуру проекта, находя файлы без чтения их содержимого. Например, паттерн src/api/**/*.ts возвращает плоский список путей за доли секунды.
Поиск по содержимому (Grep): агент ищет вхождения функций, импортов или констант. Вместо чтения всего файла агент получает только номера строк и окружающий контекст (grep match).
Срезы файлов (View): чтение выполняется не целиком, а блоками (например, строки с 1 по 120). Это экономит токены и фокусирует внимание модели на целевой функции.

Гигиена контекста и файл .claudeignore

Даже самый умный алгоритм навигации споткнётся, если каталог проекта захламлён сгенерированными файлами, бинарными сборками или зависимостями.

Если в проекте нет явных ограничений, поисковые инструменты агента могут попытаться проиндексировать node_modules, папку .git, дампы баз данных или директории сборки (dist, build). Это приводит к расходу сотен тысяч токенов на чтение минифицированного кода сторонних библиотек.

Для изоляции рабочей области от ненужного и чувствительного содержимого используется файл .claudeignore, который помещается в корень репозитория.

Синтаксис .claudeignore полностью идентичен правилам .gitignore:

# Зависимости и пакеты
node_modules/
vendor/
.venv/

# Артефакты сборки и кэш
dist/
build/
.next/
*.tsbuildinfo
.cache/

# Чувствительные данные и секреты (КРИТИЧНО)
.env
.env.*
*.pem
*.key
credentials.json

# Логи и дампы
logs/
*.log
dump.rdb
*.sqlite

Защита конфиденциальных данных

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

Если агенту для отладки требуется проверить формат конфигурации, безопасной практикой является создание файла .env.example с фиктивными значениями. Присутствие реального .env в .claudeignore гарантирует, что ни при каких условиях секреты не попадут в контекст запроса и не будут отправлены на серверы API.

Практический сценарий: безопасный аудит проекта

Объединим управление разрешениями и правила навигации на практике. Представим задачу: нужно подключить Claude Code к незнакомому репозиторию на Node.js, найти все устаревшие вызовы API и составить отчёт, исключив риск изменения кода или утечки секретов.

Последовательность действий для безопасного сеанса:

Создание файла исключений:

echo -e ".env\nnode_modules/\ndist/\n*.log" > .claudeignore

Запуск сессии в режиме чтения: Мы ограничиваем доступные агенту инструменты только просмотром и поиском, блокируя любые попытки записи и выполнение неконтролируемых bash-команд:
```
claude --allowedTools View,GlobTool,GrepTool
```
Формулирование задачи:

«Найди все места в коде внутри каталога src/, где используется устаревший метод jwt.decode() без проверки подписи. Сформируй список файлов и номеров строк. Файлы не редактируй».

Агент использует GlobTool для локализации структуры каталога src/, затем через GrepTool найдёт вхождения jwt.decode, точечно прочитает контекст через View и выдаст структурированный список. При этом попытка агента случайно запустить тесты или изменить файл будет автоматически заблокирована на уровне CLI-интерфейса.

Промптинг для терминала и настройка правил в CLAUDE.md

Если запустить агентную сессию в незнакомом проекте и попросить Claude Code «добавить валидацию email при регистрации», результат может удивить: агент выберет привычный ему менеджер пакетов npm вместо командного pnpm, напишет код на чистом JavaScript посреди строгого TypeScript-проекта и применит библиотеку валидации, которой нет в зависимостях.

В отличие от веб-интерфейса, где языковая модель лишь генерирует текст в ответ на реплику, CLI-агент напрямую вносит изменения в файлы и выполняет системные команды. Каждое неточное указание трансформируется в реальные ошибки сборки, конфликты версий и лишнюю трату токенов. Чтобы агент действовал как штатный senior-инженер вашей команды, ему необходимы два компонента: оперативный каркас формулирования задач в терминале и долговременная память проекта в виде файла CLAUDE.md.

Терминальный промптинг: от диалога к спецификации

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

Эффективный терминальный промпт опирается на триаду: Действие — Ограничения — Верификация.

Формула надежного промпта:

Действие (Action): точный глагол и объект модификации.

Ограничения (Constraints): используемые библиотеки, стили, запрещенные подходы.

Верификация (Verification): способ, которым агент обязан проверить результат перед завершением работы.

Параметр	Слабый промпт (диалоговый стиль)	Эффективный промпт (агентная спецификация)
Формулировка	«Сделай кнопку экспорта данных в админке красивой и рабочей»	«Добавь кнопку экспорта заказов в CSV на страницу `admin/orders`. Используй компонент `Button` из `@/components/ui`. Проверь сборку через `pnpm build`»
Поведение агента	Запускает хаотичный поиск, ставит произвольные стили, завершает задачу без проверки	Находит существующие UI-компоненты, реализует логику в рамках дизайн-системы, запускает линтер и билд
Расход токенов	Высокий (множество итераций исправлений)	Минимальный (точное попадание с первого прохода)

Когда задача сложная, разбивайте ее на шаги прямо в промпте. Агенту можно явно указывать последовательность операций: «Сначала найди схему базы данных для модели User, затем создай миграцию на добавление поля telegram_id, обнови типы и выполни тесты».

Долговременная память проекта: архитектура CLAUDE.md

Каждая новая сессия Claude Code изолирована: агент начинает работу с чистым контекстом и не знает договоренностей вашей команды. Передавать одни и те же правила в каждом промпте нерационально. Для автоматической загрузки контекста Anthropic разработала механизм CLAUDE.md — специального конфигурационного файла в формате Markdown, который считывается агентом при инициализации рабочего окружения.

Агент ищет инструкции не только в корне текущего репозитория, но и по иерархическому дереву файловой системы.

Иерархия резолвинга правил

Глобальный уровень (~/.claude/CLAUDE.md): общие предпочтения разработчика, применяемые ко всем проектам на данной машине (например, «Всегда отвечай на русском языке», «Используй git-коммиты по соглашению Conventional Commits»).
Корневой уровень проекта (./CLAUDE.md или ./.claude/CLAUDE.md): базовые стандарты репозитория, команды сборки, стек технологий, правила тестирования.
Уровень подкаталогов (./packages/backend/CLAUDE.md): правила локальных модулей или пакетов в монорепозитории. При работе с файлами внутри packages/backend агент объединяет правила корневого файла с локальными, причем более специфичные директивы каталога уточняют глобальные настройки.

Анатомия идеального CLAUDE.md

Файл CLAUDE.md попадает непосредственно в системный контекст каждого запроса. Избыточный текст, длинные философские рассуждения об архитектуре или копипаста документации «съедают» полезное контекстное окно модели.

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

Обязательные разделы

Команды сборки и запуска (Build & Dev commands): точные скрипты для сборки, линтинга, форматирования и прогона тестов. Агент использует их для самопроверки.
Архитектурный стек и соглашения (Architecture & Conventions): фреймворки, менеджеры состояния, структура слоев приложения.
Стиль кода (Code Style): специфика именования, правила импортов, требования к типизации.
Ограничения и антипаттерны (Strict Boundaries): чего делать категорически нельзя (например, «Не использовать any в TypeScript», «Не ставить зависимости без явного подтверждения»).

Пример эталонного CLAUDE.md

# Инструкции проекта CRM Dashboard

## Команды управления
- Сборка: `pnpm build`
- Запуск тестов: `pnpm test:unit`
- Запуск одного теста: `pnpm vitest run path/to/test.ts`
- Линтинг: `pnpm lint --fix`
- Менеджер пакетов: строго `pnpm` (не использовать npm или yarn)

## Стек и архитектура
- Фреймворк: Next.js 14 (App Router), TypeScript (strict mode)
- Стилизация: Tailwind CSS + Radix UI primitives
- Валидация данных: Zod схемы в директории `src/schemas/`
- Серверное состояние: TanStack Query v5

## Правила написания кода
- Все компоненты страниц размещать в `src/app/`, изолированные UI-элементы — в `src/components/ui/`
- Использовать Server Components по умолчанию. 'use client' добавлять только при наличии хуков состояния или браузерных событий
- Все мутации данных оформлять через Server Actions в `src/actions/`
- Обработка ошибок: возвращать `{ success: false, error: string }`, не бросать необработанные исключения

## Запрещено
- Не создавать новые зависимости в package.json без разрешения пользователя
- Не использовать inline-стили (style={{ ... }}) — только Tailwind классы
- Не модифицировать файлы в директории `src/generated/`

Управление контекстом и инициализация через CLI

Если вы открыли существующий проект, в котором еще нет файла правил, его не обязательно создавать вручную с нуля. Claude Code предоставляет встроенные инструменты генерации и менеджмента контекста:

/init — интерактивная команда внутри REPL. Агент исследует структуру репозитория, package-файлы, конфигураторы линтеров и автоматически формирует черновик CLAUDE.md, адаптированный под ваш стек.
/compact — сжимает текущую историю диалога в сессии, сохраняя только ключевые выводы и очищая контекст от промежуточного вывода терминала.
/clear — полный сброс текущей истории сообщений. При этом CLAUDE.md останется подключенным, так как он считывается заново при инициализации контекста сессии.

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

Тонкая конфигурация CLI-агента под задачи

Файл CLAUDE.md задаёт правила поведения агента внутри конкретного репозитория, но что определяет глобальные параметры работы самого CLI-инструмента — от выбора языковой модели и лимитов потребления токенов до системных прокси и пользовательских алиасов? Без системной настройки окружения разработчик неизбежно сталкивается с ситуацией, когда агент в фоновом режиме расходует лимиты API дорогой модели на тривиальный рефакторинг или блокируется корпоративным сетевым экраном.

Тонкая настройка Claude Code опирается на многоуровневую систему параметров. Понимание того, как взаимодействуют флаги запуска, переменные окружения и конфигурационные файлы, превращает стандартный интерфейс командной строки в персонализированный инструмент под специфику конкретного рабочего процесса.

Иерархия параметров и слои конфигурации

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

Приоритет конфигурационных слоёв распределяется в порядке убывания (от наивысшего к наинизшему):

Флаги командной строки (CLI Flags): параметры, переданные непосредственно при вызове команды (например, --model или --allowedTools). Они обладают абсолютным приоритетом и действуют только в рамках текущего запуска.
Переменные окружения сессии (Environment Variables): переменные, экспортированные в текущей оболочке (export VAR=value) или заданные перед вызовом команды.
Локальный конфигурационный файл проекта: настройки в каталоге .claude/ внутри рабочего репозитория (.claude/settings.local.json и .claude/settings.json).
Глобальный конфигурационный файл пользователя: параметры, расположенные в домашней директории пользователя (~/.claude/settings.json или ~/.claude.json), применяемые ко всем проектам по умолчанию.
Системные значения по умолчанию: зашитые в CLI-клиент базовые параметры Anthropic.

Слой конфигурации	Область видимости	Пример использования	Срок жизни
CLI флаги	Текущий процесс	`claude -p --model claude-3-5-haiku-20241022`	До завершения команды
Переменные окружения	Текущая сессия оболочки	`ANTHROPIC_MODEL=claude-3-5-sonnet-20241022`	До закрытия терминала
Проектные настройки	Конкретный репозиторий	`.claude/settings.json`	Постоянно для проекта
Глобальные настройки	Все проекты пользователя	`~/.claude/settings.json`	Постоянно для системы

Знание этой иерархии предотвращает конфликты параметров: если глобально выставлена модель по умолчанию, но в одном проекте требуется экономичный режим, достаточно переопределить параметр на уровне локального каталога или флага запуска.

Управление моделями и баланс «стоимость — качество»

По умолчанию Claude Code ориентирован на флагманские модели семейства Sonnet, обеспечивающие максимальную точность при решении сложных архитектурных задач и написании кода с нуля. Однако рутинные операции — поиск опечаток, расстановка JSDoc-комментариев, аудит форматирования или генерация простых тестов — не требуют максимальной вычислительной мощности.

Для выбора базовой модели используется переменная окружения ANTHROPIC_MODEL либо флаг --model при запуске.

# Разовый запуск аудита с использованием быстрой и экономичной модели Haiku
claude --model claude-3-5-haiku-20241022 -p "Проверь синтаксис в src/utils/formatters.ts"

# Установка Sonnet для глубокого рефакторинга в текущей сессии
export ANTHROPIC_MODEL="claude-3-7-sonnet-20250219"
claude

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

Задержка ответа (Latency): компактные модели генерируют ответы и вызывают инструменты (GlobTool, GrepTool) быстрее, что ускоряет выполнение простых линейных скриптов.
Глубина рассуждений (Reasoning Capability): старшие модели точнее удерживают цепочки зависимостей в крупных кодовых базах и реже ошибаются при формировании правок через FileEdit.

Экономика агентной разработки строится на разделении контекста: для глубоких мультифайловых изменений и проектирования архитектуры используется Sonnet, а для фоновых скриптов линтинга, валидации и документации — Haiku.

Конфигурация сетевого окружения и прокси

В корпоративных средах прямой доступ к серверам Anthropic часто ограничен прокси-серверами или закрытыми контурами безопасности с кастомными SSL-сертификатами. Claude Code считывает стандартные сетевые переменные окружения Node.js:

# Настройка HTTP и HTTPS прокси
export HTTP_PROXY="http://proxy.internal.company.com:8080"
export HTTPS_PROXY="http://proxy.internal.company.com:8080"

# Исключение локальных адресов из проксирования
export NO_PROXY="localhost,127.0.0.1,.internal.company.com"

# Указание пути к корпоративному CA-сертификату
export NODE_EXTRA_CA_CERTS="/etc/ssl/certs/company-internal-ca.pem"

Если взаимодействие с API осуществляется через кастомный шлюз (API Gateway) или совместимый с Anthropic прокси-эндпоинт, базовый URL переопределяется через переменную ANTHROPIC_BASE_URL:

export ANTHROPIC_BASE_URL="https://api-gateway.company.internal/v1"

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

Профилирование и алиасы для типовых сценариев

Постоянный ввод длинных команд с набором флагов противоречит идее эффективного вайб-кодинга. Оптимальный подход — создание специализированных профилей через алиасы командной оболочки (~/.zshrc или ~/.bashrc).

Рассмотрим практическую конфигурацию нескольких специализированных режимов:

# 1. Режим безопасного аудитора: только чтение файлов, модель Haiku
alias claude-audit='claude --model claude-3-5-haiku-20241022 --allowedTools View,GlobTool,GrepTool'

# 2. Режим полной автономности для изолированных песочниц (контейнеров)
alias claude-auto='claude --dangerously-skip-permissions'

# 3. Быстрый генератор коммитов: разовый запрос к модели
alias claude-commit='claude -p "Проанализируй git diff --staged и предложи краткое сообщение коммита по Conventional Commits. Выведи только текст сообщения."'

Каждый такой алиас решает изолированную задачу:

claude-audit гарантирует, что агент ни при каких условиях не изменит код и не выполнит деструктивных команд в терминале.
claude-auto снимает необходимость интерактивных подтверждений при работе внутри временных Docker-контейнеров.
claude-commit автоматизирует рутину фиксации изменений без входа в интерактивный REPL-режим.

Интеграция конфигураций в рабочий процесс

Эффективная организация конфигурации Claude Code строится на правильном разделении ответственности:

Глобальный уровень (~/.zshrc, ~/.claude/): API-ключи, корпоративные прокси, персональные терминальные алиасы и дефолтная модель.
Уровень репозитория (CLAUDE.md, .claudeignore): команды сборки, стандарты кодовой базы, архитектурные ограничения и списки исключённых директорий.
Уровень разового запуска (CLI-флаги): переопределение модели под конкретную сложную подзадачу или ограничение доступных инструментов.

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

Архитектура агентов и обработка данных и таблиц

Попытка скормить языковой модели 500-мегабайтный CSV-файл с транзакциями за год гарантированно закончится одной из двух проблем: переполнением контекстного окна либо огромным счётом за токены с риском галлюцинаций в агрегациях. Однако Claude Code справляется с анализом таких объёмов за несколько секунд, затратив минимум токенов сессии. Секрет кроется не в увеличении размера контекста, а в фундаментальной смене роли модели: из «читателя текста» агент превращается в оркестратора кода.

Вместо попыток вычислений «в уме» агентный CLI использует системные ресурсы вашего компьютера. Чтобы эффективно ставить задачи на обработку структурированных массивов, необходимо понимать внутреннюю архитектуру принятия решений агента и методы безопасного делегирования вычислений локальной среде.

Анатомия агентного цикла: ReAct и оркестрация инструментов

В основе автономного поведения Claude Code лежит архитектурный паттерн ReAct (Reasoning + Acting). В отличие от классического режима чат-бота, где модель генерирует финальный текстовый ответ за один проход, агент функционирует в непрерывном цикле из трёх состояний:

Рассуждение (Thought): Модель анализирует входящий запрос, текущее состояние файловой системы и формулирует гипотезу или подзадачу.
Действие (Action): Агент выбирает подходящий инструмент (запуск bash-команды, чтение среза файла, редактирование кода) и формирует полезную нагрузку.
Наблюдение (Observation): Терминальная среда выполняет действие и возвращает стандартный вывод (stdout) или ошибку (stderr) обратно в контекст агента.

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

Ключевой инсайт: Агент никогда не считает медиану или сумму колонок в своей нейросетевой памяти. Он пишет скрипт на Python, Node.js или вызывает утилиту оболочки, запускает её в изолированном subshell-процессе и считывает готовый результат из stdout.

Стратегии обработки структурированных данных

При работе с табличными данными (CSV, TSV), древовидными структурами (JSON, YAML) или реляционными дампами критически важно удерживать расход контекстного окна на минимальном уровне. Для этого применяются три основных архитектурных паттерна.

Стратегия	Механизм	Когда применять	Расход токенов
In-Context Injection	Прямое чтение файла в контекст через инструмент просмотра	Небольшие конфигурационные файлы ( $< 50$ КБ)	Пропорционален размеру файла
Schema Discovery	Снятие заголовков, типов данных и первых строк (`head`, `jq`)	Первичный аудит структуры любого объёма	Минимальный ( $< 500$ токенов)
Code Execution Filter	Генерация и запуск локальных скриптов обработки	Массивы от единиц мегабайт до десятков гигабайт	Фиксированный (только код скрипта и итоговая сводка)

1. Паттерн Schema Discovery (Исследование схемы)

Перед обработкой любого набора данных агент должен изучить его метаданные, не загружая сам массив. Правильный промпт направляет агента на безопасную инспекцию:

claude -p "Определи структуру файла data/users_dump.csv: покажи список колонок, типы данных и первые 3 строки. Не читай файл целиком."

Получив такую задачу, агент выполняет в терминале эквивалент команды:

head -n 4 data/users_dump.csv

В контекст попадает лишь минимальный срез данных, достаточный для проектирования алгоритма трансформации.

2. Паттерн Code Execution as Data Filter

Когда требуется фильтрация или агрегация, агент генерирует одноразовый скрипт, производящий вычисления на диске или в оперативной памяти машины.

Практический пайплайн: аудит, очистка и трансформация

Рассмотрим сквозную задачу. В проекте находится файл customers_dirty.csv объёмом 120 МБ, содержащий пропуски в номерах телефонов, некорректные форматы дат (смесь DD/MM/YYYY и YYYY-MM-DD) и дубликаты записей.

Вместо абстрактных просьб «исправь файл», эффективный агентный пайплайн делится на четыре последовательных этапа.

+-------------------+      +--------------------+      +--------------------+      +--------------------+
|  1. Исследование  | ---> |  2. Проектирование | ---> |  3. Изолированное  | ---> |   4. Верификация   |
|   схемы и брака   |      |  скрипта очистки   |      |    тестирование    |      |     результата     |
+-------------------+      +--------------------+      +--------------------+      +--------------------+

Шаг 1: Поиск аномалий и спецификация правил

Формулируем задачу на выявление краевых случаев без модификации исходного файла:

claude
> Исследуй customers_dirty.csv. Напиши и выполни Python-скрипт, который выведет:
  1. Общее количество строк.
  2. Список колонок с количеством пустых значений.
  3. Все уникальные форматы в колонке registration_date.
  Сам файл не изменяй.

Агент создаёт временный скрипт с использованием csv или pandas, запускает его через bash-инструмент и возвращает точную аналитическую сводку.

Шаг 2: Генерация и запуск пайплайна очистки

На основе полученной сводки задаются строгие правила нормализации:

> Создай скрипт scripts/clean_customers.py:
  - Удалить полные дубликаты строк.
  - Привести все даты в колонке registration_date к формату ISO-8601 (YYYY-MM-DD).
  - Если номер телефона невалиден, записать null.
  - Результат сохранить в data/customers_clean.csv.
  - Вывести отчёт: сколько строк обработано, сколько удалено, сколько дат нормализовано.
  Запусти скрипт и покажи вывод.

Шаг 3: Самокоррекция при сбоях (Self-Correction Loop)

Если в процессе выполнения скрипт падает с ошибкой (например, ValueError: time data '31-02-2023' does not match format), вступает в действие агентный цикл:

Терминал возвращает агенту трассировку стека (stderr).
Агент локализует строку, вызвавшую сбой.
Добавляет обработку исключения (например, fallback на errors='coerce').
Повторно запускает скрипт до получения нулевого кода возврата (exit code 0).

Локальная аналитика: SQLite и DuckDB как промежуточный слой

Для сложных реляционных преобразований и аналитических выборок эффективнее всего загружать сырые данные во временные встраиваемые СУБД. Это избавляет от необходимости писать многостраничный процедурный код.

Использование DuckDB для мгновенных аналитических SQL-запросов

DuckDB позволяет выполнять прямой SQL-запрос к файлам CSV, Parquet и JSON без предварительного создания таблиц.

> Используя duckdb CLI, найди топ-5 городов по сумме покупок из data/orders.csv и data/users.csv, объединив их по user_id.

Агент сформирует и выполнит лаконичную команду:

duckdb -c "
SELECT u.city, ROUND(SUM(o.amount), 2) as total_spent
FROM 'data/orders.csv' o
JOIN 'data/users.csv' u ON o.user_id = u.id
GROUP BY u.city
ORDER BY total_spent DESC
LIMIT 5;
"

Такой подход требует десятых долей секунды на выполнение и возвращает в контекст лишь компактную финальную таблицу из 5 строк.

Работа с вложенными JSON через `jq`

При работе с логами и JSONL-дампами вызов специализированной утилиты jq даёт максимальную скорость фильтрации:

# Извлечение только ошибок уровня ERROR с кодом ответа >= 500
jq -c 'select(.level == "ERROR" and .status >= 500) | {timestamp, path, error}' server.log > critical_errors.jsonl

Делегируя подобные операции утилитам уровня операционной системы, вы сохраняете контекст Claude Code чистым для решения архитектурных и инженерных задач следующего уровня.

Создание веб-страниц и конверсионных сайтов

Человеческий мозг формирует первое визуальное впечатление о веб-странице всего за 50 миллисекунд. Если посетитель за первые три секунды не понимает, какую проблему решает продукт и куда нужно нажать, конверсия падает в разы. В классической разработке создание даже простого промо-сайта требует слаженной работы дизайнера, верстальщика и фронтенд-инженера. В агентной разработке через Claude Code дистанция между идеей и рабочим сайтом сокращается до нескольких минут, однако бесконтрольная генерация вслепую часто приводит к визуальному шуму, «поехавшей» сетке и неработающим кнопкам.

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

Выбор стека: почему утилитарный CSS побеждает в вайб-кодинге

При генерации веб-интерфейсов через языковую модель выбор технологического стека напрямую определяет качество результата. Традиционный подход с разделением на HTML и отдельные CSS/SCSS-файлы заставляет агента постоянно переключаться между контекстами, синхронизировать имена классов и держать в памяти каскадные таблицы стилей.

Наиболее надёжный стек для автономной генерации фронтенда включает три компонента:

Vite (или Next.js / Astro) — обеспечивает мгновенный старт сборщика и Hot Module Replacement (HMR).
Tailwind CSS — утилитарные классы помещают разметку и оформление в единый контекст, исключая конфликты имен и разрастание изолированных стилевых файлов.
Lucide Icons — векторные иконки с прозрачным именованием компонентов (<ArrowRight />, <ShieldCheck />), которые модель использует без ошибок в путях к ассетам.

Параметр сравнения	Классический CSS / SCSS	Tailwind CSS в связке с Claude Code
Локальность контекста	Стили оторваны от HTML-тегов, требуются вызовы `View` для двух файлов	Стили встроены в атрибут `class`, генерация идёт за один проход
Риск регрессии	Изменение глобального класса ломает соседние страницы	Утилитарные классы изолированы внутри конкретного элемента
Адаптивность	Громоздкие медиавыражения (`@media (min-width: 768px)`)	Компактные префиксы брейкпоинтов (`md:flex`, `lg:grid-cols-3`)
Консистентность дизайна	Произвольные отступы и цвета в пикселях	Фиксированная шкала отступов (`p-4`, `gap-6`) и готовая палитра

Утилитарный подход Tailwind CSS снижает когнитивную нагрузку на контекстное окно модели: агенту не нужно выполнять GrepTool для поиска селекторов, вся визуальная семантика сосредоточена прямо в узле разметки.

Анатомия конверсионной структуры

Конверсионный сайт строится не вокруг абстрактной эстетики, а вокруг пути пользователя. Модель должна получать задачу не в виде «сделай красивый лендинг», а в виде чёткой иерархии смысловых блоков, реализующих классическую маркетинговую модель AIDA (Attention, Interest, Desire, Action).

Стандартная архитектура посадочной страницы состоит из шести обязательных секций:

Hero Section (Первый экран) — чёткий оффер (H1), подзаголовок с конкретной выгодой, главный призыв к действию (Primary CTA) и социальное доказательство первого уровня (рейтинг, бейдж «10,000+ пользователей»).
Social Proof (Логотипы и доверие) — монохромная лента логотипов клиентов, публикации в медиа или сертификаты безопасности.
Problem & Solution (Проблема и решение) — контрастное противопоставление: «Как вы работаете сейчас» (рутина, потери) против «Как с нашим продуктом» (автоматизация, скорость).
Feature Grid (Сетка возможностей) — 3–6 карточек ключевых функций с акцентными иконками, заголовками и кратким описанием пользы, а не технических деталей.
Interactive Demo / Calculator (Вовлечение) — интерактивный элемент (калькулятор окупаемости, переключатель тарифов или превью дашборда), удерживающий внимание.
Lead Capture & Final CTA (Захват контактов) — простая форма из 1–2 полей (Email + Имя) без лишних барьеров и кнопка с триггером действия.

Паттерн Component-First Prompting

Чтобы Claude Code собрал страницу чисто и без дублирования, задачу разделяют на генерацию дизайн-токенов и изолированных компонентов.

Пример спецификации для инициализации проекта и сборки первого экрана:

# Инициализация легковесного проекта
npm create vite@latest landing-page -- --template react-ts
cd landing-page
npm install -D tailwindcss postcss autoprefixer
npm install lucide-react
npx tailwindcss init -p

Промпт для агента формулируется по принципу «Дизайн-система → Каркас → Состояние»:

ДЕЙСТВИЕ: Создай посадочную страницу для SaaS-сервиса автоматического аудита баз данных.
ДИЗАЙН-СИСТЕМА:
- Цвета: Slate-900 (фон темной темы), Emerald-500 (акцент/конверсия), Indigo-400 (вторичные акценты).
- Шрифт: Inter / sans-serif, строгая типографика с контрастными заголовками.
ОГРАНИЧЕНИЯ:
- Использовать Tailwind CSS и lucide-react.
- Реализовать Hero-секцию: бейдж "v2.0 доступна", H1 с градиентным текстом, 2 кнопки (Primary Emerald, Secondary Outline), поле ввода Email с валидацией.
- Полная адаптивность: мобильная колонка (flex-col), десктопная сетка (md:flex-row).
ВЕРИФИКАЦИЯ: Запусти npm run build и проверь отсутствие TypeScript-ошибок.

Адаптивность и динамика поведения интерфейса

Качественный конверсионный интерфейс обязан корректно перестраиваться между разрешениями экранов. Claude Code отлично справляется с префиксами sm:, md:, lg:, xl:, если ему явно заданы правила трансформации сложных элементов (например, скрытие навигационного меню в мобильный «гамбургер» или превращение многоколоночной таблицы тарифов в слайдер/аккордеон).

Для предотвращения сдвигов макета (Cumulative Layout Shift) и обеспечения доступности (a11y) требуются следующие правила вёрстки:

Контрастность элементов: Обычный текст на кнопке действия (CTA) должен иметь контрастность к фону не менее $4.5:1$ , а сами графические элементы управления — не менее $3:1$ по стандарту WCAG AA.
Состояния интерактивности: Каждый кликабельный элемент обязан содержать классы transition-all, hover:, active: и фокусные стили focus:ring-2.
Резервирование пространства: Блоки с асинхронным контентом или иконками должны иметь фиксированные минимальные размеры (min-h-[...], w-6 h-6), чтобы интерфейс не дергался при загрузке.

Цикл визуальной обратной связи: Dev-сервер и живая отладка

Главная сложность вайб-кодинга во фронтенде — агент «не видит» экран глазами человека, если работает исключительно через чтение кода. Для эффективной работы организуется цикл с локальным сервером разработки:

[Claude Code вносит правки]
          │
          ▼
   [HMR / Vite Build] ──(Ошибки сборки)──► [Claude Code читает stderr и исправляет]
          │
    (Сборка успешна)
          │
          ▼
[Разработчик в браузере: http://localhost:5173] ──(Замечания по UI)──► [Промпт с точечной правкой]

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

Фоновый запуск: В терминале запускается npm run dev. В сессии Claude Code агент выполняет правки файлов компонентов (src/components/Hero.tsx, src/App.tsx).
Контроль сборки: Если допущена ошибка импорта или неверный тип свойства (props), сборщик мгновенно выдает ошибку. Агент перехватывает вывод компилятора через команды проверки (npm run build или чтение терминала) и автоматически устраняет нестыковку.
Точечные визуальные директивы: Разработчик направляет агента короткими итеративными промптами, указывая на конкретные селекторы или визуальные артефакты:
- «Уменьши отступ между H1 и подзаголовком на мобильных до py-2»
- «Сделай карточки тарифов одинаковой высоты через h-full flex flex-col justify-between»

Клиентская логика: валидация, микроинтерактивность и захват лидов

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

Для организации полноценного сбора заявок без развертывания отдельного бекенда агент может внедрить валидацию на базе легковесных решений (например, регулярные выражения или библиотека Zod) и настроить отправку через бессерверные вебхуки (Formspree, Webhook.site, Telegram Bot API).

Пример реализации компонента формы с состояниями загрузки, валидации и успеха:

import React, { useState } from 'react';
import { Send, CheckCircle2, AlertCircle, Loader2 } from 'lucide-react';

interface LeadFormProps {
  webhookUrl?: string;
}

export const LeadCaptureForm: React.FC<LeadFormProps> = ({ webhookUrl }) => {
  const [email, setEmail] = useState('');
  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
  const [errorMessage, setErrorMessage] = useState('');

  const validateEmail = (value: string): boolean => {
    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
  };

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!validateEmail(email)) {
      setStatus('error');
      setErrorMessage('Пожалуйста, введите корректный рабочий email');
      return;
    }

    setStatus('loading');
    setErrorMessage('');

    try {
      if (webhookUrl) {
        const response = await fetch(webhookUrl, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ email, timestamp: new Date().toISOString() })
        });
        if (!response.ok) throw new Error('Ошибка сервера');
      } else {
        // Эмуляция сетевой задержки для прототипа
        await new Promise((resolve) => setTimeout(resolve, 800));
      }
      setStatus('success');
    } catch (err) {
      setStatus('error');
      setErrorMessage('Не удалось отправить заявку. Попробуйте снова.');
    }
  };

  if (status === 'success') {
    return (
      <div className="flex items-center gap-3 rounded-xl bg-emerald-500/10 p-4 text-emerald-400 border border-emerald-500/20">
        <CheckCircle2 className="h-5 w-5 flex-shrink-0" />
        <p className="text-sm font-medium">Доступ отправлен! Проверьте почтовый ящик.</p>
      </div>
    );
  }

  return (
    <form onSubmit={handleSubmit} className="w-full max-w-md space-y-3">
      <div className="relative flex items-center">
        <input
          type="email"
          value={email}
          onChange={(e) => {
            setEmail(e.target.value);
            if (status === 'error') setStatus('idle');
          }}
          placeholder="name@company.com"
          disabled={status === 'loading'}
          className="w-full rounded-xl bg-slate-800 border border-slate-700 px-4 py-3.5 text-slate-100 placeholder-slate-400 outline-none transition focus:border-emerald-500 focus:ring-2 focus:ring-emerald-500/20 disabled:opacity-50"
        />
        <button
          type="submit"
          disabled={status === 'loading'}
          className="absolute right-1.5 flex items-center gap-2 rounded-lg bg-emerald-500 px-4 py-2 text-sm font-semibold text-slate-950 transition hover:bg-emerald-400 active:scale-95 disabled:opacity-50"
        >
          {status === 'loading' ? (
            <Loader2 className="h-4 w-4 animate-spin" />
          ) : (
            <>
              <span>Начать</span>
              <Send className="h-4 w-4" />
            </>
          )}
        </button>
      </div>
      {status === 'error' && (
        <div className="flex items-center gap-2 text-xs text-rose-400">
          <AlertCircle className="h-4 w-4" />
          <span>{errorMessage}</span>
        </div>
      )}
    </form>
  );
};

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

Интеграция с Git и GitHub через Claude Code

Рабочий день инженера редко состоит только из написания логики: от $30\%$ до $50\%$ времени уходит на рутину контроля версий — инспекцию диффов, формулирование осмысленных сообщений коммитов, создание веток, открытие Pull Request и устранение замечаний ревьюеров. Когда разработка ускоряется благодаря ИИ-агенту, возникает опасный соблазн свалить сорок изменённых файлов в один гигантский коммит git add . && git commit -m "fix stuff". Такой подход мгновенно ломает историю репозитория, делает git bisect бесполезным и парализует командное код-ревью.

Claude Code решает эту проблему на уровне терминала: агент умеет анализировать семантику изменений, делить единый рабочий дифференциал на изолированные атомарные коммиты по стандарту Conventional Commits, взаимодействовать с GitHub CLI (gh) и автономно разрешать конфликты слияния.

Семантический аудит изменений и атомарные коммиты

В отличие от простых скриптов автоматизации, агент не выполняет git add . вслепую. Опираясь на команды git status и git diff, Claude Code группирует изменения по их архитектурному смыслу.

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

Формат Conventional Commits в инструкциях агента

Чтобы агент форматировал историю в соответствии со стандартами команды, эти требования закрепляются в файле CLAUDE.md. Стандартная спецификация Conventional Commits имеет вид:

<type>(<scope>): <short summary>

[optional body]

[optional footer(s)]

Основные типы фиксаций:

feat: добавление новой функциональности;
fix: исправление ошибки;
refactor: изменение кода без изменения его внешнего поведения;
test: добавление или корректировка тестов;
docs: обновление документации;
chore: сопутствующие задачи (обновление зависимостей, конфигурация линтеров).

Когда в репозитории накопились разнородные правки (например, добавление схемы валидации формы, сопутствующий рефакторинг утилит дат и обновление пакетов в package.json), агенту подаётся направляющий запрос:

claude -p "Проанализируй git diff, разбей изменения на атомарные коммиты по Conventional Commits и выполни коммиты последовательно"

Агент выполняет поэтапное индексирование:

git add src/utils/date.ts $\rightarrow$ git commit -m "refactor(utils): simplify date parsing logic"
git add src/schemas/auth.ts src/components/Form.tsx $\rightarrow$ git commit -m "feat(auth): add email domain validation schema"
git add package.json pnpm-lock.yaml $\rightarrow$ git commit -m "chore(deps): bump zod from 3.22 to 3.23"

Каждый шаг верифицируется: агент проверяет статус индекса и гарантирует, что временные файлы, дампы или переменные окружения не попадут в историю.

Бесшовная связка с GitHub CLI (`gh`)

Контроль версий не ограничивается локальным компьютером. Для полноценного цикла командной разработки Claude Code комбинируется с официальной утилитой GitHub CLI (gh).

GitHub CLI предоставляет агенту программный доступ к Pull Requests, Issues, комментариям ревьюеров и GitHub Actions прямо через subshell.

# Проверка авторизации в GitHub CLI
gh auth status

Если утилита настроена, Claude Code получает возможность управлять полным жизненным циклом ветки — от получения задачи до открытия PR.

Паттерн Feature-Branch разработки

Типовой агентный сценарий включает четыре шага:

Создание изолированной ветки под задачу:
```
git checkout -b feat/export-orders-csv
```
Реализация изменений и прогон тестов: Агент вносит правки, запускает npm test или pytest, проверяет отсутствие регрессий.

Фиксация и пуш:

git push -u origin feat/export-orders-csv

Формирование Pull Request с автогенерацией описания:

gh pr create --title "feat(orders): implement CSV export streaming" \
  --body "## Описание изменений
- Реализован потоковый экспорт заказов в CSV через Web Streams API.
- Добавлены юнит-тесты для санитизации спецсимволов.

## Связанные задачи
Closes #142"

Сводная таблица показывает распределение ролей между локальным Git и gh при работе агента:

Инструмент	Операция Claude Code	Применяемые команды
Git	Инспекция и индексация	`git status`, `git diff`, `git add -p`
Git	Фиксация версий	`git commit -m "..."`, `git rebase`
GitHub CLI	Контекст задачи	`gh issue view 142`, `gh issue list`
GitHub CLI	Публикация и ревью	`gh pr create`, `gh pr view --comments`
GitHub CLI	Проверка CI пайплайнов	`gh run list`, `gh run view <id>`

Агентный цикл ревью и устранение замечаний

После публикации PR процесс разработки переходит в фазу обратной связи. Традиционно разработчик вручную копирует замечания тимлида из веб-интерфейса, ищет строки в коде, исправляет их и повторно пушит. С Claude Code этот цикл замыкается внутри терминала.

Сбор комментариев и точечные патчи

Агент считывает замечания из открытого Pull Request через команду gh pr view --comments или GraphQL API. Получив список тредов с замечаниями (например: «Замени any на строгий тип интерфейса OrderPayload» и «Добавь обработку таймаута для внешнего шлюза»), Claude Code выполняет следующий цикл:

Локализация контекста: поиск указанных файлов через GrepTool и чтение актуальных строк через View.
Внесение правок: точечная модификация интерфейсов и добавление параметров таймаута.
Локальная верификация: запуск линтера (npm run lint) и тестов.

Формирование корректирующего коммита:

git commit -am "fix(orders): address PR review comments on strict typing and timeout"
git push origin feat/export-orders-csv

Ответ в тред: публикация отчёта о проделанной работе через gh pr comment.

Разрешение merge-конфликтов под управлением агента

При параллельной работе нескольких разработчиков ветка неизбежно устаревает относительно main. При выполнении git rebase main возникают маркеры конфликтов. Для языковой модели маркеры слияния — это структурированная текстовая задача.

<<<<<<< HEAD
const timeoutMs = config.apiTimeout || 5000;
=======
const timeoutMs = options.timeout ?? DEFAULT_TIMEOUT;
>>>>>>> main

Алгоритм устранения конфликта через Claude Code

Инспекция состояния конфликтующих файлов: Агент запрашивает git status --porcelain для выявления файлов в состоянии UU (both modified).
Семантический анализ обеих ветвей: Модель сопоставляет логику входящей ветки (HEAD) и целевой ветки (main), чтобы объединить их без потери бизнес-требований (например, объединить новую систему конфигурации с дефолтным фолбэком).
Удаление маркеров и запись чистого файла: Файл перезаписывается без синтаксических артефактов <<<<<<<, =======, >>>>>>>.

Продолжение rebase:

git add src/config/network.ts
git rebase --continue

Важное правило безопасности: никогда не передавайте агенту команду git push --force без явного указания безопасного флага --force-with-lease. Это защитит удалённый репозиторий от перезаписи чужих коммитов, отправленных в ту же ветку.

Практический сценарий: от грязного рабочего дерева к чистому PR

Разберём сквозной пример. В репозитории интернет-магазина разработчик набросал прототип системы промокодов: изменены 5 файлов, добавлены миграция БД, эндпоинт и тест, но всё лежит в рабочей директории вперемешку.

Шаг 1. Перенос в новую ветку и семантическая фиксация

Подаём команду агенту:

claude -p "Создай ветку feat/promo-codes. Проанализируй изменённые файлы и разбей их на два логических коммита: миграцию со схемой и реализацию эндпоинта с тестами."

Claude Code выполняет:

git checkout -b feat/promo-codes
git add prisma/schema.prisma prisma/migrations/
git commit -m "feat(db): add PromoCode model and discount relation"
git add src/api/promo.ts tests/promo.test.ts
git commit -m "feat(api): implement promo code validation and checkout application"

Шаг 2. Верификация и открытие Pull Request

Следующий промпт автоматизирует отправку:

claude -p "Запусти тесты проекта. Если они зеленые, запушь ветку и открой PR в ветку main с подробным описанием изменений."

Агент выполняет тестовый прогон:

npm test -- tests/promo.test.ts

После успешного завершения ( $100\%$ pass) агент отправляет код на GitHub и открывает PR:

git push -u origin feat/promo-codes
gh pr create --title "feat(promo): implement discount and promo code engine" --body "### Summary
- Added database schema for promo codes with usage limits.
- Implemented `/api/promo/validate` endpoint with expiration checks.
- Covered with integration tests.

Closes #88"

В результате репозиторий получает чистую историю коммитов, связанную ветку и оформленный Pull Request без единого переключения в браузер.

Подключение локальных моделей и автоматизация рутины

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

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

Зачем переносить рутину в локальный контур

В ежедневной разработке до $70\%$ задач агента не требуют глубоких мультимодальных рассуждений. Это шаблонные операции: написание базовых модульных тестов по готовым контрактам, актуализация документации, типизация нетипизированного JavaScript и генерация моковых данных.

Критерий	Облачные модели (Claude 3.7 Sonnet / Opus)	Локальные модели (Qwen 2.5 Coder, DeepSeek)
Стоимость	Оплата за каждый миллион токенов	Бесплатно (только электроэнергия и оборудование)
Приватность	Данные обрабатываются внешним API	Код не покидает оперативную память машины
Задержка (TTFT)	Зависит от сети и очередей провайдера	Минимальная, ограничена только вашим GPU
Ограничения по рейтам	Лимиты запросов в минуту (RPM/TPM)	Полное отсутствие лимитов на запросы
Сложность рассуждений	Максимальная (системный дизайн, архитектура)	Высокая в рамках синтаксиса и локального контекста

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

Архитектура проксирования: от CLI к Ollama и vLLM

Интерфейс Claude Code изначально рассчитан на взаимодействие с конечной точкой Anthropic Messages API. Большинство локальных движков (Ollama, vLLM, llama.cpp, LocalAI) предоставляют эндпоинты в стандарте OpenAI Chat Completions API либо в собственном формате.

Чтобы связать CLI-агент с локальным движком, используется слой трансляции — прокси-сервер LiteLLM. Он принимает запросы в формате Anthropic, трансформирует структуру сообщений и вызовы инструментов (Tool Use) в формат целевой локальной модели, отправляет их на локальный порт и возвращает ответ агенту.

Шаг 1. Запуск локального бэкенда инференса

Самый простой способ развернуть открытую модель — использовать Ollama. После установки утилиты достаточно загрузить специализированную модель для работы с кодом:

ollama run qwen2.5-coder:14b

Для высоконагруженных сценариев и серверов с несколькими GPU стандартом является vLLM, обеспечивающий непрерывный батчинг (continuous batching) и высокую пропускную способность:

vllm serve Qwen/Qwen2.5-Coder-14B-Instruct --port 8000 --max-model-len 16384

Шаг 2. Развертывание шлюза LiteLLM

Установите и запустите LiteLLM Proxy, указав целевой бэкенд:

pip install 'litellm[proxy]'
litellm --model ollama_chat/qwen2.5-coder:14b --port 4000

Шаг 3. Перенаправление Claude Code

Переопределите сетевые переменные окружения перед запуском сессии агента:

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-local-proxy-stub"
claude

Ключевой инсайт: Claude Code воспринимает http://localhost:4000 как штатный сервер Anthropic. Переменная ANTHROPIC_API_KEY в таком сценарии может содержать любую непустую строку, если на прокси не включена внутренняя авторизация.

Выбор локальных моделей и расчет аппаратных ресурсов

Качество работы локального агента напрямую зависит от способности модели следовать инструкциям формата Tool Use. Не всякая открытая модель способна корректно формировать вызовы утилит чтения, поиска и редактирования файлов.

Наилучшие результаты в агентных сценариях показывают:

Qwen 2.5 Coder (7B, 14B, 32B) — эталонный открытый кодер с поддержкой контекста до 128k токенов и высокой точностью вызова функций.
DeepSeek Coder V2 Lite (16B) — архитектура Mixture of Experts (MoE) с 2.4B активных параметров, демонстрирующая высокую скорость генерации при умеренных требованиях к памяти.

Оценка требуемой видеопамяти (VRAM)

Чтобы загрузить модель и выделить пространство под контекст агента ( $16\text{k} - 32\text{k}$ токенов), используйте формулу расчета требуемой памяти:

VRAM \approx P \times B \times 1.25 + KV

Где:

$P$ — количество параметров модели в миллиардах (например, $14$ для 14B).
$B$ — вес одного параметра в байтах (для квантования 4-bit $B = 0.5$ байта; для 8-bit $B = 1$ байт; для 16-bit $B = 2$ байта).
$1.25$ — коэффициент накладных расходов фреймворка (буферы, тензоры активаций).
$KV$ — объем памяти для KV-кэша контекста (в среднем $2\text{–}4\text{ ГБ}$ для окна в $16000$ токенов).

Практический пример: Для модели Qwen 2.5 Coder 14B в квантовании 4-bit (Q4_K_M):

14 \times 0.5 \times 1.25 + 3 = 11.75\text{ ГБ}

Следовательно, модель комфортно помещается в потребительскую видеокарту с $12\text{–}16\text{ ГБ}$ VRAM (например, RTX 4080 или Apple Silicon Mac с объединенной памятью $18\text{–}24\text{ ГБ}$ ).

Автоматизация рутинных задач через Headless CLI

Главное преимущество связки локальной модели и Claude Code — возможность запускать неинтерактивные пакетные пайплайны без участия человека и без затрат на API.

Режим разовых команд с флагом -p (print mode) в комбинации с флагом автономности --dangerously-skip-permissions позволяет встраивать агента в стандартные Shell-скрипты, Makefile и Git-хуки.

Сценарий 1. Массовое добавление документации и типов

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

#!/usr/bin/env bash
set -euo pipefail

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="local"

find src/services -name "*.ts" | while read -r file; do
  echo "Обработка файла: $file"
  claude --dangerously-skip-permissions -p \
    "Добавь JSDoc-комментарии ко всем экспортируемым функциям в $file. Опиши параметры и возвращаемые типы. Не изменяй логику кода."
done

npm run lint

Сценарий 2. Локальный Pre-commit аудит безопасности

Интеграция в Git-хук .git/hooks/pre-commit предотвращает коммит случайных секретов и грубых уязвимостей до отправки кода в репозиторий:

#!/usr/bin/env bash

# Получаем список измененных файлов, готовых к коммиту
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)

if [ -z "$STAGED_FILES" ]; then
  exit 0
fi

echo "Локальный аудит безопасности перед коммитом..."
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="local"

AUDIT_PROMPT="Проверь следующие файлы на наличие жестко зашитых API-ключей, паролей и SQL-инъекций: $STAGED_FILES. Если нашел проблему — выведи описание и завершись с ошибкой."

claude --dangerously-skip-permissions -p "$AUDIT_PROMPT"

Проектирование двухуровневого воркфлоу

Чтобы не переключать конфигурации вручную, настройте терминальные профили в конфигурационном файле оболочки (~/.zshrc или ~/.bashrc):

# Профиль для тяжелых архитектурных задач (Cloud)
alias claude-cloud='unset ANTHROPIC_BASE_URL; export ANTHROPIC_MODEL="claude-3-7-sonnet-20250219"; claude'

# Профиль для локальной пакетной рутины (Local)
alias claude-local='export ANTHROPIC_BASE_URL="http://localhost:4000"; export ANTHROPIC_API_KEY="local"; export ANTHROPIC_MODEL="qwen2.5-coder:14b"; claude'

Такое разделение формирует законченный гибридный процесс: вы проектируете фичи и решаете сложные баги через claude-cloud, а рутинные тесты, рефакторинг стилей, аудит секретов и наполнение документации делегируете автономному claude-local.

Протокол MCP и интеграция внешних инструментов

Кастомные bash-скрипты и прямые вызовы CLI-утилит решают локальные задачи автоматизации, но быстро упираются в архитектурный тупик. Представьте, что агенту нужно одновременно работать с живой базой данных PostgreSQL, читать закрытую документацию из Confluence, трекать задачи в GitHub Issues и опрашивать систему мониторинга Sentry. Если писать отдельный адаптер под каждый инструмент и под каждую модель, возникает проблема комбинаторного взрыва: $M$ агентов, умноженные на $N$ сервисов, требуют создания $M \times N$ хрупких интеграций.

В ноябре 2024 года компания Anthropic представила Model Context Protocol (MCP) — открытый стандартизированный протокол взаимодействия ИИ-ассистентов с внешними источниками данных и исполняемыми средами. Подобно тому, как протокол LSP (Language Server Protocol) избавил редакторы кода от необходимости писать сотни парсеров для каждого языка программирования, MCP превращает Claude Code в универсальный хост, способный бесшовно подключать десятки готовых коннекторов без модификации базового кода агента.

Зачем нужен Model Context Protocol

До появления единого стандарта интеграция внешних систем с LLM строилась на написании ad-hoc инструментов (Function Calling) внутри каждого конкретного приложения. Это порождало дублирование кода, проблемы с безопасностью учетных записей и постоянные сбои при изменении форматов API.

Model Context Protocol (MCP) — это открытый клиент-серверный протокол с открытым исходным кодом, стандартизирующий передачу контекста, вызов функций и предоставление данных между приложениями-хостами (LLM-клиентами) и изолированными серверами инструментов.

В архитектуре MCP выделяются три ключевых участника:

MCP Host — приложение, координирующее работу языковой модели и управляющее пользовательским контекстом (в нашем случае это Claude Code CLI).
MCP Client — протокольный слой внутри хоста, который обнаруживает доступные серверы, запрашивает их возможности (capabilities) и транслирует вызовы.
MCP Server — независимый легковесный процесс или сервис, экспортирующий строго типизированные данные и функции через стандартизированный интерфейс.

При запуске сессии Claude Code обращается к зарегистрированным серверам, выполняет процедуру рукопожатия (handshake) и автоматически обогащает свой инструментарий новыми командами. Модель видит внешние серверы как естественное расширение собственных возможностей.

Анатомия протокола: Tools, Resources и Prompts

Протокол MCP оперирует тремя фундаментальными примитивами взаимодействия. Понимание их различий определяет, как именно агент будет взаимодействовать с целевой системой.

Примитив	Назначение	Кто инициирует	Аналог в разработке
Tools (Инструменты)	Выполнение действий, мутация данных, вызов API с передачей параметров	ИИ-модель (автономно в процессе reasoning-цикла)	Вызовы функций / RPC-методы
Resources (Ресурсы)	Чтение статического или динамического контекста по URI-схеме без побочных эффектов	Пользователь или хост-клиент	Файлы, GET-эндпоинты, схемы БД
Prompts (Промпты)	Шаблонизированные сценарии взаимодействия и готовые цепочки инструкций	Пользователь (через интерфейс хоста)	Слэш-команды, сниппеты

Разберем эти примитивы на практике:

Tools предназначены для выполнения вычислимых операций. Например, MCP-сервер базы данных может предоставить инструмент execute_sql с аргументом {"query": "SELECT * FROM orders WHERE total > 1000"}. Модель сама решает, когда и с какими аргументами вызвать этот инструмент.
Resources представляют собой данные, доступные только для чтения. Они идентифицируются по стандарту URI (например, postgres://public/schema/users или file:///logs/app.log). Ресурсы можно передавать напрямую в контекстное окно в виде неизменяемых срезов данных.
Prompts позволяют разработчикам серверов упаковывать сложные цепочки инструкций вместе с кодом. Например, сервер аудита безопасности может поставлять готовый промпт analyze-vulnerabilities, который автоматически подтягивает в контекст нужные логи и правила проверки.

Транспорты и конфигурация MCP в Claude Code

Связь между клиентом и серверами MCP осуществляется через транспортный уровень. Протокол специфицирует основные виды транспорта:

stdio (Standard Input/Output) — обмен сообщениями в формате JSON-RPC через стандартные потоки ввода-вывода дочернего процесса. Это основной и самый безопасный метод для локальной работы: Claude Code сам запускает бинарный файл или Node/Python-скрипт сервера как изолированный подпроцесс на машине.
HTTP / SSE (Server-Sent Events / Streamable HTTP) — клиент подключается к удаленному веб-серверу через HTTP (включая стриминг сообщений). Используется для взаимодействия с облачной инфраструктурой и корпоративными шлюзами.

Настройка конфигурации серверов

Claude Code считывает доступные MCP-серверы из конфигурационных файлов проекта или глобального профиля пользователя. В корне репозитория можно создать файл .mcp.json (проектная область видимости) или сконфигурировать серверы через команду claude mcp add / напрямую в ~/.claude.json.

Ниже приведен пример боевого файла конфигурации .mcp.json, подключающего сразу три источника: локальную базу данных PostgreSQL, файловый инспектор и сервер поисковой системы Brave:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://app_user:secret_pass@localhost:5432/analytics_db"
      ],
      "env": {
        "PGTIMEOUT": "5000"
      }
    },
    "web-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA_example_token_value"
      }
    },
    "filesystem-extra": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/var/log/nginx",
        "/opt/shared/data"
      ]
    }
  }
}

Разбор параметров конфигурации:

command — исполняемый файл для запуска подпроцесса (например, npx, python3, uvx или скомпилированный бинарник на Go/Rust).
args — список аргументов командной строки, включая имена пакетов, флаги и строки подключения.
env — изолированный набор переменных окружения, передаваемый исключительно данному подпроцессу. Это предотвращает утечку секретов в общий шелл.

Практический сценарий: инспекция базы данных и безопасная аналитика

Рассмотрим реальный сценарий: в проекте произошел сбой синхронизации заказов. Разработчику требуется выяснить структуру таблиц, найти битые записи и написать миграцию. Без MCP агенту пришлось бы вызывать psql через bash-команды, парсить неструктурированный текст терминала и рисковать выполнением деструктивных команд.

С подключенным PostgreSQL MCP-сервером диалог в терминале Claude Code выглядит принципиально иначе.

> claude
╭────────────────────────────────────────────────────────╮
│ Claude Code CLI (MCP Enabled)                          │
│ Connected servers: database (8 tools), web-search      │
╰────────────────────────────────────────────────────────╯

> Найди в базе данных analytics_db пять последних заказов со статусом 'failed',
  проверь структуру связанной таблицы транзакций и выясни причину ошибки.

Внутри агентного цикла происходят следующие шаги:

Schema Discovery: Claude Code автономно вызывает инструмент list_tables, получая структурированный список таблиц.
Type Inspection: Вызывает describe_table с аргументом {"table_name": "orders"} и describe_table для transactions.

Targeted Query: Формирует параметризованный SQL-запрос через инструмент query:

SELECT o.id, o.user_id, o.total_cents, t.error_code, t.raw_payload
FROM orders o
JOIN transactions t ON o.id = t.order_id
WHERE o.status = 'failed'
ORDER BY o.created_at DESC
LIMIT 5;

Analysis & Fix: Получив структурированный JSON-ответ от сервера базы данных, модель мгновенно локализует проблему (например, несоответствие длины поля error_code в схеме) и предлагает точечный патч для кода бэкенда.

Защита и разграничение прав доступа

При подключении внешних MCP-серверов к терминальному агенту критически важно соблюдать принцип наименьших привилегий (Principle of Least Privilege):

Read-Only учетные записи: для аналитических задач и аудита всегда используйте строку подключения с пользователем, имеющим только права SELECT.
Изоляция сетевого контура: запускайте базы данных и сервисы в тестовых контейнерах Docker или подключайтесь к staging-репликам, а не к production-кластеру напрямую.
Аудит вызовов инструментов: Claude Code запрашивает подтверждение на выполнение инструментов MCP, способных изменить состояние внешней системы, аналогично правилам безопасности терминальных команд.

Отладка и диагностика MCP-серверов

Если сервер не отвечает или выдает неожиданные ошибки, для изоляции проблемы используется специализированная утилита MCP Inspector. Она запускает интерактивный веб-интерфейс, позволяющий протестировать сервер без участия LLM:

npx @modelcontextprotocol/inspector npx @modelcontextprotocol/server-postgres postgresql://localhost:5432/test_db

Инспектор открывает локальную страницу в браузере (по умолчанию порт 5173 или 6274 в зависимости от версии), где можно:

вручную проверить список экспортируемых инструментов (Tools), ресурсов (Resources) и промптов (Prompts);
отправить тестовый вызов функции с кастомными JSON-параметрами;
просмотреть входящие и исходящие JSON-RPC пакеты в реальном времени;
зафиксировать ошибки сериализации данных или падения дочернего процесса.

Полноценное использование протокола MCP превращает Claude Code из локального скриптового помощника в оркестратор корпоративной инфраструктуры, способный безопасно и структурированно взаимодействовать с любыми сервисами компании.

Разработка пользовательских навыков (Skills)

Готовые MCP-серверы закрывают типовые сценарии — чтение баз данных, веб-поиск или работу с файловой системой. Однако рабочий процесс любой инженерной команды уникален: он завязан на внутренние микросервисы, закрытые корпоративные API, проверку статусов сборки в локальном кластере или специфические пайплайны развёртывания.

Когда встроенных возможностей CLI и внешних открытых серверов становится недостаточно, на сцену выходят пользовательские навыки (Skills). Навык — это специализированный инструмент или набор инструментов, реализованный в виде легковесного локального MCP-сервера, который расширяет контекст и инструментарий Claude Code именно теми функциями, которые нужны вашему проекту.

Анатомия навыка: от bash-команды к детерминированному API

В простейшем случае автоматизировать задачу можно строкой в CLAUDE.md, заставив агента запускать bash-скрипт. Но у такого подхода есть фундаментальные ограничения:

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

Пользовательский навык на базе протокола MCP решает эти проблемы за счёт строгой типизации входных параметров и стандартизированного протокола обмена сообщениями.

Пользовательский навык состоит из трёх ключевых компонентов:

Декларация схемы (Schema) — описание инструмента, его аргументов и их типов в формате JSON Schema (часто формируемое с помощью библиотек валидации вроде Zod).
Обработчик выполнения (Handler) — изолированная функция на Node.js/TypeScript или Python, которая принимает проверенные аргументы и выполняет бизнес-логику (обращение к API, чтение локальных сокетов, выполнение расчётов).
Транспорт (Transport) — механизм передачи данных через стандартные потоки stdio, связывающий процесс сервера с Claude Code.

Создание собственного MCP-сервера на TypeScript

Официальный SDK @modelcontextprotocol/sdk предоставляет высокоуровневый класс McpServer, который берёт на себя маршрутизацию JSON-RPC сообщений, сериализацию ответов и валидацию входящих аргументов.

Инициализируем проект для пользовательского сервера:

mkdir my-claude-skills
cd my-claude-skills
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx
npx tsc --init

Создадим сервер, реализующий два навыка: генерацию диагностического отчёта по ветке Git и отправку уведомлений во внутренний вебхук команды.

Создайте файл src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { execSync } from "node:child_process";

// Инициализация сервера с указанием имени и версии
const server = new McpServer({
  name: "dev-team-skills",
  version: "1.0.0",
});

// Регистрация инструмента анализа статуса окружения
server.tool(
  "inspect_environment",
  "Возвращает сводку по текущей ветке git, хешу коммита и статусу сборки",
  {
    includeLogs: z.boolean().default(false).describe("Включать ли последние 3 коммита в отчет"),
  },
  async ({ includeLogs }) => {
    try {
      const branch = execSync("git rev-parse --abbrev-ref HEAD").toString().trim();
      const commit = execSync("git rev-parse --short HEAD").toString().trim();

      let details = `Ветка: ${branch}\nКоммит: ${commit}`;

      if (includeLogs) {
        const logs = execSync("git log -n 3 --oneline").toString().trim();
        details += `\nПоследние коммиты:\n${logs}`;
      }

      return {
        content: [
          {
            type: "text",
            text: details,
          },
        ],
      };
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
      return {
        isError: true,
        content: [
          {
            type: "text",
            text: `Ошибка при сборе информации окружения: ${message}`,
          },
        ],
      };
    }
  }
);

// Запуск сервера через стандартные потоки ввода-вывода (stdio)
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch((error) => {
  console.error("Критическая ошибка запуска MCP-сервера:", error);
  process.exit(1);
});

В этой архитектуре Claude Code не выполняет сырые bash-команды напрямую в вашей системе. Модель вызывает типизированный метод inspect_environment, а сервер контролирует исполнение команд и форматирует результат.

Проектирование контракта: как модель понимает инструмент

Языковая модель не видит исходный код функции. Единственное руководство к действию для неё — это манифест инструмента: имя, текстовое описание (description) и схема параметров.

Качество описания напрямую определяет, когда и с какими данными Claude решит вызвать ваш навык.

Элемент схемы	Антипаттерн (плохо)	Эталон (хорошо)
Имя инструмента	`do_stuff`, `helper_1`	`deploy_to_staging`, `query_user_metrics`
Описание инструмента	"Работает с базой"	"Выполняет параметризованный поиск активных пользователей по диапазону дат и статусу подписки"
Описание параметра	`id` (без пояснения)	"Уникальный UUID заказа в формате 8-4-4-4-12 символов"
Ограничения типов	`z.string()` для всего подряд	`z.enum(["dev", "stage", "prod"])`, `z.number().int().positive()`

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

Обработка ошибок и флаг `isError`

Одна из ключевых особенностей MCP-протокола — разграничение системных ошибок протокола и ошибок бизнес-логики инструмента.

Когда инструмент падает с исключением или внешнее API возвращает код 404/500, нельзя ронять процесс сервера через process.exit() или выбрасывать необработанный throw Error. Если процесс завершится, канал stdio закроется, и Claude Code полностью потеряет соединение с сервером.

Вместо падения сервер обязан вернуть объект с флагом isError: true:

server.tool(
  "fetch_api_data",
  "Запрашивает данные из закрытого API сервиса",
  { endpoint: z.string() },
  async ({ endpoint }) => {
    const response = await fetch(`https://internal.api.local/${endpoint}`);

    if (!response.ok) {
      return {
        isError: true,
        content: [
          {
            type: "text",
            text: `API вернуло статус ${response.status}: ${response.statusText}. Проверьте правильность endpoint.`,
          },
        ],
      };
    }

    const data = await response.json();
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(data),
        },
      ],
    };
  }
);

Флаг isError: true сигнализирует Claude Code, что вызов был доставлен, но операция не увенчалась успехом. Получив осмысленное текстовое описание причины сбоя, модель способна сама исправить аргументы (например, скорректировать путь endpoint) и повторить вызов в следующем шаге агентного цикла.

Регистрация и проверка навыка в Claude Code

После написания кода сервера его необходимо зарегистрировать в конфигурации проекта.

Скомпилируем TypeScript или воспользуемся tsx для прямого запуска без предварительной сборки. Добавим сервер в конфигурационный файл .mcp.json в корне целевого репозитория:

{
  "mcpServers": {
    "team-skills": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/my-claude-skills/src/index.ts"],
      "env": {
        "INTERNAL_API_KEY": "sk-internal-secret-token"
      }
    }
  }
}

Важно: Всегда указывайте абсолютный путь к исполняемому файлу сервера или используйте пакеты, установленные локально в node_modules. При запуске сессии Claude Code поднимает сервер как изолированный дочерний процесс.

Теперь при запуске интерактивной сессии claude агент автоматически обнаружит зарегистрированные инструменты:

$ claude
╭────────────────────────────────────────────────────────╮
│ Claude Code CLI (v0.2.x)                               │
│ MCP servers connected: team-skills (1 tool)           │
╰────────────────────────────────────────────────────────╯

> Собери отчет по текущему состоянию ветки и коммитам

● Calling tool: inspect_environment (team-skills)
  └ includeLogs: true

  Результат:
  Ветка: feature/auth-redesign
  Коммит: a8f12c4
  Последние коммиты:
  a8f12c4 feat: add OAuth callback handler
  41b9e01 refactor: migrate token storage
  d903aa2 chore: update auth dependencies

Текущая ветка feature/auth-redesign находится на коммите a8f12c4. Последние изменения связаны с доработкой механизма OAuth-авторизации.

Навыки превращают Claude Code из универсального текстового ассистента в узкоспециализированного инженера вашей команды, знающего правила, внутренние интерфейсы и ограничения вашей инфраструктуры.

Построение контент-завода и цепочек процессов

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

Контент-завод — это автоматизированный конвейер (pipeline), где сложная комплексная задача разбивается на детерминированные последовательные этапы, а Claude Code в пакетном режиме (claude -p) выступает специализированным исполнителем на каждом шаге, используя созданные ранее MCP-навыки.

Анатомия агентного конвейера

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

Типовой контент-завод состоит из пяти связанных фаз:

Сбор и нормализация (Ingestion): извлечение сырых данных (логи, выгрузки БД, markdown-файлы, спецификации API) через навигационные инструменты или MCP-серверы.
Анализ и структурирование (Extraction & Planning): выявление ключевых сущностей, построение оглавления или карты связей.
Генерация контента (Drafting): пошаговое создание текста, кода или документации по утвержденной структуре.
Валидация и критика (Verification & Linting): автоматическая проверка сгенерированных артефактов на соответствие схемам, фактам и код-стайлу.
Сборка и публикация (Assembly & Output): сведение частей в итоговый результат, генерация оглавлений и сохранение в файловую систему или Git-репозиторий.

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

Контракты данных и идемпотентность

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

Контракт данных — это зафиксированная спецификация формата обмена между шагами конвейера. Если вывод этапа не проходит валидацию схемы, конвейер останавливается до запуска следующего шага.

При пакетной обработке десятков или сотен сущностей неизбежно возникают сбои: исчерпание лимитов API (rate limits), временные сетевые ошибки или некорректные ответы модели. Чтобы сбой на 95-м шаге из 100 не заставлял перезапускать весь процесс с нуля, пайплайн должен обладать свойством идемпотентности.

my-pipeline/
├── data/
│   ├── 01_raw/             # Исходные файлы
│   ├── 02_extracted/       # Извлеченные структуры (JSON)
│   ├── 03_generated/       # Черновики страниц (Markdown)
│   └── 04_verified/        # Проверенные итоговые артефакты
├── state.json              # Реестр статусов обработки
└── run-pipeline.ts         # Оркестратор конвейера

Реестр состояний (state.json) сохраняет контрольные точки (checkpoints) для каждого обрабатываемого элемента. Перед запуском задачи оркестратор проверяет статус: если элемент уже находится в статусе completed или verified, этап пропускается.

Оркестрация через headless-режим и MCP-навыки

Для автоматизации конвейера используется скрипт-оркестратор (на Node.js, Python или Bash), который запускает Claude Code в автономном пакетном режиме через флаг -p (--print), комбинируя его с флагом --dangerously-skip-permissions для исключения ручных подтверждений в терминале.

Связка оркестратора и Claude Code строится следующим образом:

Оркестратор готовит изолированное окружение и параметры.
Claude Code вызывается как дочерний процесс операционной системы (child_process.spawn или execSync).
Через флаг --model задается оптимальная модель: быстрая и дешевая для первичной фильтрации, мощная — для синтеза и проверки.
Модель получает доступ к инструментам проекта, зарегистрированным в .mcp.json.

Посмотрим, как выглядит динамика выполнения шагов конвейера при пакетной обработке, включая накопление стоимости и автоматический перезапуск при сбоях.

Практическая реализация: конвейер генерации технической документации

Разберем оркестратор на TypeScript, который выполняет конвейерную обработку сырых спецификаций модулей в чистую, проверенную документацию с сохранением контрольных точек.

import { execSync } from "node:child_process";
import * as fs from "node:fs";
import * as path from "node:path";

interface PipelineItem {
  id: string;
  sourceFile: string;
  status: "pending" | "extracted" | "drafted" | "verified" | "failed";
  error?: string;
}

interface StateStore {
  items: Record<string, PipelineItem>;
}

const STATE_FILE = path.join(process.cwd(), "state.json");

function loadState(): StateStore {
  if (fs.existsSync(STATE_FILE)) {
    return JSON.parse(fs.readFileSync(STATE_FILE, "utf-8"));
  }
  return { items: {} };
}

function saveState(state: StateStore): void {
  fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
}

function runClaudeStep(prompt: string, model: string = "claude-3-5-sonnet-20241022"): string {
  const escapedPrompt = prompt.replace(/"/g, '\\"');
  const command = `claude -p "${escapedPrompt}" --model ${model} --dangerously-skip-permissions`;

  return execSync(command, {
    encoding: "utf-8",
    maxBuffer: 10 * 1024 * 1024,
    env: { ...process.env }
  });
}

async function runPipeline() {
  const state = loadState();
  const sourceFiles = fs.readdirSync("data/01_raw");

  // Инициализация новых элементов
  for (const file of sourceFiles) {
    const id = path.parse(file).name;
    if (!state.items[id]) {
      state.items[id] = { id, sourceFile: file, status: "pending" };
    }
  }
  saveState(state);

  for (const item of Object.values(state.items)) {
    try {
      // Шаг 1: Извлечение схемы и сигнатур (быстрая модель)
      if (item.status === "pending") {
        console.log(`[1/3] Извлечение метаданных: ${item.id}`);
        const prompt = `Прочитай файл data/01_raw/${item.sourceFile}. Извлеки список всех экспортируемых функций, их типов аргументов и возвращаемых значений. Сохрани результат СТРОГО в формате валидного JSON в файл data/02_extracted/${item.id}.json. Не пиши никакого сопроводительного текста, только JSON.`;

        runClaudeStep(prompt, "claude-3-5-haiku-20241022");
        item.status = "extracted";
        saveState(state);
      }

      // Шаг 2: Генерация документации (мощная модель с MCP-навыком валидации)
      if (item.status === "extracted") {
        console.log(`[2/3] Генерация документации: ${item.id}`);
        const prompt = `На основе извлеченной схемы data/02_extracted/${item.id}.json составь подробное руководство разработчика на русском языке. Опиши назначение, каждый аргумент с примером и возможные ошибки. Сохрани итоговый текст в data/03_generated/${item.id}.md.`;

        runClaudeStep(prompt, "claude-3-5-sonnet-20241022");
        item.status = "drafted";
        saveState(state);
      }

      // Шаг 3: Верификация и линтинг
      if (item.status === "drafted") {
        console.log(`[3/3] Верификация артефакта: ${item.id}`);
        const prompt = `Проверь файл data/03_generated/${item.id}.md. Убедись, что все примеры кода валидны синтаксически, заголовки следуют стандарту и нет пустых разделов. Если найдены неточности — исправь файл на месте. Если всё корректно — скопируй файл в data/04_verified/${item.id}.md.`;

        runClaudeStep(prompt, "claude-3-5-sonnet-20241022");
        item.status = "verified";
        saveState(state);
      }
    } catch (err: unknown) {
      const errorMessage = err instanceof Error ? err.message : String(err);
      console.error(`Ошибка при обработке ${item.id}:`, errorMessage);
      item.status = "failed";
      item.error = errorMessage;
      saveState(state);
    }
  }

  console.log("Конвейер завершил работу.");
}

runPipeline();

В приведенном пайплайне ключевую роль играет распределение ролей:

На первом шаге вызывается модель семейства Haiku — она быстро и с минимальными затратами выполняет чисто синтаксическую работу по парсингу исходников в JSON.
На втором шаге подключается модель Sonnet, которая разворачивает структурированные данные в полноценный технический текст.
На третьем шаге запускается аудит с автономным исправлением выявленных недочетов.

Защитные механизмы и контроль затрат

Автоматизированные конвейеры способны за считанные минуты отправить сотни запросов к API. Чтобы процесс оставался контролируемым и экономически оправданным, внедряются три защитных механизма:

Механизм	Назначение	Реализация
Экспоненциальная задержка (Backoff)	Предотвращение ошибок 429 (Rate Limit)	Увеличение паузы между повторными попытками: $t_{\text{wait}} = 2^k \times 1000\text{ мс}$ , где $k$ — номер попытки
Лимит контекста на шаг	Защита от раздувания истории токенов	Изолированный вызов `claude -p` на каждый шаг вместо одной бесконечной сессии
Circuit Breaker	Остановка конвейера при систематических сбоях	Прерывание цикла, если более 3 элементов подряд завершились со статусом `failed`

Формула экспоненциальной задержки $t_{\text{wait}} = 2^k \times 1000\text{ мс}$ обеспечивает прогрессивное увеличение времени ожидания. Например, при первой ошибке ( $k = 1$ ) скрипт подождет $2^1 \times 1000 = 2000\text{ мс}$ (2 секунды), при второй ( $k = 2$ ) — $2^2 \times 1000 = 4000\text{ мс}$ (4 секунды), а при третьей ( $k = 3$ ) — уже 8 секунд. Это позволяет API восстановить лимиты без перегрузки сервиса повторными запросами.

Построенный таким образом конвейер трансформирует Claude Code из интерактивного ассистента в надежный бэкенд-движок, способный автономно перерабатывать масштабные объемы данных без деградации качества и потери контроля над расходами.

Мультиагентные системы и Claude Agents Team

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

Линейные конвейеры решают проблему фрагментации данных, но пасуют перед недетерминированными задачами, где требуется обратная связь, споры и встречная критика. Решением становится переход от одиночного исполнителя к мультиагентной команде (Multi-Agent System) — ансамблю узкоспециализированных инстансов Claude Code, каждый из которых обладает собственной ролью, изолированным контекстом и специфическим набором инструментов.

От одиночного агента к разделению ролей

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

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

Параметр	Универсальный агент (Single-Agent)	Мультиагентная команда (Multi-Agent Team)
Контекстное окно	Единое, быстро деградирует из-за накопления разнородных данных	Изолированное у каждого агента; передаются только итоговые артефакты
Системный промпт	Перегружен десятками разнородных инструкций и правил	Компактный, сфокусирован на одной зоне ответственности
Инструменты (Tools)	Подключены десятки MCP-серверов, риск ложного выбора инструмента	Минимальный рабочий набор утилит под конкретную роль
Критика решений	Самопроверка через ту же сессию (низкая объективность)	Внешняя верификация изолированным агентом-критиком
Стоимость токенов	Растёт квадратично от длины единой истории сообщений	Линейный рост по каждому изолированному шагу

Анатомия ролевой модели

В устойчивой инженерной команде Claude Code выделяются четыре ключевые роли:

Lead / Supervisor (Координатор) — декомпозирует высокоуровневую цель на подзадачи, формирует технические контракты, назначает исполнителей и принимает финальный результат. Не пишет прикладной код.
Implementer / Coder (Разработчик) — получает спецификацию и файлы контрактов. Пишет код, используя встроенные инструменты (Read, Edit, Write), вносит изменения в репозиторий.
Tester / QA (Инженер по тестированию) — получает ветку или дифф, генерирует тест-кейсы, запускает линтеры и тестовые раннеры. Не исправляет код сам, а формирует структурированный отчёт об ошибках (Bug Report).
Security Auditor / Reviewer (Рецензент) — анализирует изменения на соответствие стандартам безопасности (OWASP, утечки секретов, сложность алгоритмов), накладывает вето или даёт подтверждение на мердж.

Архитектурные топологии: как связать агентов

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

1. Иерархическая (Supervisor)    2. Одноранговая (Mesh)    3. Доска объявлений (Blackboard)

        [Supervisor]                   [Agent A]                     [Agent A]   [Agent B]
         /    |     \                   /     \                          \     /
    [Coder] [QA] [Reviewer]        [Agent B] — [Agent C]            [ === Shared DB === ]
                                                                     /     \
                                                                [Agent C]   [Agent D]

Иерархическая топология (Supervisor-Worker)

Центральный агент-оркестратор принимает пользовательский запрос, формирует план в виде направленного ациклического графа (DAG) и поочерёдно вызывает рабочих агентов через дочерние процессы CLI (claude -p). Рабочие агенты не общаются друг с другом напрямую — они возвращают результат супервизору.

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

Одноранговая сеть (Mesh)

Агенты передают контекст друг другу напрямую через цепочку делегирования (Handoff). Например, Планировщик передаёт управление Разработчику, тот вызывает Тестировщика, а Тестировщик возвращает задачу Разработчику при падении сборки. Без жёстких программных ограничений топология Mesh склонна к бесконечным циклам рассуждений и лавинообразному расходу токенов.

Паттерн «Доска объявлений» (Blackboard)

Агенты не общаются через сообщения, а считывают и модифицируют общее состояние (файловую систему, SQLite или Redis-хранилище). Супервизор публикует задачу со статусом pending. Агент-разработчик забирает её в работу, меняет статус на implemented и сохраняет дифф. Агент-тестировщик подхватывает обновлённый артефакт.

Механизм делегирования и Handoff через CLI

Чтобы запустить мультиагентную связку на базе Claude Code, не требуются тяжеловесные фреймворки. Оркестрацию можно реализовать программно на Node.js / TypeScript, управляя дочерними процессами claude с изолированными конфигурациями.

Ключевой приём заключается в создании специализированных профилей инструкций (ролевых CLAUDE.md) и вызове агентов в автономном режиме без интерактивного ввода.

Реализация ролевого оркестратора

Создадим структуру, где оркестратор координирует работу Разработчика и Рецензента, управляя циклом доработок.

Спецификация ролей задаётся через изолированные промпты:

// roles.ts
export interface AgentRole {
  name: string;
  systemPrompt: string;
  allowedTools: string;
}

export const CODER_ROLE: AgentRole = {
  name: "Coder",
  systemPrompt: `Ты — старший инженер-разработчик.
Твоя задача — вносить минимальные, точные изменения в кодовую базу строго по ТЗ.
Обязательно запускай локальную проверку синтаксиса перед завершением работы.`,
  allowedTools: "Read,Edit,Write,Glob,Grep,Bash"
};

export const REVIEWER_ROLE: AgentRole = {
  name: "Reviewer",
  systemPrompt: `Ты — строгий архитектор и аудитор безопасности.
Твоя задача — изучить git diff и найти потенциальные баги, уязвимости или нарушения типов.
Если замечаний нет, твой ответ ОБЯЗАН начинаться со слова "APPROVED".
Если есть ошибки, верни структурированный список правок с префиксом "REJECTED:".`,
  allowedTools: "Read,Glob,Grep,Bash"
};

Диспетчер задач запускает изолированные сессии Claude Code:

// runner.ts
import { execSync } from "child_process";
import * as fs from "fs";

export function runAgent(role: AgentRole, taskPrompt: string): string {
  // Формируем изолированное окружение с инструкцией роли
  const tempPromptFile = `.claude_prompt_${role.name}.tmp`;
  fs.writeFileSync(tempPromptFile, `${role.systemPrompt}\n\nЗАДАЧА:\n${taskPrompt}`);

  try {
    const command = `claude -p --allowedTools ${role.allowedTools} --dangerously-skip-permissions < ${tempPromptFile}`;
    const output = execSync(command, {
      encoding: "utf-8",
      maxBuffer: 10 * 1024 * 1024,
      env: {
        ...process.env,
        // Защищаем сессию от влияния глобального пользовательского контекста
        CLAUDE_CONFIG_DIR: `./.agents/${role.name}`
      }
    });
    return output.trim();
  } finally {
    if (fs.existsSync(tempPromptFile)) {
      fs.unlinkSync(tempPromptFile);
    }
  }
}

Основной цикл итеративного согласования:

// team_orchestrator.ts
import { runAgent, CODER_ROLE, REVIEWER_ROLE } from "./runner";
import { execSync } from "child_process";

async function executeFeature(taskDescription: string) {
  const MAX_ITERATIONS = 3;
  let iteration = 0;
  let feedback = "";
  let isApproved = false;

  console.log(`[Supervisor] Старт реализации задачи: "${taskDescription}"`);

  while (iteration < MAX_ITERATIONS && !isApproved) {
    iteration++;
    console.log(`\n--- Итерация ${iteration} ---`);

    // 1. Агент-разработчик вносит правки
    const coderTask = iteration === 1
      ? taskDescription
      : `Исправь замечания ревьюера:\n${feedback}\nИсходная задача:\n${taskDescription}`;

    console.log(`[Coder] Выполняет задачу...`);
    runAgent(CODER_ROLE, coderTask);

    // Получаем фактический дифф изменений
    const diff = execSync("git diff HEAD~1..HEAD || git diff", { encoding: "utf-8" });

    // 2. Агент-рецензент проверяет результат
    console.log(`[Reviewer] Анализирует дифф (${diff.length} байт)...`);
    const reviewTask = `Проанализируй следующие изменения и вынеси вердикт:\n\n${diff}`;
    const reviewResult = runAgent(REVIEWER_ROLE, reviewTask);

    if (reviewResult.startsWith("APPROVED")) {
      console.log(`[Supervisor] Изменения согласованы рецензентом!`);
      isApproved = true;
    } else {
      console.log(`[Supervisor] Рецензент запросил доработки.`);
      feedback = reviewResult;
    }
  }

  if (!isApproved) {
    throw new Error(`[Supervisor] Превышен лимит итераций (${MAX_ITERATIONS}). Требуется вмешательство человека.`);
  }
}

Управление памятью и предотвращение антипаттернов

При проектировании ансамблей агентов возникают специфические системные сбои, отсутствующие в классическом программировании.

1. Пинг-понг согласований (Infinite Review Loop)

Ситуация, когда Разработчик и Рецензент зацикливаются на бесконечных мелких правках (например, переименование переменной туда и обратно из-за разной интерпретации стиля).

Решение:

Жёсткий программный лимит итераций ( $N \leq 3$ ).
Включение порога строгости: на 3-й итерации Рецензенту запрещается отклонять код по стилистическим критериям, разрешены только блокирующие баги (severity: critical).

2. Конкуренция за файловую систему (Resource Contention)

Если запустить двух агентов параллельно на одной ветке, они затрут правки друг друга при одновременном вызове Edit / Write.

Решение:

Изоляция рабочих пространств: параллельные агенты работают в независимых Git-ветках (worktrees) или временных директориях.
Слияние результатов через выделенный этап интеграции, управляемый Супервизором.

3. Загрязнение контекста артефактами (Artifact Bloat)

Передача всего тела изменённых файлов между агентами быстро расходует контекст.

Решение:

Использование диффов (git diff) вместо полных файлов для агентов аудита.
Сохранение промежуточных данных на диск и передача между агентами только ссылок на файлы (URIs) и компактных сводок (Summaries).

Проектирование контрактов взаимодействия

Для стабильной работы агентов их диалог должен быть строго типизирован. Свободный текст порождает двусмысленность. Взаимодействие между агентами выстраивается по схеме «Запрос — Артефакт — Верификация».

+-------------------+       Task Contract (JSON)      +-------------------+
|                   | ------------------------------> |                   |
|    Supervisor     |                                 |   Coder / Worker  |
|                   | <------------------------------ |                   |
+-------------------+       Execution Summary (JSON)  +-------------------+
          |
          | Git Diff + Audit Scope
          v
+-------------------+
|                   |
| Reviewer / Audit  | ----> Verdict: { status: "APPROVED" | "REJECTED", issues: [] }
|                   |
+-------------------+

Пример контракта задачи (task.json), формируемого Супервизором для Разработчика:

{
  "taskId": "AUTH-042",
  "goal": "Внедрить проверку срока жизни JWT токена",
  "targetFiles": ["src/middleware/auth.ts", "src/utils/jwt.ts"],
  "acceptanceCriteria": [
    "Токены с истекшим exp возвращают HTTP 401 Unauthorized",
    "Тест npm run test:auth завершается без ошибок",
    "Не изменяются сигнатуры публичных методов в auth.ts"
  ]
}

Агент-разработчик возвращает отчёт об исполнении:

{
  "taskId": "AUTH-042",
  "status": "COMPLETED",
  "modifiedFiles": ["src/middleware/auth.ts"],
  "testExecutionOutput": "PASS src/middleware/auth.test.ts (4 tests passed)",
  "notesForReviewer": "Добавлена проверка Math.floor(Date.now() / 1000) > payload.exp"
}

Такая структура исключает субъективные интерпретации: Рецензент сверяет отчёт Разработчика напрямую со списком acceptanceCriteria, не тратя токены на повторный поиск файлов по всему репозиторию.

Мультиагентный подход превращает Claude Code из умного автодополнения в автономную инженерную группу, способную решать архитектурно сложные задачи с контролируемым качеством кода.

Тестирование и отладка работы агентных цепочек

Когда одиночный скрипт падает с ошибкой, стек вызовов немедленно указывает на конкретную строчку кода. Но что делать, когда мультиагентный пайплайн из пяти звеньев успешно отработал без единого аварийного завершения процесса, потратил три доллара на API-запросы, но на выходе выдал синтаксически корректный, однако абсолютно неработоспособный результат? Ошибка в недетерминированной системе может зародиться на втором шаге из-за двусмысленной инструкции, усилиться при передаче контекста (handoff) на четвёртом и проявиться лишь в финальном артефакте.

Тестирование агентных цепочек требует принципиального пересмотра классической пирамиды тестирования: вместо проверки одного лишь детерминированного кода нам необходимо верифицировать поведение вероятностных моделей, корректность выбора инструментов (tool calling) и сохранность контрактов данных между агентами.

Пирамида тестирования агентных систем

В традиционной разработке фундамент тестирования составляют быстрые и дешёвые модульные тесты (unit tests). В агентных архитектурах этот фундамент делится на два изолированных слоя: детерминированные проверки инфраструктуры и вероятностные оценки поведения моделей.

Разберём каждый уровень пирамиды снизу вверх:

Детерминированные Unit-тесты инструментов и парсеров. Проверяют код, выполняемый внутри обработчиков навыков (MCP-серверов), валидаторы входных схем и функции извлечения структурированных данных. Здесь вообще не вызывается нейросеть: тесты выполняются за миллисекунды и стоят 0 USD.
Изолированные тесты агентов с мокированием (Mocked Agent Tests). Проверяют реакцию агента на зафиксированные ответы среды или симулируют ответы LLM для проверки логики оркестратора.
Оценка качества отдельного шага (Single-Step Evals). Агенту подаётся изолированный контекст и проверяется, какой инструмент он выбрал (tool selection) и какие аргументы сгенерировал.
Интеграционные тесты контрактов Handoff. Проверка передачи артефактов между специализированными агентами (например, сформировал ли Coder корректный task.json, который ожидает Tester).
Сквозные прогоны по золотому датасету (End-to-End Evals). Запуск всей цепочки на репрезентативном наборе эталонных задач с автоматической оценкой результата.

Изоляция и мокирование: детерминированный прогон без затрат на токены

Запуск полной языковой модели при каждом коммите в репозиторий приводит к двум проблемам: высокой стоимости прогона и нестабильности (flakiness) тестов из-за стохастической природы генерации. Чтобы сделать агентную систему тестируемой в CI/CD, применяется паттерн Record & Replay (запись и воспроизведение) либо подмена зависимостей на уровне вызовов инструментов.

Рассмотрим, как протестировать логику валидации аргументов для инструмента без реального обращения к LLM. Для этого создаётся детерминированная фикстура:

import { z } from "zod";

// Схема контракта задачи от супервизора к исполнителю
export const TaskHandoffSchema = z.object({
  taskId: z.string().uuid(),
  targetFile: z.string().regex(/\.(ts|js|py)$/, "Недопустимое расширение файла"),
  action: z.enum(["create", "modify", "delete"]),
  requirements: z.array(z.string()).nonempty("Список требований не может быть пустым"),
  testCriteria: z.string().min(10, "Критерии проверки должны быть описаны подробно")
});

export type TaskHandoff = z.infer<typeof TaskHandoffSchema>;

// Функция верификации контракта перед запуском подпроцесса
export function validateHandoffPayload(rawJson: unknown): TaskHandoff {
  const result = TaskHandoffSchema.safeParse(rawJson);
  if (!result.success) {
    const errorDetails = result.error.errors
      .map(err => `${err.path.join(".")}: ${err.message}`)
      .join("; ");
    throw new Error(`Нарушение контракта handoff: ${errorDetails}`);
  }
  return result.data;
}

Модульный тест для такой валидации мгновенно отлавливает попытку агента передать невалидный путь или пропустить критерии проверки:

import { describe, it, expect } from "vitest";
import { validateHandoffPayload } from "./handoffValidator";

describe("Валидация передачи контекста между агентами", () => {
  it("успешно пропускает валидный контракт", () => {
    const validPayload = {
      taskId: "550e8400-e29b-41d4-a716-446655440000",
      targetFile: "src/utils/calc.ts",
      action: "modify",
      requirements: ["Добавить округление до 2 знаков"],
      testCriteria: "Покрытие unit-тестами функции roundToTwo"
    };

    expect(() => validateHandoffPayload(validPayload)).not.toThrow();
  });

  it("выбрасывает ошибку при некорректном расширении файла", () => {
    const invalidPayload = {
      taskId: "550e8400-e29b-41d4-a716-446655440000",
      targetFile: "src/utils/calc.exe",
      action: "create",
      requirements: ["Скомпилировать бинарник"],
      testCriteria: "Запуск через execSync"
    };

    expect(() => validateHandoffPayload(invalidPayload)).toThrow(
      /Недопустимое расширение файла/
    );
  });
});

Трейсинг и структурированное логирование

Когда ошибка всё же возникает в рантайме, текстового вывода консоли недостаточно. В сложных цепочках необходимо регистрировать каждый шаг агентного цикла: рассуждение (Thought), вызов инструмента (Action), ответ окружения (Observation) и изменения на диске.

Агентный трейс (Execution Trace) — хронологический структурированный журнал всех внутренних состояний, промежуточных решений, аргументов вызова функций и системных ответов в ходе выполнения задачи.

Каждый вызов подпроцесса claude -p или кастомного оркестратора должен оборачиваться в сборщик телеметрии, сохраняющий снимок шага в формате JSON Lines (traces.jsonl):

{
  "traceId": "tr-8941a",
  "step": 3,
  "agentRole": "Coder",
  "timestamp": "2025-02-28T14:20:11.104Z",
  "inputPromptTokens": 1420,
  "outputTokens": 215,
  "thought": "Для исправления ошибки импорта необходимо проверить пути в tsconfig.json",
  "toolCall": {
    "name": "View",
    "args": { "file_path": "tsconfig.json", "limit": 30 }
  },
  "toolResult": { "status": "success", "linesRead": 30 },
  "durationMs": 840
}

Наличие структурированного трейса позволяет визуализировать ход рассуждений и локализовать момент, где агент отклонился от цели или вошёл в зацикливание.

Оценка качества: LLM-as-a-Judge и метрики эвалюации

Для проверки смысловой корректности кода или документации детерминированных assert недостаточно. Здесь применяется подход LLM-as-a-Judge: отдельная независимая языковая модель (обычно более мощная модель с нулевой температурой) оценивает результат работы цепочки по строгой рубрике.

Метрики качества агентной цепочки

В отличие от классического машинного обучения с метриками вроде $F_1$ -score или точности классификации, для агентных пайплайнов рассчитываются операционные и качественные показатели:

Метрика	Формула / Способ расчёта	Что показывает
Task Completion Rate (TCR)	$\text{TCR} = \frac{N_{\text{success}}}{N_{\text{total}}}$	Доля задач из тестового набора, решённых без вмешательства человека
Tool Selection Accuracy	$\text{TSA} = \frac{\text{Верно выбранные инструменты}}{\text{Всего вызовов инструментов}}$	Точность выбора нужного инструмента на каждом шаге цикла
Step Efficiency	$\text{SE} = \frac{\text{Минимально необходимые шаги}}{\text{Фактически затраченные шаги}}$	Степень отсутствия лишних блужданий и холостых вызовов
Cost per Task (CPT)	$\text{CPT} = \frac{\sum (\text{Входные токены} \times P_{\text{in}} + \text{Выходные токены} \times P_{\text{out}})}{N_{\text{tasks}}}$	Средняя финансовая себестоимость успешного выполнения сценария

Где:

$N_{\text{success}}$ — количество успешно завершённых задач;
$N_{\text{total}}$ — общий объём задач в тестовом датасете;
$P_{\text{in}}, P_{\text{out}}$ — тарифная стоимость входных и выходных токенов соответственно.

Практический пример: если из $20$ тестовых сценариев миграции базы данных агент успешно и без ошибок выполнил $17$ , то показатель успешности составит:

\text{TCR} = \frac{17}{20} = 0.85 \quad (85\%)

Реализация судьи (Eval Judge)

Судья не должен выносить вердикт в свободной форме. Ему задаётся структурированная схема с бинарными флагами и обоснованием:

export const EvaluationRubricSchema = z.object({
  functionalRequirementsMet: z.boolean().describe("Выполнены ли все требования из ТЗ"),
  noRegressionsIntroduced: z.boolean().describe("Не сломаны ли существующие функции"),
  codeStyleCompliant: z.boolean().describe("Соответствует ли код стандартам проекта"),
  score: z.number().int().min(1).max(5).describe("Итоговый балл от 1 до 5"),
  reasoning: z.string().describe("Подробный анализ дефектов или обоснование оценки")
});

export type EvaluationResult = z.infer<typeof EvaluationRubricSchema>;

Системный промпт для судьи изолирует его от контекста создания решения:

Вы — строгий аудитор программного кода. Ваша задача — оценить предложенный патч.
Вам предоставлены:
1. Исходное техническое задание.
2. Фактический git diff изменений.
3. Результаты прогона модульных тестов.

Оцените решение исключительно на основе фактов. Заполните каждый пункт схемы EvaluationRubric.

Создание золотого датасета (Golden Dataset)

Тестирование агентов бессмысленно без репрезентативного набора входных данных. Золотой датасет (Golden Dataset) — это коллекция из 20–50 реальных задач с зафиксированными начальными условиями и эталонными критериями приёмки.

Структура типового тест-кейса в таком датасете:

{
  "id": "case-auth-jwt-refresh",
  "description": "Добавление ротации refresh-токенов в AuthController",
  "initialStateBranch": "fixtures/base-auth-setup",
  "taskPrompt": "Реализуй ротацию refresh-токенов в endpoint /auth/refresh с сохранением в Redis",
  "expectedModifiedFiles": ["src/controllers/auth.ts", "src/services/token.ts"],
  "verificationCommand": "pnpm test src/controllers/auth.test.ts",
  "maxAllowedSteps": 8,
  "maxBudgetUsd": 0.45
}

Прогон золотого датасета запускается перед каждым релизом новых промптов супервизора или модификацией MCP-инструментов. Если средний показатель TCR падает более чем на $5\%$ или стоимость решения возрастает в полтора раза, изменения отклоняются как содержащие регрессию.

Контейнеризация ИИ-приложений с Docker

Запуск автономного агента с флагом --dangerously-skip-permissions на локальной рабочей станции напоминает передачу ключей от квартиры незнакомцу: достаточно одной галлюцинации в регулярном выражении команды rm или непредвиденного сайд-эффекта сборщика, чтобы повредить системные файлы хоста или перезаписать исходный код. Когда агентный конвейер переходит от локальных экспериментов к непрерывной обработке задач, запуск вслепую на хост-системе становится недопустимым архитектурным риском.

Контейнеризация решает две фундаментальные проблемы агентной разработки: гарантирует воспроизводимость окружения со всеми зависимостями (Node.js, Python, базы данных, CLI-утилиты) и создает жесткий барьер безопасности между автономным исполнителем и вашей операционной системой.

Зачем ИИ-агентам и MCP Docker-изоляция

Автономная работа Claude Code строится вокруг вызова инструментов (Tool Use) и выполнения shell-команд. В сложной агентной системе, включающей несколько MCP-серверов, локальные базы данных и фоновые очереди, среда выполнения быстро обрастает десятками системных утилит.

Изоляция в Docker дает три критических преимущества:

Безопасное делегирование прав. Внутри контейнера агент может обладать правами суперпользователя на установку пакетов через apt или запуск тестов, но это пространство изолировано от хостовой ОС через Linux namespaces и cgroups.
Детерминизм окружения инструментов. Если вашему кастомному MCP-серверу требуется Python 3.11 с конкретными C-библиотеками, а агентному раннеру — Node.js 20, контейнер упаковывает эти требования в неизменяемый образ (Immutable Image).
Эфемерность (смертность) состояния. Любой сбой, утечка памяти или засорение диска временными артефактами устраняются простым пересозданием контейнера за доли секунды.

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

Проектирование Multi-Stage Dockerfile для агентного стека

Создание Docker-образа для Claude Code и сопутствующих инструментов требует баланса между размером образа и наличием всех утилит, которые могут понадобиться агенту при анализе кода (git, jq, curl, компиляторы).

Применение многоэтапной сборки (multi-stage build) позволяет разделить фазу установки тяжелых системных зависимостей и финальный runtime-образ.

Ниже представлена конфигурация Dockerfile для создания изолированной среды разработчика под управлением Claude Code:

# syntax=docker/dockerfile:1.4

# Этап 1: Базовый образ с системными утилитами
FROM node:20-slim AS base
ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    curl \
    jq \
    python3 \
    python3-pip \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Создаем непривилегированного пользователя для безопасной работы
RUN useradd -m -u 1001 -s /bin/bash agentuser

# Этап 2: Установка CLI-инструментов и MCP-окружения
FROM base AS runtime

# Устанавливаем Claude Code глобально
RUN npm install -g @anthropic-ai/claude-code

# Подготовка рабочей директории
WORKDIR /workspace
RUN chown -R agentuser:agentuser /workspace

# Переключаемся на непривилегированного пользователя
USER agentuser

# Настройка переменных окружения
ENV NODE_ENV=production
ENV HOME=/home/agentuser

ENTRYPOINT ["claude"]
CMD ["--help"]

Разбор директив безопасности

Непривилегированный пользователь (agentuser): Запуск процессов от имени root внутри контейнера опасен. Если сгенерированный скрипт или скомпрометированный пакет попытается выйти за рамки окружения, непривилегированный пользователь с UID 1001 минимизирует вектор атаки.
Очистка кэша пакетов (rm -rf /var/lib/apt/lists/*): Удаление индексов apt непосредственно в том же слое RUN уменьшает размер финального слоя на десятки мегабайт.
Фиксация рабочего каталога (/workspace): Все операции монтирования внешнего репозитория будут происходить в предсказуемую точку файловой системы с заранее настроенными правами владения (chown).

Оркестрация стека в Docker Compose

На практике Claude Code редко работает в изоляции. Типичный production-конвейер включает сам CLI-агент, MCP-сервер базы данных (PostgreSQL), брокер задач и, при необходимости, локальный прокси-сервер моделей LiteLLM.

Для объединения этих компонентов в единую изолированную сеть используется docker-compose.yml:

version: '3.8'

services:
  # Изолированная база данных для тестов и MCP
  postgres-sandbox:
    image: postgres:16-alpine
    container_name: mcp-postgres-db
    environment:
      POSTGRES_DB: devdb
      POSTGRES_USER: mcpuser
      POSTGRES_PASSWORD: mcppassword
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - agent-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mcpuser -d devdb"]
      interval: 5s
      timeout: 5s
      retries: 5

  # Агентный раннер
  claude-runner:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: claude-agent-runner
    depends_on:
      postgres-sandbox:
        condition: service_healthy
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - DATABASE_URL=postgresql://mcpuser:mcppassword@postgres-sandbox:5432/devdb
    volumes:
      # Монтируем локальный репозиторий в песочницу
      - ./project-src:/workspace
      # Монтируем пользовательскую конфигурацию MCP
      - ./mcp-config.json:/home/agentuser/.claude.json:ro
    networks:
      - agent-network
    stdin_open: true
    tty: true

networks:
  agent-network:
    driver: bridge

volumes:
  pgdata:

Сетевая безопасность и изоляция сервисов

В приведенной конфигурации контейнеры объединены виртуальным мостом agent-network. База данных postgres-sandbox не пробрасывает порты на хост-машину (отсутствует секция ports:). Доступ к базе открыт исключительно для контейнера claude-runner по внутреннему DNS-имени postgres-sandbox:5432.

Это предотвращает случайный конфликт портов с локально запущенными сервисами разработчика и блокирует несанкционированный внешний доступ к тестовой базе.

Паттерн Ephemeral Sandbox (Одноразовые песочницы)

Когда перед агентным конвейером стоит задача выполнить сгенерированный код, прогнать модульные тесты или провести сборку стороннего репозитория, запуск длительно живущего контейнера не всегда оптимален. Для потенциально опасных операций применяется паттерн Ephemeral Sandbox — запуск одноразового контейнера с жесткими аппаратными лимитами, который уничтожается сразу после возврата кода выхода (exit code).

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

docker run --rm \
  --name "agent-sandbox-job-$$" \
  --network none \
  --memory 512m \
  --cpus 1.0 \
  --pids-limit 100 \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  -v "$(pwd)/project-src":/workspace:ro \
  -w /workspace \
  claude-runner-image \
  python3 -m unittest discover tests

Ключевые параметры жесткой изоляции

Флаг запуска	Назначение для безопасности
`--rm`	Автоматически удаляет контейнер и его анонимные тома после завершения процесса.
`--network none`	Полностью отключает сетевой стек: агент не сможет скачать сторонний код или передать секреты наружу.
`--memory 512m`	Защита от утечек памяти (Out-Of-Memory) и бесконечных циклов аллокации.
`--pids-limit 100`	Предотвращение «fork-бомб» (бесконечного ветвления процессов внутри контейнера).
`--read-only`	Переводит корневую файловую систему контейнера в режим «только чтение».
`-v ...:ro`	Монтирует исходный код проекта только для чтения, защищая кодовую базу от случайного повреждения.

Если контейнеру необходимо записать временные файлы во время тестов, директива --tmpfs /tmp:rw,noexec,nosuid,size=64m выделяет изолированный сегмент оперативной памяти размером 64 МБ, запрещая выполнение исполняемых бинарных файлов из этой директории (noexec).

Управление секретами и переменными окружения

При контейнеризации ИИ-приложений критически важно не зашить API-ключи в слои Docker-образа. Команда RUN export ANTHROPIC_API_KEY=sk-... внутри Dockerfile сохраняет ключ в истории слоев навсегда — его сможет извлечь любой пользователь через docker history.

Правильные подходы к передаче секретов:

Передача через env_file в рантайме: Файл .env добавляется в .gitignore и передается контейнеру в момент старта:
```
docker run --env-file .env.agent -v $(pwd):/workspace claude-runner
```
Использование Docker Secrets (в Docker Compose / Swarm): Монтирование секретов в виде временных файлов в /run/secrets/, считываемых процессом без попадания в переменные окружения.
BuildKit Secrets для сборки: Если ключ необходим на этапе сборки (например, для доступа к приватному реестру npm/pip):
```
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) npm install
```

Контейнеризация формирует предсказуемый фундамент для перехода к следующему этапу жизненного цикла ИИ-приложений: развертыванию готового агентного сервиса на удаленный сервер, настройке сетевых шлюзов, SSH-туннелей и защищенных SSL-сертификатов.

Деплой на сервер: SSH, SSL и сетевая безопасность

Приложение, упакованное в легковесный Docker-контейнер и протестированное локально, готово к встрече с реальными пользователями. Но если просто запустить docker run -p 80:3000 на арендованном VPS со стандартными настройками, сканеры ботнетов обнаружат открытые порты менее чем за десять минут. Прод-окружение требует надежного контура: защищенного доступа к терминалу, автоматической выдачи SSL-сертификатов, обратного проксирования и закрытия служебных портов от внешнего мира.

Развертывание агентных систем и веб-сервисов на удаленном Linux-сервере (Ubuntu/Debian) строится на нескольких фундаментальных уровнях безопасности, которые предотвращают перехват трафика и несанкционированный доступ к инфраструктуре.

1. Подготовка и ужесточение доступа по SSH

Первая линия обороны любого удаленного сервера — настройка протокола Secure Shell (SSH). По умолчанию многие хостинг-провайдеры выдают доступ пользователю root с парольной аутентификацией, что подвергает сервер постоянным атакам методом перебора (brute-force).

Создание ключей и непривилегированного пользователя

Парольная аутентификация полностью отключается в пользу асимметричного шифрования на базе современных эллиптических кривых Ed25519.

Генерация ключевой пары на локальной рабочей станции:

ssh-keygen -t ed25519 -C "admin-deploy-key"

Копирование публичного ключа на целевой сервер:

ssh-copy-id -i ~/.ssh/id_ed25519.pub root@203.0.113.10

После первого входа необходимо создать отдельного системного пользователя с правами sudo и перенести авторизованные ключи в его домашнюю директорию:

# Создание пользователя deployer
adduser --gecos "" deployer
usermod -aG sudo deployer

# Настройка SSH-каталога для нового пользователя
mkdir -p /home/deployer/.ssh
cp /root/.ssh/authorized_keys /home/deployer/.ssh/
chown -R deployer:deployer /home/deployer/.ssh
chmod 700 /home/deployer/.ssh
chmod 600 /home/deployer/.ssh/authorized_keys

Конфигурация SSH-демона

Файл конфигурации /etc/ssh/sshd_config (или отдельный файл в /etc/ssh/sshd_config.d/99-security.conf) модифицируется для запрета опасных настроек:

# Запрет входа под учетной записью root
PermitRootLogin no

# Запрет аутентификации по паролю
PasswordAuthentication no
PermitEmptyPasswords no

# Отключение интерактивной проверки пароля (современная и устаревшая директивы)
KbdInteractiveAuthentication no
ChallengeResponseAuthentication no

# Ограничение максимального числа попыток аутентификации
MaxAuthTries 3

После сохранения изменений служба SSH перезапускается без разрыва текущей активной сессии:

sudo sshd -t && sudo systemctl reload ssh

Проверка корректности синтаксиса через команду sshd -t перед перезапуском демона обязательна. Ошибка в конфигурационном файле при отключенном парольном входе может полностью заблокировать доступ к серверу.

2. Межсетевой экран: настройка UFW

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

В дистрибутивах Ubuntu и Debian стандартным инструментом управления сетевым фильтром iptables выступает утилита UFW (Uncomplicated Firewall).

# Установка базовой политики: запретить всё входящее, разрешить всё исходящее
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Разрешение входящего SSH-трафика
sudo ufw allow 22/tcp comment 'SSH'

# Разрешение веб-трафика (HTTP и HTTPS)
sudo ufw allow 80/tcp comment 'HTTP'
sudo ufw allow 443/tcp comment 'HTTPS'

# Активация фаервола
sudo ufw enable

Специфика связки UFW и Docker

Стандартный демон Docker при публикации портов (-p 3000:3000 или ports: - "3000:3000") по умолчанию модифицирует цепочки iptables напрямую, минуя правила UFW. Это означает, что контейнер с открытым портом окажется доступен из интернета, даже если UFW запрещает входящие подключения на этот порт.

Чтобы гарантировать изоляцию, порты контейнеров никогда не публикуются на публичном интерфейсе 0.0.0.0. Вместо этого они привязываются строго к локальной петле 127.0.0.1:

# Фрагмент docker-compose.prod.yml
services:
  app:
    image: my-app:latest
    ports:
      # Доступен ТОЛЬКО локальным процессам хоста (Nginx)
      - "127.0.0.1:3000:3000"
    restart: unless-stopped

3. Обратный прокси (Nginx) и SSL-терминация

Прямое выставление Node.js- или Python-сервера наружу неэффективно: такие приложения уязвимы к медленным HTTP-атакам (Slowloris), не умеют быстро отдавать статический контент и требуют сложной настройки прав для работы на привилегированных портах 80 и 443.

Роль входной точки принимает на себя обратный прокси-сервер (Reverse Proxy) — Nginx. Он выполняет следующие задачи:

Завершает защищенное TLS-соединение (SSL Termination).
Проксирует очищенный трафик на локальный порт контейнера (http://127.0.0.1:3000).
Сжимает ответы алгоритмами Gzip / Brotli и буферизирует тяжелые запросы.
Добавляет критически важные HTTP-заголовки безопасности.

Конфигурация виртуального хоста Nginx

Файл конфигурации создается по пути /etc/nginx/sites-available/app.example.com:

server {
    listen 80;
    listen [::]:80;
    server_name app.example.com;

    # Ограничение размера тела запроса (защита от переполнения памяти)
    client_max_body_size 10M;

    # Заголовки безопасности
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        # Проброс заголовков для поддержки WebSocket и корректного определения IP клиента
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Таймауты для длительных агентных генераций (Server-Sent Events / стриминг)
        proxy_read_timeout 300s;
        proxy_connect_timeout 60s;
        proxy_send_timeout 300s;
    }
}

Активация конфигурации и перезапуск веб-сервера:

sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

4. Автоматизация SSL-сертификатов через Let's Encrypt и Certbot

Шифрование веб-трафика по протоколу TLS 1.3 обязательно для любого продакшн-ресурса. Бесплатный удостоверяющий центр Let's Encrypt выпускает сертификаты сроком на 90 дней с возможностью автоматического продления через утилиту Certbot.

Установка и выпуск сертификата

# Установка Certbot и плагина для Nginx через snap
sudo snap install core && sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

# Выпуск сертификата и автоматическая модификация конфига Nginx
sudo certbot --nginx -d app.example.com

Certbot автоматически настроит перенаправление всего незашифрованного HTTP-трафика (порт 80) на защищенный HTTPS (порт 443), добавит пути к цепочке сертификатов (fullchain.pem) и приватному ключу (privkey.pem).

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

Утилита регистрирует системный таймер systemd, который запускает проверку истечения сертификатов дважды в сутки:

sudo certbot renew --dry-run

Если симуляция завершилась без ошибок (All simulated renewals succeeded), сертификат будет продлеваться автоматически без участия оператора.

5. Паттерн безопасного деплоя и доставки секретов

Работа ИИ-агентов и веб-приложений опирается на внешние API-ключи (Anthropic API Key, токены баз данных). Попадание этих секретов в открытый доступ или хранение в Git-репозитории недопустимо.

Структура каталогов на сервере

Стандартная изоляция проекта в домашней директории пользователя deployer:

/home/deployer/apps/my-project/
├── docker-compose.prod.yml
├── .env.production          # Хранится ТОЛЬКО на сервере, права 600
└── releases/                # Артефакты сборки или логи

Файл окружения .env.production защищается правами файловой системы:

chmod 600 /home/deployer/apps/my-project/.env.production

Скрипт атомарного обновления сервиса (Zero-Downtime Rebuild)

Для автоматизации выкатки свежих версий кода используется сценарий, выполняющий сборку нового контейнера, проверку работоспособности и подмену старого экземпляра:

#!/usr/bin/env bash
set -euo pipefail

APP_DIR="/home/deployer/apps/my-project"
cd "$APP_DIR"

echo "=== 1. Получение последних изменений ==="
git pull origin main

echo "=== 2. Сборка Docker-образа ==="
docker compose -f docker-compose.prod.yml build --no-cache app

echo "=== 3. Бесшовный перезапуск контейнеров ==="
docker compose -f docker-compose.prod.yml up -d --remove-orphans app

echo "=== 4. Проверка статуса сервиса ==="
sleep 5
if curl -sf http://127.0.0.1:3000/health > /dev/null; then
    echo "Деплой успешно завершен, эндпоинт /health отвечает 200 OK"
else
    echo "ОШИБКА: Сервис не прошел healthcheck!"
    docker compose -f docker-compose.prod.yml logs --tail=50 app
    exit 1
fi

echo "=== 5. Очистка неиспользуемых слоев и образов ==="
docker image prune -f

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

6. Защита от злоупотреблений: Fail2ban и лимиты запросов

Даже при закрытых портах веб-сервер подвергается сканированию уязвимостей и спам-запросам. Для защиты Nginx и SSH на сервер устанавливается утилита Fail2ban, анализирующая системные журналы и временно блокирующая IP-адреса нарушителей через фаервол.

sudo apt-get update && sudo apt-get install -y fail2ban

Создание локального файла настроек /etc/fail2ban/jail.local:

[DEFAULT]
bantime  = 1h
findtime = 10m
maxretry = 5

[sshd]
enabled = true
port    = 22
mode    = aggressive

[nginx-http-auth]
enabled = true
port    = http,https

[nginx-limit-req]
enabled = true
port    = http,https
logpath = /var/log/nginx/*error.log

В блоке http конфигурации Nginx (/etc/nginx/nginx.conf) настраиваются зоны ограничения частоты запросов (Rate Limiting), предотвращающие исчерпание лимитов внешних ИИ-моделей:

# Ограничение: не более 10 запросов в секунду с одного IP-адреса
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

# В блоке location /api/:
# limit_req zone=api_limit burst=20 nodelay;

Комплекс из Ed25519-ключей, UFW, изолированной привязки портов Docker, обратного прокси Nginx с TLS 1.3 и надстройки Fail2ban формирует надежную инфраструктуру, готовую к промышленной эксплуатации и монетизации созданных сервисов.

Стратегии монетизации и упаковка услуг вайб-кодинга

Традиционный аутсорс продает часы: разработчик тратит 80 часов на создание CRM-интеграции и выставляет счет по ставке 40 USD в час, зарабатывая 3200 USD. Инженер с Claude Code и готовой библиотекой MCP-навыков реализует ту же самую интеграцию, включая тесты и контейнеризацию, за 6 часов чистого времени. Если продавать эти 6 часов по стандартной ставке, доход составит 240 USD — парадокс производительности наказывает разработчика за экстремальную скорость.

Появление агентных инструментов ломает классическую экономику заказной разработки. Единственный способ монетизировать возросшую в 10–15 раз скорость генерации ценности — полностью отказаться от продажи рабочего времени и перейти к упаковке готовых результатов, продуктовых сервисов и собственных микросервисов.

Парадокс почасовой оплаты и переход к Value-Based Pricing

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

Ценообразование на основе ценности (Value-Based Pricing) — модель формирования стоимости, при которой цена услуги определяется не затраченными ресурсами или временем исполнителя, а экономической выгодой (доходом или сэкономленными средствами), которую решение приносит бизнесу клиента.

Если автоматизированный контент-завод экономит маркетинговому агентству 5000 USD ежемесячно на рутинном рерайте и верстке, ценность внедрения за первый год составляет 60 000 USD. Продажа такого решения за фиксированные 6000–10 000 USD является выгодной сделкой для клиента (окупаемость за 2 месяца) и дает исполнителю доходность в тысячи долларов за считанные часы работы с Claude Code.

Параметр	Почасовая оплата (T&M)	Фиксированный проект (Fixed-Price)	Оплата за ценность (Value-Based)	Продуктовый сервис (Productized Service)
База для расчета	Затраченные часы	Оценка трудозатрат + буфер	Финансовый эффект для заказчика	Стандартизированный пакет услуг
Влияние Claude Code	Снижает суммарный чек	Увеличивает маржинальность	Максимизирует итоговый доход	Позволяет масштабировать поток заказов
Финансовый риск	Несет заказчик	Несет разработчик	Распределен (через KPI/этапы)	Минимален за счет четких границ
Сложность продажи	Низкая (привычно рынку)	Средняя (нужно ТЗ)	Высокая (нужен аудит бизнеса)	Средняя (понятный прайс-лист)

Продуктовые форматы: как упаковать навыки вайб-кодинга

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

Sprint-as-a-Service (Вайб-спринты под ключ) Вместо многомесячной заказной разработки клиенту продается 3–5-дневный спринт с жестко зафиксированным результатом: работающий прототип (MVP), парсер данных с MCP-интеграцией или админ-панель. Четкие временные рамки снимают с разработчика риск бесконечных правок.
Productized Automation (Стандартизированные роботы) Создание типовых интеграций под ключ с фиксированным ценником. Например: «Пайплайн генерации SEO-статей из базы PostgreSQL в Webflow за 1500 USD» или «Telegram-бот технической поддержки с базой знаний на SQLite за 900 USD». Решение собирается из заранее подготовленных модулей и кастомных промптов за 2–4 часа.
Micro-SaaS и внутренние инструменты по подписке Развертывание специализированных нишевых утилит с ежемесячной оплатой (B2B-подписка). Благодаря тому, что инфраструктура на базе Docker и Nginx обходится в 5–15 USD в месяц на VPS, даже 10 клиентов с чеком 50 USD/мес обеспечивают высокую рентабельность.

Юнит-экономика и расчет себестоимости ИИ-продуктов

Главная ловушка при запуске сервисов на базе LLM — иллюзия бесплатности вычислений. Если в классическом SaaS основная переменная статья затрат — это нагрузка на CPU и трафик базы данных, то в агентных решениях каждый вызов языковой модели напрямую списывает баланс API.

Формула себестоимости агентной операции

Себестоимость выполнения одной пользовательской задачи $C_{\text{task}}$ складывается из прямых затрат на контекст токенов и амортизации серверной инфраструктуры:

C_{\text{task}} = (T_{\text{in}} \cdot P_{\text{in}} + T_{\text{out}} \cdot P_{\text{out}}) \cdot N_{\text{steps}} + \frac{C_{\text{infra}}}{U_{\text{monthly}}}

Разберем составляющие формулы на конкретных величинах:

$T_{\text{in}}$ и $T_{\text{out}}$ — объем входных и выходных токенов за один шаг агентного цикла.
$P_{\text{in}}$ и $P_{\text{out}}$ — стоимость 1 токена соответствующего типа (указывается провайдером за 1 миллион токенов).
$N_{\text{steps}}$ — среднее количество итераций агента (ReAct-шагов) до завершения задачи.
$C_{\text{infra}}$ — постоянные ежемесячные затраты на сервер (VPS, домен, SSL, шлюзы).
$U_{\text{monthly}}$ — суммарное расчетное количество задач, выполняемых сервисом за месяц.

Практический расчет: Мультиагентный конвейер делает 3 шага для обработки входящего лида. На каждом шаге в модель отправляется 4000 токенов контекста ( $T_{\text{in}} = 4000$ ) и генерируется 500 токенов ответа ( $T_{\text{out}} = 500$ ). При использовании Claude 3.5 Sonnet ( $P_{\text{in}} = 3$ USD за $10^6$ токенов, $P_{\text{out}} = 15$ USD за $10^6$ токенов):

Затраты на 1 шаг: $(4000 \cdot 0.000003) + (500 \cdot 0.000015) = 0.012 + 0.0075 = 0.0195\text{ USD}$ . За 3 шага агентного цикла: $0.0195 \cdot 3 = 0.0585\text{ USD}$ . При аренде сервера за 10 USD/мес и объеме 2000 запросов добавочная стоимость инфраструктуры составит $10 / 2000 = 0.005\text{ USD}$ .

Итоговая чистая себестоимость задачи: $C_{\text{task}} \approx 0.0635\text{ USD}$ (около 6.35 центов).

Стратегии защиты маржинальности

Многоуровневая маршрутизация моделей (Model Tiering) Запуск дорогой модели (Sonnet) на всех этапах сжигает бюджет. Рутинные задачи валидации, извлечения сущностей из JSON и первичной фильтрации делегируются Claude 3.5 Haiku или локальным моделям через LiteLLM Proxy. Sonnet подключается только на финальном этапе синтеза.
Кэширование промптов (Prompt Caching) При работе с массивными неизменяемыми контекстами (системные инструкции, схемы баз данных, документация) использование встроенного кэширования API снижает стоимость входных токенов до 90% и ускоряет ответ.
Жесткие лимиты токенов и итераций (Hard Caps) Агентный цикл без ограничения шагов способен зациклиться на невалидном вводе и потратить десятки долларов за один запуск. В коде раннера обязательны параметры max_tokens и счетчик шагов max_iterations <= 5.

Границы ответственности, юридическая упаковка и SLA

Ключевой барьер при продаже решений на базе вайб-кодинга — страх клиента перед стохастической природой генеративного ИИ (галлюцинации, сбои логики, утечки контекста). Грамотная упаковка услуг требует четкого разграничения зон ответственности в договоре и техническом задании.

Что включать в соглашение об уровне обслуживания (SLA)

Метрики качества вместо гарантии 100% безошибочности: В договоре фиксируется не «абсолютная безошибочность генерации», а показатель успешного выполнения задач (Task Completion Rate) на тестовой выборке (например, $\text{TCR} \geq 92\%$ ).
Изоляция секретов и клиентских данных: Четкое указание на то, что данные клиента не используются для дообучения глобальных моделей (что гарантируется коммерческим API Anthropic) и изолированы в контейнерах.
Модель оплаты API-токенов:
- Вариант А (BYOK — Bring Your Own Key): Клиент регистрирует собственный аккаунт в Anthropic Console и привязывает карту. Разработчик настраивает окружение с переменной ANTHROPIC_API_KEY клиента. Разработчик не несет рисков перерасхода лимитов.
- Вариант B (Managed Service): Разработчик включает стоимость токенов в ежемесячный абонентский чек с 2–3-кратным коэффициентом безопасности и устанавливает системный лимит в панели управления.

+-------------------------------------------------------------------+
|              СТРУКТУРА КОММЕРЧЕСКОГО ПРЕДЛОЖЕНИЯ                  |
+-------------------------------------------------------------------+
| 1. Фиксация бизнес-результата (что автоматизируем и сколько часов |
|    экономит решение в месяц)                                      |
| 2. Состав поставки (Docker-контейнер, MCP-серверы, скрипты Nginx) |
| 3. Гарантированный период поддержки (14-30 дней фиксов багов)     |
| 4. Протокол передачи (репозиторий Git, документация CLAUDE.md,    |
|    инструкция по деплою через Docker Compose)                     |
| 5. Тарификация инфраструктуры и токенов (BYOK или фикс-пакет)     |
+-------------------------------------------------------------------+

Умение упаковать технический стек (Claude Code, MCP, Docker, Linux-серверы) в прозрачный бизнес-оффер превращает вайб-кодинг из инструмента быстрого прототипирования в высокорентабельный бизнес.

Разработка и запуск финального практического проекта

Создание программного продукта традиционным методом требует последовательной смены ролей: системный архитектор готовит спецификацию, бэкендер проектирует базу данных и API, фронтендер верстает интерфейс, QA-инженер пишет тестовые сценарии, а DevOps настраивает Docker-контейнеры и Nginx на сервере. В парадигме агентной инженерии и вайб-кодинга все эти этапы выполняет единый тандем разработчика и Claude Code — при условии, что процесс разбит на строгие детерминированные фазы с проверяемыми контрактами.

Разработка сложного сервиса за одну сессию неизбежно приводит к галлюцинациям, деградации контекста и накоплению скрытых багов. Чтобы довести проект от пустой директории до работающего в продакшне решения с реальными пользователями, требуется собрать воедино все изученные паттерны: от тонкой настройки CLAUDE.md и кастомных MCP-инструментов до мультиагентного тестирования, контейнеризации и защищённого сетевого деплоя.

Концепция и архитектурная декомпозиция проекта

В качестве итогового проекта реализуется полнофункциональный микро-сервис AuditVibe — автоматизированный конвейер безопасности и аудита pull-реквестов с публичным веб-интерфейсом и Telegram-уведомлениями.

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

Архитектура объединяет ключевые строительные блоки, разобранные на протяжении курса:

Frontend-слой: одностраничное приложение на Vite и Tailwind CSS с реактивной формой отправки задач и экраном визуализации отчёта.
API-оркестратор: Node.js/TypeScript сервис на Fastify, принимающий входящие запросы и управляющий жизненным циклом фоновых задач.
Агентный движок аудита: изолированный подпроцесс Claude Code, оснащённый кастомным MCP-сервером для статического анализа и синтаксической валидации.
Слой данных: локальная база данных SQLite/DuckDB для хранения истории проверок и аналитических срезов.
Инфраструктурный контур: Docker Compose стек (приложение, обратный прокси Nginx, SSL-терминация через Certbot) с привязкой портов к локальному интерфейсу 127.0.0.1.

auditvibe/
├── .claudeignore
├── CLAUDE.md
├── docker-compose.yml
├── Dockerfile
├── .env.example
├── mcp-server/
│   ├── package.json
│   └── src/
│       └── index.ts
├── server/
│   ├── src/
│   │   ├── index.ts
│   │   ├── routes.ts
│   │   └── runner.ts
│   └── package.json
└── client/
    ├── src/
    │   ├── App.tsx
    │   └── components/
    └── package.json

Фаза 1: Инициализация контекста и правила проекта

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

В корне проекта создаётся CLAUDE.md, задающий архитектурный контракт:

# AuditVibe System Instructions

## Tech Stack
- Frontend: React 18, Vite, Tailwind CSS, Lucide Icons
- Backend: Node.js 20, Fastify, TypeScript, Zod, SQLite (better-sqlite3)
- Agent Engine: Claude Code CLI in headless mode (`claude -p`)

## Workflow Commands
- Build all: `pnpm --filter "*" build`
- Typecheck: `pnpm --filter "*" typecheck`
- Test: `pnpm test`
- Run dev: `pnpm dev`

## Code Rules & Invariants
- Strict TypeScript: no `any`, all payload schemas must be defined in Zod.
- Security: Never expose `ANTHROPIC_API_KEY` to client bundle.
- Subprocesses: Agent runs must execute with ephemeral timeouts and memory limits.
- Errors: Return standardized JSON errors with code and user-friendly explanation.

Наряду с правилами настраивается .claudeignore, исключающий директории сборок, дампы данных и локальные логи, чтобы встроенные поисковые инструменты Glob и Grep не расходовали токены на мусорные файлы.

Фаза 2: Реализация кастомного MCP-навыка аудита

Для проведения аудита агенту нужен доступ к специализированным инструментам: чтению патчей, проверке зависимостей и поиску уязвимых паттернов в коде. В директории mcp-server/ создаётся кастомный навык на базе @modelcontextprotocol/sdk.

Сервер экспортирует два инструмента:

analyze_ast_security: выполняет статический поиск опасных конструкций (например, небезопасного вызова eval или прямых инъекций команд оболочки).
check_dependency_cve: сверяет манифесты зависимостей с локальной базой известных уязвимостей.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "auditvibe-tools",
  version: "1.0.0"
});

server.tool(
  "analyze_ast_security",
  {
    filePath: z.string().describe("Path to the target file inside the sandbox"),
    checkPattern: z.enum(["command_injection", "hardcoded_secrets", "prototype_pollution"])
  },
  async ({ filePath, checkPattern }) => {
    // Детерминированная проверка файла без обращения к внешним LLM
    const issues = await runSecurityInspection(filePath, checkPattern);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ filePath, checkPattern, foundIssues: issues })
        }
      ]
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Подключение кастомного сервера фиксируется в конфигурации MCP (например, .mcp.json или .claude/settings.json), благодаря чему Claude Code автоматически получает доступ к специализированным валидаторам при анализе кода.

Фаза 3: Оркестратор и агентный конвейер

Бэкенд-сервер на Fastify принимает входящий запрос с дифференциалом кода, помещает задачу в очередь и запускает сессию аудита через утилиту claude -p (print / headless режим).

Принципиальный момент надежности — соблюдение паттерна изоляции:

Для каждой задачи создаётся временная рабочая директория (scratchpad).
Вызов агента ограничивается таймаутом и передачей строго типизированного системного промпта.
Результат аудита запрашивается в формате JSON-схемы AuditReportSchema с флагом --output-format json.

import { execFile } from "node:child_process";
import { promisify } from "node:util";
import { z } from "zod";

const execFileAsync = promisify(execFile);

export const AuditReportSchema = z.object({
  score: z.number().min(0).max(100),
  summary: z.string(),
  vulnerabilities: z.array(
    z.object({
      severity: z.enum(["low", "medium", "high", "critical"]),
      file: z.string(),
      line: z.number().optional(),
      description: z.string(),
      remediation: z.string()
    })
  )
});

export type AuditReport = z.infer<typeof AuditReportSchema>;

export async function runAgentAudit(diffContent: string, workDir: string): Promise<AuditReport> {
  const prompt = `
Ты — ведущий инженер по безопасности. Проанализируй переданный git-diff.
Используй подключенные MCP-инструменты для проверки подозрительных мест.
Верни результат ИСКЛЮЧИТЕЛЬНО в виде валидного JSON, соответствующего схеме:
{
  "score": number,
  "summary": string,
  "vulnerabilities": [{ "severity": "...", "file": "...", "description": "...", "remediation": "..." }]
}

DIFF ДЛЯ АНАЛИЗА:
${diffContent}
`;

  const { stdout } = await execFileAsync("claude", [
    "-p", prompt,
    "--output-format", "json",
    "--allowedTools", "analyze_ast_security,Read,Grep"
  ], {
    cwd: workDir,
    timeout: 60000,
    maxBuffer: 10 * 1024 * 1024
  });

  const rawOutput = JSON.parse(stdout.trim());
  const reportPayload = typeof rawOutput.result === "string"
    ? JSON.parse(rawOutput.result)
    : (rawOutput.structured_output ?? rawOutput);

  return AuditReportSchema.parse(reportPayload);
}

Фаза 4: Клиентский интерфейс и живая верификация

Фронтенд разрабатывается по методологии Component-First: сначала создаются атомарные виджеты индикации критичности уязвимостей (SeverityBadge), метрики общего рейтинга (SecurityScoreGauge) и таблица выявленных дефектов, после чего компоненты собираются в единую страницу дашборда.

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

Фаза 5: Контейнеризация и релизный пайплайн

Финальный шаг — упаковка всех сервисов в многоэтапный Docker-образ и настройка сервера.

В Dockerfile используется разделение на этапы сборки (builder) и финального исполнения от имени пользователя non-root:

# Этап 1: Сборка клиентской и серверной части
FROM node:20-slim AS builder
WORKDIR /app
RUN npm install -g pnpm
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
COPY client/package.json ./client/
COPY server/package.json ./server/
COPY mcp-server/package.json ./mcp-server/
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm --filter "*" build

# Этап 2: Финальный runtime-контейнер
FROM node:20-slim AS runner
WORKDIR /app
RUN npm install -g @anthropic-ai/claude-code pnpm && \
    useradd -u 1001 -m -s /bin/bash appuser

COPY --from=builder --chown=appuser:appuser /app /app

USER appuser
ENV NODE_ENV=production
EXPOSE 3000

CMD ["node", "server/dist/index.js"]

После сборки контейнер поднимается на целевом сервере под управлением docker-compose.prod.yml. Сервер Nginx принимает внешний HTTPS-трафик на 443 порту, выполняет SSL-терминацию и перенаправляет запросы на локальный порт 127.0.0.1:3000.

Smoke-тестирование в продакшне

После завершения деплоя необходимо провести финальную верификацию по контрольному чек-листу:

Проверка эндпоинта здоровья: curl -f https://auditvibe.example.com/api/health возвращает статус {"status": "ok"}.
Сквозной тест аудита: отправка тестового pull-реквеста с умышленно внедренной уязвимостью (например, fs.readFileSync(userInput)).
Контроль изоляции: проверка, что агентный подпроцесс завершается вовремя и очищает временные файлы из директории tmp/.
Валидация телеметрии: проверка логов Nginx и счетчика расхода токенов API.

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

Знакомство с Claude Code и настройка CLI

Знакомство с Claude Code и настройка CLI

Парадигма вайб-кодинга и терминальный агент

Системные требования и подготовка окружения

Установка Claude Code

Аутентификация и настройка API

Вариант 1. Авторизация через браузер (OAuth)

Вариант 2. Экспорт ключа API (ANTHROPIC_API_KEY)

Первый запуск и базовая интерактивная сессия

Итоги

Управление правами доступа и навигация по файлам

Управление правами доступа и навигация по файлам

Архитектура безопасности: как Claude Code исполняет команды

Уровни контроля и флаги запуска

Навигация по файлам и чтение кодовой базы

Встроенные инструменты исследования

Гигиена контекста и файл .claudeignore

Защита конфиденциальных данных

Практический сценарий: безопасный аудит проекта

Промптинг для терминала и настройка правил в CLAUDE.md

Промптинг для терминала и настройка правил в CLAUDE.md

Терминальный промптинг: от диалога к спецификации

Долговременная память проекта: архитектура CLAUDE.md

Иерархия резолвинга правил

Анатомия идеального CLAUDE.md

Обязательные разделы

Пример эталонного CLAUDE.md

Управление контекстом и инициализация через CLI

Тонкая конфигурация CLI-агента под задачи

Тонкая конфигурация CLI-агента под задачи

Иерархия параметров и слои конфигурации

Управление моделями и баланс «стоимость — качество»

Конфигурация сетевого окружения и прокси

Профилирование и алиасы для типовых сценариев

Интеграция конфигураций в рабочий процесс

Архитектура агентов и обработка данных и таблиц

Архитектура агентов и обработка данных и таблиц

Анатомия агентного цикла: ReAct и оркестрация инструментов

Стратегии обработки структурированных данных

1. Паттерн Schema Discovery (Исследование схемы)

2. Паттерн Code Execution as Data Filter

Практический пайплайн: аудит, очистка и трансформация

Шаг 1: Поиск аномалий и спецификация правил

Шаг 2: Генерация и запуск пайплайна очистки

Шаг 3: Самокоррекция при сбоях (Self-Correction Loop)

Локальная аналитика: SQLite и DuckDB как промежуточный слой

Использование DuckDB для мгновенных аналитических SQL-запросов

Работа с вложенными JSON через jq

Создание веб-страниц и конверсионных сайтов

Создание веб-страниц и конверсионных сайтов

Выбор стека: почему утилитарный CSS побеждает в вайб-кодинге

Анатомия конверсионной структуры

Паттерн Component-First Prompting

Адаптивность и динамика поведения интерфейса

Цикл визуальной обратной связи: Dev-сервер и живая отладка

Клиентская логика: валидация, микроинтерактивность и захват лидов

Интеграция с Git и GitHub через Claude Code

Интеграция с Git и GitHub через Claude Code

Семантический аудит изменений и атомарные коммиты

Формат Conventional Commits в инструкциях агента

Бесшовная связка с GitHub CLI (gh)

Паттерн Feature-Branch разработки

Агентный цикл ревью и устранение замечаний

Сбор комментариев и точечные патчи

Разрешение merge-конфликтов под управлением агента

Алгоритм устранения конфликта через Claude Code

Практический сценарий: от грязного рабочего дерева к чистому PR

Шаг 1. Перенос в новую ветку и семантическая фиксация

Шаг 2. Верификация и открытие Pull Request

Подключение локальных моделей и автоматизация рутины

Подключение локальных моделей и автоматизация рутины

Зачем переносить рутину в локальный контур

Архитектура проксирования: от CLI к Ollama и vLLM

Шаг 1. Запуск локального бэкенда инференса

Шаг 2. Развертывание шлюза LiteLLM

Шаг 3. Перенаправление Claude Code

Выбор локальных моделей и расчет аппаратных ресурсов

Оценка требуемой видеопамяти (VRAM)

Автоматизация рутинных задач через Headless CLI

Сценарий 1. Массовое добавление документации и типов

Работа с вложенными JSON через `jq`

Бесшовная связка с GitHub CLI (`gh`)

Обработка ошибок и флаг `isError`