Понятный AI-агент: как заставить думать как самый ленивый...

Понятный AI-агент: как заставить думать как самый ленивый сеньор

Практическое руководство по настройке AI-агентов с использованием Claude Code и инфраструктуры Proxmox. Узнайте, как писать код, который никогда не писали.

Настройка Claude Code для AI-агентов

Настройка Claude Code для AI-агентов

Конфигурация среды разработки

Для запуска Claude Code в Proxmox рекомендуется использовать систему Linux (Ubuntu 22.04 LTS или Debian 12) с актуальными версиями Docker и kubectl. Создайте виртуальную машину с достаточным количеством RAM (минимум 8 ГБ) и процессорной мощностью для комфортного работы с AI-агентом.

Установка и базовая конфигурация

bashКопировать
# Скачиваем и распаковываем Claude Code
wget https://github.com/claudecode/claude-code/releases/download/v0.21.0/claude-code-linux-amd64
chmod +x claude-code-linux-amd64
sudo mv claude-code-linux-amd64 /usr/local/bin/claude-code

# Проверка установки
claude-code version

После установки создайте конфигурационный файл ~/.claudecode/claude-code.toml:

tomlКопировать
# ~/.claudecode/claude-code.toml
[general]
name = "AI-Agent-Controller"
language = "ru"
default-model = "codellama-34b-instruct"  # или Claude Code GPT-4o

[cli]
app_name = "AI Agent Controller"
workspace = "/home/alexei/ai-agents"

[plugins]
# Плагин для автоматизации задач
plugin = "claude-code-plugin-automation"
config = {
    "automation_rules" = [
        "create_backup_of_important_files",
        "run_daily_health_check",
        "cleanup_temporary_files"
    ]
}

Настройка окружения в Proxmox

В Proxmox VE создайте контейнер для Claude Code с нужными ресурсами:

bashКопировать
# Создаём контейнер
pct create -n claude-code -t debian-11 -d 4G -c 2 -p 1000 \
  --graphics --graphics-modes vga \
  --boot /dev/root

# Примонтируем папку с конфигурацией
pct setup -n claude-code -p /home/alexei/ai-agents

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

Плагин claude-code-plugin-automation позволяет автоматизировать рутинные задачи без участия человека. В примере ниже настраиваем плагин для создания резервных копий и ежедневных проверок здоровья системы.

Настройка автоматизированного плагина

tomlКопировать
# ~/.claudecode/claude-code.toml (дополнительная секция)
[plugins.automation]
enabled = true
rules = [
    {
        "name" = "backup_important_files",
        "description" = "Создаёт дневную резервную копию важных директорий",
        "steps" = [
            "identify_files_to_backup = [\"/home/alexei/projects\", \"/home/alexei/data\"]",
            "create_backup_dir = \"/backups/daily-2026-01-27\"",
            "run_backup_command = \"rsync -a --delete /home/alexei/projects /backups/daily-2026-01-27/\"",
            "notify_completion = true"
        ]
    },
    {
        "name" = "health_check",
        "description" = "Проверяет состояние критических сервисов",
        "steps" = [
            "check_docker_containers = [\"app-1\", \"api-1\"]",
            "check_network_ports = [\"443\", \"8080\"]",
            "run_health_endpoint = \"/health\"",
            "log_results = \"/var/log/health-check.log\""
        ]
    }
]

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

pythonКопировать
# script/backup_agent.py
import subprocess
from pathlib import Path

def run_backup():
    """Функция создания дневной резервной копии"""
    backup_dir = Path("/backups/daily-2026-01-27")
    backup_dir.mkdir(parents=True, exist_ok=True)
    
    # Создаём дамп важных директорий
    for dir_path in ["/home/alexei/projects", "/home/alexei/data"]:
        if Path(dir_path).exists():
            subprocess.run(
                ["rsync", "-a", "--delete", str(dir_path), str(backup_dir)],
                check=True,
                capture_output=True
            )
    
    # Логируем результат
    print(f"Резервная копия создана: {backup_dir}")

Интеграция с Proxmox

Для работы с узлами Proxmox в Claude Code можно использовать плагин proxmox или написать собственный скрипт:

bashКопировать
# Скрипт для управления узлами Proxmox
#!/bin/bash
# manage-nodes.sh

