Цикл локального агента кодування: 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.

Перш ніж схвалити будь-які зміни, запитайте:

• Чи вказує план заплановану реалізацію та тестування?
• Чи обмежується він однією функціональністю?
• Чи зазначено, які зміни валідації він пропонує?

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

Різниця та результат тесту — це кінцевий продукт

Як тільки план схвалений, щоразу повторюйте ту саму послідовність перевірки.

Дивіться лише узгоджені файли

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, щоб дізнатися про зміни, які готові до збереження, незафіксовані файли чи інші зміни, перш ніж вважати експеримент відкинутим.

Якщо весь гілка може бути видалена, приберіть worktree після перевірки його стану та збереження всього, що варте збереження:

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, які фактично встановлені на вашому пристрої.

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