Запуск Bash-команд: как это делает агент

Именно поэтому агент и оболочка неразделимы: без Bash агент умел бы только редактировать текст, но не мог бы проверить, работает ли код. Вся обратная связь — ошибки, результаты тестов, версии пакетов — приходит через вывод команд. Умение контролировать этот канал означает контроль над всем, что агент делает в вашей системе.

1. Чтение системы. ls, cat, git status — агент изучает проект и среду.
2. Проверка работы. Запуск тестов, линтеров и сборки после изменений.
3. Изменение состояния. Установка пакетов, миграции, git-операции.
4. Восстановление. Откаты, очистка, перезапуск сервисов.

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

Агент формирует команду → harness запускает её в Bash
→ агент получает stdout, stderr и код возврата
→ агент анализирует результат и продолжает работу

Ключевая деталь — код возврата (exit code). Программа завершается с числом: 0 означает успех, любое другое значение — ошибку. Агент видит не только текст вывода, но и этот код, поэтому он «знает», завершилась ли команда удачно, даже если текст вывода этого прямо не говорит.

Stdout, stderr и код возврата

Вывод команды делится на два потока: stdout — обычный результат (список файлов, вывод тестов) и stderr — сообщения об ошибках. Оба потока агент получает целиком и рассматривает вместе с кодом возврата. Понимание этой триады помогает читать логи агента: если код возврата 0, но в stderr есть предупреждения — команда прошла, но на что-то обратила внимание.

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

1. Просмотр. ls, cat, head, grep — чтение файлов и структуры проекта.
2. Статус. git status, git diff, git log — понимание текущего состояния.
3. Проверка. Запуск тестов, линтеров, компиляторов и сборки.
4. Зависимости. Установка и обновление пакетов менеджером зависимостей.
5. Служебные. pwd, echo, touch, mkdir — мелкие операции с файлами.
6. Git-операции. add, commit, checkout — фиксация и откат изменений.

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

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

Правило простое: команда опасна, если её последствия нельзя легко отменить. Удаление, перезапись, изменение прав и работа вне проекта — всегда повод остановиться и проверить. Безопасность здесь строится не на доверии к агенту, а на контроле конкретной команды перед её запуском.

Хороший harness не даёт агенту молча выполнять всё подряд: перед запуском команда показывается вам, и вы решаете, разрешить её или нет. Это и есть разрешения (permissions). Уже сейчас важно понять механику: агент предлагает команду, вы видите её до выполнения.

1. Предпросмотр. Команда отображается до запуска — вы успеваете её прочитать и оценить.
2. Разрешить или отклонить. Вы выбираете, запускать команду или нет, и можете попросить изменить её.
3. Автозапуск безопасных. Частые безобидные команды (git status, запуск тестов) можно разрешить без вопросов.
4. Запрет опасных. Команды из «опасной» категории можно запретить совсем или требовать подтверждение каждый раз.

Главный навык — читать команду до запуска, а не после. Взгляните на команду, которую предлагает агент, и задайте один вопрос: «что будет, если эта команда выполнится не так, как задумано?» Если ответ вас не устраивает — не запускайте, а попросите безопасный вариант.

У каждой команды есть скрытая цена, о которой легко забыть: её вывод попадает в контекст сессии и занимает токены. Чем длиннее вывод — тем больше контекста он съедает, а переполненный контекст — прямая дорога в Dumb Zone из урока 13.

Из этого следует практический вывод: не позволяйте агенту вываливать в контекст всё подряд. Длинный вывод стоит токенов, даже если вы его не читаете, — он просто занимает место в сессии и приближает границу Smart Zone. Чем аккуратнее команды, тем дольше живёт сессия.

Команды иногда падают — и это нормальная часть работы. Агент видит код возврата и stderr, поэтому он сам замечает ошибку и обычно пытается исправить её. Ваша задача — не паниковать, а понять, почему команда не сработала, и решить, пускать ли агента на вторую попытку.

1. Ошибка окружения. Не установлен пакет, нет прав, занят порт — часто лечится одной командой.
2. Ошибка в команде. Опечатка, неверный путь — агент сам увидит это в stderr и поправит.
3. Повторные попытки. Агент может запускать одну команду несколько раз — убедитесь, что он меняет подход, а не долбит в ту же стену.
4. Таймаут. Долгие команды (сборка, установка) могут превышать лимит — разрешите повторный запуск или разбейте команду на части.

Полезный приём — просить агента объяснять, что пошло не так. Одна фраза «что говорит вывод ошибки?» перед повторным запуском экономит ходы: агент анализирует stderr и приходит к решению, а не гадает. Помните и об обратной стороне: команды, которые «висят» или повторяются бесконечно, — сигнал остановиться и переформулировать задачу, а не давать агенту бесконечные попытки.

Контроль строится на трёх вещах: предпросмотр команды перед запуском, понимание, какие команды опасны, и учёт того, что вывод команды занимает контекст. Освоив эти три уровня, вы получаете агента, который работает быстро, но никогда не действует «втихую».

В следующем уроке разберём разрешения (permissions): как настроить права агента так, чтобы безопасные команды выполнялись без вопросов, а опасные — только с вашего явного согласия.

1. Bash — командная оболочка, программа, выполняющая текстовые команды в системе.
2. Оболочка (shell) — среда для запуска команд и программ, синоним Bash в контексте курса.
3. Команда — текстовая инструкция, которую выполняет оболочка.
4. Инструмент bash — механизм harness, через который агент запускает команды оболочки.
5. Stdout — стандартный поток вывода: обычный результат команды.
6. Stderr — стандартный поток ошибок: сообщения об ошибках и предупреждения.
7. Код возврата (exit code) — число, с которым завершается команда: 0 — успех, иное — ошибка.
8. Предпросмотр команды — отображение команды пользователю до её запуска.
9. Разрешение (permission) — право, которое пользователь даёт агенту на выполнение команды.
10. Таймаут — ограничение времени выполнения команды.
11. Harness — программа-оболочка, через которую агент выполняет команды и управляется пользователем.
12. Контекст — информация, доступная агенту в текущей сессии, ограниченная объёмом токенов.
13. Dumb Zone — состояние сессии, в котором переполненный контекст снижает качество рассуждений агента.
14. Smart Zone — продуктивная зона сессии, в которой агент рассуждает качественно.