Агентские инструменты разработки

Агент — это не автодополнение и не «чат про код». Это цикл, в котором модель сама решает, какой файл прочитать, что изменить и какую команду запустить, получает результат и повторяет. Понимание устройства этого цикла объясняет, почему инструменты ведут себя по-разному, где они надёжны, а где требуют вашего контроля. В статье — архитектура агентского цикла, инструменты и права, изоляция сессий через worktrees, subagents, plan mode, headless-режим в CI и сравнение Claude Code / Codex / Cursor / OpenCode.

Содержание

1. Цикл агента: мысль, инструмент, наблюдение
2. Инструменты и права
3. Изоляция сессии и worktrees
4. Subagents и параллельные агенты
5. Plan mode: сначала план
6. Headless-режим и CI
7. Сравнение инструментов
8. Практики и антипаттерны
9. Кейс: от задачи до ревью
10. Ключевые тезисы для интервью
11. Заключение
12. Полезные ссылки

---

Цикл агента: мысль, инструмент, наблюдение

Три режима работы с моделью

Важно различать три вещи, которые часто называют «AI-ассистентом»:

Агент отличается не «умом», а наличием цикла и инструментов: он не просто генерирует текст, а запрашивает действия и реагирует на их результат.

ReAct: thought → action → observation

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

Вопрос/задача
   │
   ▼
Thought        — «нужно понять, где определён useAuth»
Action         — вызвать Grep(pattern="useAuth")
Observation    — файл src/hooks/useAuth.ts, строки 12–40
   │
   ▼
Thought        — «прочитаю файл и правку»
Action         — Read(src/hooks/useAuth.ts)
Observation    — содержимое файла
   │
   ▼
Thought        — «внесу изменение»
Action         — Edit(...) / Bash("pnpm test")
Observation    — дифф применён / тесты прошли
   │
   ▼
Final answer

Цикл повторяется, пока в ответе модели есть вызовы инструментов. Остановка — либо финальный текстовый ответ, либо достижение лимита шагов (у инструментов он обычно настраивается: --max-turns, maxTurns в SDK).

Ключевой факт: модель не выполняет код

Для собеседований это один из главных вопросов. Модель не запускает код и не трогает файловую систему сама. Она эмитит структурированный запрос на вызов инструмента (JSON с именем инструмента и аргументами):

{
  "tool": "Edit",
  "input": {
    "file_path": "src/hooks/useAuth.ts",
    "old_string": "return user;",
    "new_string": "return { user, isLoading };"
  }
}

Выполняет его ваша среда — CLI-приложение, IDE или agent SDK. Оно проверяет права, запускает инструмент и возвращает результат как observation. Отсюда следствия для интервью:

• Агент — это модель + harness: цикл, набор инструментов, правила и политика прав. Одна и та же модель в разных инструментах ведёт себя по-разному.
• Безопасность — задача harness, а не модели: модель может «попросить» опасное действие, но именно среда решает, выполнять ли его.
• «Агент написал код» — неточность: код записан средой по запросу модели.

Навигация: agentic search вместо RAG

Поиск по кодовой базе агенты почти всегда делают не векторным retrieval, а обычным glob + grep по файлам: точное совпадение символов, нулевая настройка, нет устаревшего индекса. Claude Code изначально пробовал RAG с локальной векторной БД и отказался от него в пользу agentic search, который «выиграл с большим отрывом». Подробнее о контексте и retrieval — в статье Контекст-инжиниринг агентов.

---

Инструменты и права

Какие инструменты есть у агента

Типовой набор инструментов (названия у разных продуктов близки):

MCP как протокол интеграции внешних инструментов — отдельная тема, см. MCP: Model Context Protocol.

Кто выполняет и с какими правами

Модель лишь просит; решение о выполнении принимает harness. Поэтому у каждого инструмента есть политика прав и режим подтверждения. Примеры из реальных продуктов:

• Claude Code — permission modes (plan, acceptEdits, auto, dontAsk), точечные allow/deny-правила, а в headless-режиме — --allowedTools.
• Codex CLI — два независимых рычага: sandbox_mode (ограничения файловой системы и сети, например workspace-write) и approval_policy (когда спрашивать подтверждение, например on-request).
• Cursor — подтверждение команд терминала и настройка авто-аппрува.

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

Hooks: детерминированные проверки в цикле

Второй контур защиты — хуки: команды, которые harness выполняет автоматически на события цикла. В Claude Code это, например, PreToolUse (до вызова инструмента) и PostToolUse (после успешного вызова).

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