# Получаем список доступных узлов
pct list --nodes

# Проверка статуса узла
pct status --nodes <node-name>

# Создание под-узла для агентной инфраструктуры
pct create -n agent-node -t debian-11 -d 8G -c 4 \
  --graphics --graphics-modes vga \
  --boot /dev/root

Дополнительные плагины из статьи

В статье QA-агенты Momentic ищут баги в веб и мобильных приложениях описывается практическое применение плагинов для автоматизации поиска ошибок. Аналогично, Graphify-Labs/graphify: Кодовая база в запросную графичес... предлагает методы генерации визуального кода из текстовых описаний.

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

Проверка работоспособности

После настройки убедитесь, что Claude Code корректно инициализируется:

bashКопировать
claude-code --version
# Вывод: Claude Code version 0.21.0

# Проверка плагина
claude-code plugin list
# Должно вывести: [claude-code-plugin-automation]

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

Архитектура инфраструктуры Proxmox

Архитектура инфраструктуры Proxmox

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

Размещение агентов на нодах

Во-первых, я не держу всех агентов на одной ноде. Если выйдет из строя Винни-Пух, не должны упасть все агенты сразу. Кластер из трёх нод на Proxmox VE позволяет распределить нагрузку и оставить резерв.

С практической точки зрения, агент — это либо лёгкий LXC-контейнер, либо полноценная VM. Для Claude Code и прочих агентов, которые больше работают с сетью и API, чем с тяжелыми вычислениями, я использую LXC. Они стартуют за секунды, легко ограничиваются по ресурсам и не жрут память на гипервизор.

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

bashКопировать
pct create 101 /var/lib/vz/template/cache/debian-12-standard_12.4-1_amd64.tar.zst \
  --hostname claude-agent-01 \
  --memory 2048 --swap 512 \
  --cores 2 --cpuunits 1024 \
  --rootfs local-zfs:8 \
  --net0 name=eth0,bridge=vmbr1,ip=10.10.10.11/24,gw=10.10.10.1 \
  --onboot 1

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

После создания настраиваю límites и автозапуск:

bashКопировать
pct set 101 --lock 0
pct set 101 --onboot 1 --startup order=1,up=10,down=30

Внутри контейнера агент запускаю через systemd. Einheit простая, без лишней магии:

iniКопировать
[Unit]
Description=Claude Code Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/claude-agent --config /etc/claude-agent/config.yaml
Restart=always
RestartSec=5
User=agent

[Install]
WantedBy=multi-user.target

Комментарий в конфиге не нужен — всё и так понятно, но я всегда добавляю строку с объяснением, почему RestartSec=5: даём агенту время освободить порты перед перезапуском, иначе получаем «адрес уже занят».

Где размещать: stateful-агенты, которые пишут локальную базу или кэш, ставлю на ноду с локальным ZFS-зеркалом. Stateless-агенты можно мигрировать между нодами через pct migrate без простоев. Если мы посмотрим на логи моего кластера, то увидим, что агенты с базой данных никогда не мигрируют — это правило, а не рекомендация.

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

Бэкап и резервное копирование

Бэкап без проверки восстановления — это не бэкап, а просто копирование файлов. Я придерживаюсь правила: архив создаётся автоматически, а восстановление проверяю вручную раз в квартал.

Для кластера Proxmox использую Proxmox Backup Server (PBS) или vzdump с целевым хранилищем на TrueNAS. В моей конфигурации TrueNAS отдаёт NFS-шару, куда Proxmox складывает снимки контейнеров и VM.

Пример задачи бэкапа через командную строку:

bashКопировать
vzdump 101 --mode snapshot --compress zstd --storage backup-nfs --retention 7

Что здесь происходит:

• --mode snapshot — консистентный снимок без остановки контейнера;
• --compress zstd — сжатие, которое не грузит процессор так сильно, как gzip;
• --storage backup-nfs — хранилище, примонтированное через NFS с TrueNAS;
• --retention 7 — хранить семь последних копий.

Автоматизирую через cron на ноде Винни-Пух:

cronКопировать
0 2 * * * root vzdump 101 102 103 --mode snapshot --compress zstd --storage backup-nfs --retention 7

