Цыкл лакальнага агента кадавання: Aider, Ollama, Git worktree і лёгкі адкат

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

Кансерватыўны набор для такога цыклу прэдпакоўвае, што рэпазітары ўжо знаходзіцца пад кераваннем Git і ў яго ёсць спецыяльны каманд для тэставання:

• Агент: Aider
• Час выканання модэлі: Ollama, якая запускае мадэль на локальным камп’ютары
• Ізоляція: рабочая дрэва Git
• Пошук: rg, запускаецца з корня рэпазітарыя
• Аверыка: будзь-якая каманда для тэставання, якая ўжо ёсць ў рэпазітарые
• Вяснаванне: git diff, пасля чаго або здзейснюецца зберэжчыце, або git restore

Толькі агент і местны рантайм являюцца новымі. Усе іншае — цэлкам звычныя інструменты рэпазітарыя, і наладка не павінна ператворыцца ў другую платформу для разработкі.

Ролі простыя. Ollama аддае службу модэлю. Aider працюе ўнутры рэпазітарыя Git. Worktree дае заданню саўстанні свайго чэкауту, зазвычай на спецыяльнай гілке, а 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. Запускайце яго ў worktree, чытайце разлічныя версіі пасля кожной змены і заставайце рашэння пра фіксацыю змены ў руках чалавека.

У яго таксама ўключаныя команды для чату, карта рэпазітарыя, опцыі налашчання і контроль ліміту кантэксту. Яны дапамагаюць у навігацыі, але жадна з іх не задае межы чысткі кантэксту і не падтверджвае правільнасць патча.

Зробіце першы крок планам

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

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.

Такі вказванні запобiegаюць калькам: задачам, які растуць без кантролю, змянам па неякразныя траекторыі, і патчам, для якіх няма чытальнага спосабу пераканаліць іх правільнасць.

Як можна раней адмовіцца ад масштабных планаў

Хорашая першая адпаведзь выглядае так:

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 быў зменены, хоць у вказаўках гэта было забранае
• файлы былі зменены паza даговораную спіс
• перфарматаванне, якое не мае нічынаго з багам
• новы тэст, які праходзіць без адносу да цялевага паведання
• корэкцыя верыфікацыі, якая таксама адхоўляе легітымныя назвы

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

Запускайце спецыяльную перацэнку

<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. Вярненне да пачатковага стану — гэта нормальны працэс, і самэ гэта робіць эксперыменты з маленькім агентам правільнымі для павтарэння.

Межы: файловая сістэма, правыя, кантэкст

Запуск з корня рэпазітарыю

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

Катэгорыя працы задае стандартны дыячы, але не накладзе жадных обмежэнняў. Тое, да чаго можа дасягнуць агент, выклікаецца правамі ОС, настройкамі інструментаў і наявным сэндбоксам.

Жадана згода на побачныя эфекты

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

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, якія фактычна ўстановлены на вашам камп’ютары.

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