Цикл локального агента по программированию: Aider, Ollama, рабочие ветки Git и удобный механизм отката.

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

Консервативная стек-структура для такого цикла предполагает наличие репозитория, уже управляемого Git, с специализированным командом тестирования:

• Агент: Aider
• Время выполнения модели: Ollama, обслуживающий модель на локальной машине
• Изоляция: рабочая дерево Git
• Поиск: rg, запускаемый из корня репозитория
• Проверка: любая специализированная команда тестирования, уже имеющаяся в репозитории
• Восстановление: git diff, затем либо сохранение изменений, либо git restore

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

Роли просты: Ollama обслуживает модель, Aider работает внутри репозитория Git. Рабочая ветка позволяет создавать собственную копию данных для задачи, обычно на отдельной ветке, а команда git restore может восстановить незакоммитированные изменения в определённые файлы. Такая структура преднамеренно узкая и предназначена для работы с репозиториями, которые должны оставаться подлежащими проверке и восстановлению. Это не критерий оценки, и эти инструменты не утверждают, что они превосходят альтернативы во всех ситуациях. Команды, названия моделей и правила утверждения также меняются в зависимости от установленных версий и локальной конфигурации.

Цикл, который может проверить человек

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

Последовательность действий:

1. Создать изолированную рабочую ветку.
2. Найти реализацию и существующий тест для неё.
3. Определить один результат и его границы.
4. Запросить план перед любыми изменениями.
5. Утвердить план или скорректировать его.
6. Прочитать отчёт о различиях.
7. Запустить проверку проекта.
8. Сохранить изменения или восстановить исходное состояние.

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

Пример: пустые имена отображения

Представьте сервис на TypeScript, который принимает пустые имена отображения, хотя API должен их отклонять. В репозитории имеется специальный тестовый файл и скрипты npm для проверки корректности данных.

Задача не сводится к очистке процедуры валидации. Она сформулирована следующим образом:

Отклонять имена для отображения, состоящие исключительно из пробелов; обновить существующий файл тестов; не менять публичный API; запустить соответствующий тест.

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

Выделить эту изменение отдельной процедурой проверки

Из основной процедуры проверки:

git worktree add -b fix/display-name-validation ../service-display-name-fix
cd ../service-display-name-fix

Рабочее дерево — это второй рабочий каталог, привязанный к тому же репозиторию. Приведённая выше команда создаёт каталог ../service-display-name-fix на ветке fix/display-name-validation, оставляя основной каталог свободным для другой работы.

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

Сначала найдите код и тесты

Используйте собственную терминологию репозитория для определения объёма работы:

rg -n "displayName|display name" src test

Предположим, поиск возвращает:

src/users/validateProfile.ts
test/users/validateProfile.test.ts

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

Запуск Aider на локальной модели Ollama

Перед этим шагом убедитесь, что установлены Git, Aider, Ollama и rg, а также что на этом компьютере доступна среда выполнения Ollama. Выбранная модель также должна работать с установленными версиями Aider и Ollama. В документации Aider описаны поставщики моделей Ollama: убедитесь, что нужная модель существует в Ollama, затем запустите Aider из рабочей директории, используя префикс ollama_chat/ перед именем модели.

ollama pull <installed-model>
aider --model ollama_chat/<installed-model>

Замените <installed-model> на тег, который фактически используется Ollama. Тот же тег присутствует в обоих командах, поскольку Ollama обслуживает данный модель, а Aider выбирает его по имени.

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

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

Превратите первый шаг в план

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

Task: Fix whitespace-only display names being accepted.

Files in scope:
- src/users/validateProfile.ts
- test/users/validateProfile.test.tsConstraints:
- Preserve the public API.
- Do not edit generated files, lockfiles, deployment configuration, or unrelated tests.
- First, explain the current behavior, name the files you would change, and propose the smallest fix.
- Do not edit files until I approve the plan. Treat this as a required review step, and use any available approval controls in your local agent configuration to enforce it where possible.Validation:
- Run: npm test -- validateProfile
- Report the exact command run, files changed, test result, and any unresolved assumption.

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

Отклоняйте общие планы заранее

Хороший первый ответ выглядит примерно так:

1. Inspect src/users/validateProfile.ts to confirm how displayName is validated.
2. Inspect test/users/validateProfile.test.ts for the existing validation-test pattern.
3. Add a failing test for a whitespace-only displayName.
4. Make the smallest validation change required to reject that input.
5. Run npm test -- validateProfile.

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

• Указано ли в плане конкретное место реализации и тестирования?
• Ограничивается ли план одним поведением?
• Указано ли, какие изменения валидации он предлагает?

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

Результаты diff и тестов — это конечный продукт

После одобрения плана каждый раз повторяйте ту же последовательность проверок.

Смотрите только на согласованные файлы

git diff -- src/users/validateProfile.ts test/users/validateProfile.test.ts

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

Обратите внимание на то, что может скрываться в кратком отчете сессии:

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

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

Выполните целенаправленную проверку

<repository-focused-test-command>

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

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

Намеренно сохранить или отклонить изменение

Если результаты сравнения и тестирования выглядят корректно:

git status
git add src/users/validateProfile.ts test/users/validateProfile.test.ts
git commit -m "Reject whitespace-only display names"

Если они этого не сделают:

git restore src/users/validateProfile.ts test/users/validateProfile.test.ts

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

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

git worktree remove ../service-display-name-fix

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

Границы: файловая система, разрешения, контекст

Запуск из корня репозитория

Запустите агента в каталоге проекта или в его специальном worktree. Попытки запустить его из личного каталога в надежде, что команда-промпт установит границы, не сработают.

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

Умышленное одобрение побочных эффектов

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

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

Практические основные принципы:

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

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

Сохраняйте конфигурацию простой и видимой

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

Предоставьте необходимый контекст

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

Договор проекта для повторных задач

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

Project contract

Goal:
- [Describe one bounded outcome.]Scope:
- You may edit: [paths]
- Do not edit: [paths, generated files, secrets, deployment configuration]Conventions:
- Follow: [formatter, naming, architecture rules]
- Preserve: [public APIs, compatibility constraints]Validation:
- Run: [exact test, lint, type-check, or build command]
- Report: commands run, files changed, failures, and unresolved assumptionsDefinition of done:
- The requested behavior is implemented.
- Relevant checks have run, or the reason they could not run is stated.
- The final response summarizes the diff and any follow-up work.

Формат не имеет значения. Важно лишь то, чтобы ограничения были видны.

Возможные сбои и следующие шаги

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

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

Изменения вне рамок задачи. Отклоните патч, восстановьте не связанные файлы и укажите запрещенные пути в следующем запросе.

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

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

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

Более быстрый агент, создающий более крупные и сложные для анализа различия, не улучшает рабочий процесс.

Настраивайте по одному параметру за раз

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

Настройка Aider чувствительна к версии, поэтому перед повторным использованием стоит проверить страницы с её конфигурацией и историей выпусков. Сравнивайте каждую команду, идентификатор модели и опцию конфигурации с версиями Aider и Ollama, фактически установленными на вашем устройстве.

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