Также бэкапю конфигурацию кластера /etc/pve — без неё восстановление контейнеров будет сложнее, чем пересоздание с нуля.

Восстановление контейнера из бэкапа:

bashКопировать
pct restore 101 /mnt/backup/vzdump-lxc-101.tar.zst --storage local-zfs

После восстановления обязательно проверяю, что сетевой интерфейс поднимается и systemd-сервис агента стартует без ошибок:

bashКопировать
systemctl status claude-agent
journalctl -u claude-agent -n 50

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

Оптимизация производительности системы ECC для агентов описывает, как снизить нагрузку на диск во время бэкапа, чтобы агенты не простаивали.

Паттерны написания кода

Паттерны написания кода

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

В этом разделе два паттерна, которые я применяю дома на кластере из трёх нод Proxmox и на клиентских проектах.

Принцип минимального кода

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

Пример из практики. Нужно было собрать отчёт по ошибкам 5xx из логов Nginx на нескольких серверах. Агент предложил Python-скрипт на сто строк с библиотеками для парсинга, агрегации и вывода в CSV. На практике достаточно одной команды:

bashКопировать
awk '$9 ~ /^5/ {print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head -10

Команда делает одно: выводит топ-10 IP с наибольшим количеством серверных ошибок. Нет зависимостей, нет виртуального окружения, нет файла requirements.txt. Если логи ротируются, команда продолжает работать. Это и есть предсказуемость.

Когда агент пишет код для Claude Code. Описывай задачу так, чтобы решение было максимально коротким. Вместо «напиши систему мониторинга с веб-интерфейсом» скажи «напиши скрипт, который проверяет доступность порта 443 и пишет в journald». Агент сам выберет подходящий инструмент, и чаще всего это будет оболочка или короткий скрипт на Python, а не целая платформа.

Если мы говорим об инфраструктуре на Proxmox, минимальный код означает предпочтение LXC-контейнерам вместо полноценных виртуальных машин там, где достаточно изоляции на уровне ОС. Меньше слоёв — меньше кода, который нужно обновлять.

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

Советы по читаемости

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

Во-первых, называй вещи своими именами. Переменная data ничего не говорит. nginx_error_count или proxmox_vm_status сразу понятны. Агент не угадает вашу интенцию, если имя переменной не несёт смысла.

Справедливость комментариев. Комментарий должен объяснять «почему», а не «что». Строка i += 1 — это инкремент счётчика. Комментарий «инкрементируем i» бесполезен. А вот «пропускаем первую строку заголовка CSV» — полезен.

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

Пример. Плохо:

pythonКопировать
r = [x for x in d if x['s'] == 200 and x['t'] > 1000]

Хорошо:

pythonКопировать
# Оставляем только успешные запросы, дольше секунды
slow_successful = [
    request for request in logs
    if request['status'] == 200
    and request['duration'] > 1.0
]

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

Если код становится трудно читать, это сигнал, что пора разбить его на части. Агенты тоже лучше работают с маленькими функциями, чем с монолитными скриптами. В статье про Graphify-Labs/graphify: Кодовая база в запросную графичес... показано, как представление кода в виде графа помогает находить связанные части — полезно, когда проект разрастается.

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

Практические рекомендации

Практические рекомендации

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

Проверка качества кода

Во-первых, никогда не позволяйте агенту коммитить напрямую в основную ветку. Claude Code может предложить изменения, но финальное решение остаётся за человеком. Я использую отдельную ветку для каждого задания агенту и открываю merge request только после ручного ревью.

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

1. Статический анализ. Пропустите сгенерированный код через линтер и типчекер, подходящие для языка. Для Python это ruff и mypy, для Go — golangci-lint, для TypeScript — eslint с typescript-eslint.
2. Тесты. Если агент написал функцию, он должен написать и тесты к ней. Запустите их локально перед слиянием.
3. Ручной ревью diff-а. Читайте каждое изменение. Спрашивайте себя: зачем эта строка, что она ломает, если удалить.

Пример конфига pre-commit для Python-проекта, который я использую на своих серверах:

yamlКопировать
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.5.0
    hooks:
      - id: ruff
        args: [--fix]
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.11.0
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]