Скрипт читает событие из stdin и может заблокировать действие (в Claude Code — выход с кодом 2 или permissionDecision: "deny"). Классические применения:

• PreToolUse на Bash: блокировать rm -rf, git push --force, обращения к защищённым файлам (.env, package-lock.json).
• PostToolUse на Edit|Write: авто-форматирование (Prettier), прогон линтера.
• Stop: отчёт по сессии, уведомление о завершении.

Хук — не модель: он детерминирован и срабатывает всегда, независимо от того, «решила» ли модель что-то опасное. Подробнее про хуки и правила — в Контекст-инжиниринге агентов.

---

Изоляция сессии и worktrees

Проблема: два агента в одном каталоге

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

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

git worktree как решение

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

git worktree add ../feature-a -b feature-a
git worktree add ../feature-b -b feature-b

Каждый агент работает в своём worktree: свои файлы, свои изменения, свой билд. Мержится результат так же, как любая ветка.

Инструменты встроили это в UI:

• Claude Code: флаг --worktree, а также автоматическая изоляция — фоновые сессии из agent view переносятся в собственный worktree под .claude/worktrees/; subagent может получить isolation: worktree во frontmatter.
• Cursor: автоматически создаёт и управляет worktrees для параллельных агентов.

Что копировать в worktree, а что нет

Worktree — чистая копия файлов под контролем Git. Файлы, которые в Git не хранятся, туда не попадут: .env.local, локальные секреты, кэши. Их нужно либо осознанно копировать, либо не давать агенту. Это частая причина «в worktree не работают тесты»: забыли про env или кэш зависимостей.

Практика: инициализация и очистка worktree

Типовой сценарий для параллельной работы — скрипт, который создаёт worktree и готовит его к работе:

#!/usr/bin/env bash
# scripts/new-agent-worktree.sh
BRANCH="$1"
WORKTREE_DIR="../worktree-${BRANCH}"

git worktree add "$WORKTREE_DIR" -b "$BRANCH"

# Копируем то, что агенту нужно, но чего нет в Git
cp .env.local "$WORKTREE_DIR/" 2>/dev/null || true

# Устанавливаем зависимости в worktree
(cd "$WORKTREE_DIR" && pnpm install --frozen-lockfile)

А после завершения — очистка:

git worktree remove "../worktree-feature-x"
git branch -d feature-x  # если ветка уже вмержена

Типичные проблемы:

---

Subagents и параллельные агенты

Что такое subagent

Subagent — отдельный экземпляр агента, которого главный агент запускает для подзадачи. Отличия от «просто продолжения диалога»:

В Claude Code subagent описывается markdown-файлом с YAML frontmatter:

---
name: reviewer
description: Ревьюит диффы на баги и нарушения конвенций
tools: Read, Grep, Glob
model: haiku
isolation: worktree
---
Ты — ревьюер. Не редактируй файлы, только находи проблемы
и возвращай список с путями и строками.

Зачем они нужны

• Изоляция контекста. Разведка кодовой базы («найди, где обрабатывается авторизация») не засоряет основной диалог: наружу возвращается только вывод, а не сотни прочитанных файлов.
• Параллельность. Независимые подзадачи (style-checker, security-scanner, test-coverage) могут идти одновременно — итог за время самой долгой, а не суммы.
• Ограничение прав. Subagent только для чтения физически не сможет изменить файлы.
• Экономия. Рутинную подзадачу можно направить на более дешёвую модель.

Модели параллелизма Claude Code

Claude Code предлагает несколько способов вести несколько задач:

Плюс существуют dynamic workflows (агент сам пишет workflow из subagents) и projects (долгий диалог в облаке).

«Многоагентность — это распределённые системы»

Как только агентов стало несколько, у вас распределённая система со всеми её проблемами: координация, гонки за одни и те же файлы, отсутствие общей памяти, дублирование работы. И главный счёт: стоимость растёт линейно — у каждого агента свой контекст и свои токены. «Запустить десять агентов» почти никогда не даёт десятикратного ускорения; для большинства сценариев достаточно 3–5.

---

Plan mode: сначала план

Read-only до одобрения

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

• Cursor — переключение в plan mode (Shift+Tab): агент запускает subagents для разведки и отдаёт интерактивный план.
• OpenCode — режим Plan по Tab: изменения отключены, агент предлагает, как реализует фичу.
• Claude Code — --permission-mode plan (read-only).
• Codex — встроенный Plan tool: «планы направляют правки; результат — работающий код».

Почему это дешевле

Исправить план — это две строки в тексте. Исправить уже сгенерированный код — перечитать дифф, разобраться в решениях, откатить. Plan mode ловит непонимание задачи до того, как оно превратилось в код, и заодно показывает, какие допущения сделал агент. Подробнее про постановку задачи — в AI в рабочем процессе фронтендера.

---

Headless-режим и CI

Запуск без человека

В headless (неинтерактивном) режиме агент запускается из скрипта, печатает результат и завершается. Это то, что позволяет встроить агента в CI/CD.

Claude Code:

claude -p "Найди баги и регрессии в текущем диффе. Не редактируй файлы." \
  --allowedTools "Read,Bash(git diff:*)" \
  --output-format json

Ключевые флаги:

Процесс возвращает код выхода (0 при успехе, ненулевой при ошибке), поэтому скрипт может ветвиться. У других инструментов аналоги: codex exec "..." у Codex, opencode -p "..." у OpenCode, headless-режим у Cursor CLI.

Сценарии

• Авто-ревью PR. Read-only прогон по диффу с отчётом о багах и регрессиях; правки — отдельно и после вашего решения.
• Триаж issues. Автоматические метки и категоризация по тексту задачи.
• Пакетные миграции. Обработка большого числа однотипных файлов.
• Routines по расписанию. Периодические задачи (у Claude Code — в облаке, без вашей машины).

Пример: авто-ревью в GitHub Actions

# .github/workflows/agent-review.yml
name: Agent Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get PR diff
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > diff.patch

      - name: Agent review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Проанализируй diff.patch. Найди: баги, проблемы безопасности, \
            нарушения конвенций проекта (см. AGENTS.md). Верни JSON: \
            {findings: [{file, line, severity, message}]}." \
            --allowedTools "Read,Bash(cat diff.patch)" \
            --output-format json \
            --max-turns 20 \
            > review-result.json

      - name: Parse and comment
        run: |
          # Скрипт парсит JSON и оставляет comment в PR
          node scripts/post-review-comment.js review-result.json

Ключевые моменты:

• Передача контекста. Дифф сохраняется в файл, агент читает его через Read или Bash(cat ...). Можно также передать тело issue/PR в промпт через переменные окружения.
• Структурированный вывод. --output-format json возвращает ответ модели в машиночитаемом формате. Парсить проще, чем текстовый вывод.
• Ограничение шагов. --max-turns 20 страхует от бесконечного цикла и неконтролируемого расхода токенов.
• Read-only по умолчанию. --allowedTools содержит только Read и Bash(cat ...) — агент не может редактировать файлы или запускать произвольные команды.

Ограничение стоимости в CI

Headless-запуск в CI стоит токенов. Типовые рычаги контроля:

Безопасность секретов в CI

Агент в CI получает доступ к коду, но не должен получать секреты проекта в контекст модели:

• API-ключ модели — через env шага, не коммитится. Агент его не видит (он в окружении процесса, а не в промпте).
• Секреты проекта (токены, пароли) — .env-файлы не передаются в промпт, worktree изолирует.
• Креды на запись — для read-only ревью достаточно contents: read. Для миграций — contents: write с короткоживущим токеном.
• Детерминированный режим — --bare отключает хуки, MCP, память хоста, что снижает поверхность атаки.

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

Правило безопасности для CI: по умолчанию read-only (Read, Glob, Grep, git diff/log), узкий --allowedTools, изолированное окружение, никаких секретов в контексте. Модель не должна получать право писать в прод-ветку просто потому, что «так удобнее».

---

Сравнение инструментов

Не существует «лучшего» инструмента: terminal-first удобен для автоматизации и параллельных сессий, IDE — для интерактивного ревью и навигации. Многие команды используют несколько одновременно. Общий для всех принцип один: модель просит — среда выполняет под вашим контролем.

---

Практики и антипаттерны

Что делегировать, а что нет

Гигиена сессий

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

Стоимость

Параллельность умножает не только скорость, но и токены: у каждого агента свой контекст. Полезно помнить из ментальной модели: длинный контекст и многошаговые циклы — это деньги. Prompt caching (когда неизменный префикс кэшируется) заметно снижает стоимость длинных сессий.

Антипаттерны