Если вы используете Claude Code как плагин в IDE, настройте его так, чтобы он не имел прав на запись в main или master. Это не параноя, это предсказуемость конфигурации.

Для автоматического поиска багов в уже написанном агентом коде стоит присмотреться к QA-агенты Momentic ищут баги в веб и мобильных приложениях — они интегрируются в CI и могут дополнить ручной ревью. Если нужно понять, какие части системы затронуты изменениями, полезен Graphify-Labs/graphify: Кодовая база в запросную графическую базу данных. Безопасность агентных оболочек описывается в ECC: оптимизация и безопасность агентных оболочек.

Мониторинг и логирование

Агент может упасть молча. В отличие от обычного сервиса, который вернёт 500-ю ошибку, AI-агент может просто перестать отвечать, оставив после себя полпути к решению и полунаписанный конфиг. Поэтому мониторинг для агентов — не опция, а необходимость.

Я запускаю агентов под systemd. Это позволяет собирать логи через journald и перезапускать процесс при сбое. Пример unit-файла для агента на базе Claude Code:

iniКопировать
[Unit]
Description=Claude Code AI Agent
After=network.target

[Service]
Type=simple
User=agent
WorkingDirectory=/opt/ai-agent
ExecStart=/usr/local/bin/claude-code --mode agent --task queue
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Логи пишутся в journald, откуда я забираю их в Loki через Promtail. В Grafana нахожу панели с количеством ошибок агента, длительностью выполнения задач и числом вызовов инструментов. Если агент не отчитывался больше получаса — срабатывает алерт в Alertmanager.

Пример правила оповещения в Prometheus:

yamlКопировать
groups:
  - name: ai_agent
    rules:
      - alert: AIAgentSilent
        expr: absent(agent_last_heartbeat_seconds > 0)
        for: 30m
        labels:
          severity: warning
        annotations:
          summary: "AI-агент не подаёт признаков жизни"
          description: "Агент не отчитывался более 30 минут. Проверьте логи в journald и очередь задач."

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

Если вы разворачиваете агентов на Proxmox, вынесите их в отдельные LXC-контейнеры или виртуальные машины. Так сбой одного агента не повлияет на другие сервисы, а ресурсы ограничены жёстко.

Если агент работает медленно, поможет Оптимизация производительности системы ECC для агентов. Альтернативный подход к интеграции агентов показан в DeepSeek Harness: всё как плагин в DeepSeek.

Часто задаваемые вопросы

Зачем держать агента на Proxmox, а не на своём ноутбуке?

На ноутбуке удобно экспериментировать — но для предсказуемости лучше отдельная среда. Агент будет писать конфиги и скрипты, которые потом запустятся на сервере, поэтому среда разработки должна максимально совпадать с боевой. В Proxmox можно ограничить ресурсы, сделать снимок перед экспериментом и не бояться, что что-то сломается. Если ноутбук закроют, агент прервёт задачу на полпути.

Сколько будет стоить запуск такого агента?

Зависит от модели и объёма запросов. Если используете облачный API, платите за токены — простые задачи обойдутся дешево, а генерация целых модулей может ударить по кошельку. С практической точки зрения, ленивый сеньор не тратит дорогую модель на запись systemd-юнита, для этого хватит локальной модели или даже шаблона. Обязательно настройте мониторинг расходов, чтобы не получить неожиданный счёт в конце месяца.

Нужно ли мне самому писать код, если за это отвечает агент?

Нужно уметь читать и проверять то, что сгенерировал агент. Вы несёте ответственность за каждый коммит — даже если его написал ИИ. Если агент предложит странный Docker Compose или необычный конфиг Nginx, вы должны понять, почему он так сделал, прежде чем применять. Иначе получите не предсказуемую систему, а чёрный ящик.

Как заставить агента писать простой код, а не нагромождать абстракции?

В инструкции к агенту чётко прописывайте ограничения: одна задача, без лишних слоёв, без фреймворков там, где хватит Bash или systemd. Требуйте, чтобы агент объяснял каждое решение, и отказывайтесь от вариантов с «возможно, пригодится в будущем». Ленивый сеньор ценит скучный, предсказуемый код, который легко поддерживать через полгода.

Безопасно ли отправлять свой код в облачную модель?

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