• YOLO-режим без проверок (--dangerously-skip-permissions и аналоги) вне изолированной песочницы.
• Несколько агентов в одном рабочем каталоге без worktrees.
• Вера отчёту агента («я сделал всё по спецификации») без прогона тестов и линтера.
• Гигантский AGENTS.md, который агент перестаёт учитывать целиком (см. context-engineering).
• Отсутствие хуков на защищённые каталоги (крипто, платежи, миграции).

---

Кейс: от задачи до ревью

Задача: добавить в таблицу заказов фильтр по диапазону дат.

1. Plan mode. Агент исследует компонент таблицы, хук загрузки данных и API-клиент, возвращает план: «добавить DateRangeFilter, расширить запрос, покрыть тестами». Вы правите план: зафиксировать бизнес-ограничение «не больше 90 дней».
2. Изоляция. Задача запускается в отдельном worktree (--worktree или фоновой сессией с автоматическим worktree), чтобы не мешать другим изменениям.
3. Реализация. Агент правит файлы, запускает pnpm lint и pnpm test (это прописано в правилах проекта). Хук PostToolUse форматирует каждый изменённый файл.
4. Ревью. Read-only субагент-ревьюер проходит по диффу и возвращает находки: забыт случай «пустой диапазон», граница 23:59 конца дня. Модель не выполняет код — это делает среда, а тесты служат объективным критерием.
5. Мерж. Вы проверяете находки, агент исправляет именно их, зелёные тесты и чистый дифф уходят в PR.

---

Ключевые тезисы для интервью

• Агент = модель + harness (цикл, инструменты, правила, права). Одна модель в разных инструментах ведёт себя по-разному.
• Цикл строится по паттерну ReAct: thought → action → observation, повторяется, пока есть вызовы инструментов, и ограничен лимитом шагов.
• Модель не выполняет код сама: она эмитит структурированный tool call, а выполняет его среда и возвращает результат как observation.
• Права, песочница и подтверждение — разные слои контроля: песочница ограничивает физические возможности, права — разрешённые действия, approval — что требует человека.
• Hooks (PreToolUse/PostToolUse) дают детерминированные проверки в цикле: блокировка опасных команд, авто-формат, прогон линтера.
• git worktree изолирует параллельные агентские сессии: у каждого свой checkout и ветка; файлы вне Git (env, кэш) нужно копировать отдельно. Типовая практика — скрипт инициализации worktree с pnpm install и копированием env, а после завершения — git worktree remove.
• Subagents изолируют контекст, ограничивают инструменты, работают параллельно и дешевле; многоагентность — это распределённая система с координацией и линейным ростом стоимости.
• Plan mode (read-only до одобрения) дешевле правки кода: непонимание задачи выявляется до генерации.
• Headless-режим (-p, --allowedTools, --output-format) встраивает агента в CI: авто-ревью, триаж, миграции — по умолчанию read-only. В GitHub Actions — отдельный workflow с --max-turns, structured JSON output и постингом результатов. Стоимость контролируют через max-turns, узкий набор инструментов, дешёвую модель и prompt caching. Секреты в CI: API-ключ модели — через env шага, секреты проекта не передаются в контекст модели, --bare отключает хуки и MCP.
• Agentic search (glob + grep) чаще выигрывает у векторного RAG для навигации по репозиторию: точность, свежесть, нулевая настройка.

---

Заключение

Агентские инструменты — это не «умный автокомплит», а управляемый цикл: модель предлагает действия, среда их выполняет под вашим контролем. Понимание этой архитектуры даёт три практических следствия:

• Безопасность — в harness. Права, песочница и хуки, а не надежда на благоразумие модели.
• Параллельность требует изоляции. Worktrees и отдельные контексты — база для нескольких агентов; без них вы получите конфликты и рост стоимости.
• План дешевле кода. Plan mode и чёткая задача экономят и время, и токены.

Выбор конкретного инструмента вторичен: terminal-first удобен для автоматизации, IDE — для интерактивного ревью. Начните с одного, настройте права и хуки, добавьте worktree для второй сессии — и только потом переходите к командам агентов.

---

Полезные ссылки

• Cursor — Best practices for coding with agents
• Claude Code — Run agents in parallel
• Claude Code — Hooks reference
• Claude Code — Run programmatically (headless)
• Claude Code — Create custom subagents
• OpenAI — Codex Prompting Guide
• OpenCode — Documentation
• ReAct: Synergizing Reasoning and Acting in Language Models (arXiv)
• Parallel AI coding agents in 2026 (dev.to)
• Why Coding Agents Still Use grep as Their Search Backbone