CLI-агенти: Практичне використання

💡 Усі статті, обговорення, новини про AI — в одному місці. Приєднуйтесь до AI спільноти!

Привіт! Мене звати Володимир, я Microsoft MVP та працюю в beeDynamics на позиції розробника Business Central. Я регулярно пишу технічні статті в своєму блозі. Також підтримую декілька open-source проєктів, детальніше в профілі github.

Продовжуючи серію про AI-агентів у терміналі, я хочу перейти до більш реалістичних, практичних прикладів. Мета цієї статті — показати, що робота з AI-агентами може бути простою та доступною. Я продемонструю це на прикладі розв’язання реальної задачі для Business Central у репозиторії Microsoft.

Повна автоматизація процесів розробки не є метою цією статті, і ваш досвід може відрізнятися від мого. Це лише один із можливих варіантів практичного використання та моя особиста думка.

Попередні пости

1. CLI-агенти: Новий стандарт для програмування з AI
2. CLI-агенти: розбираємось з Claude Code

Зміст

1. Вступ
2. Передумови
3. Задача
4. Планування
5. Реалізація
6. Автоматизоване тестування
7. Code Review
8. Ручне тестування
9. Продовження реалізації
10. Документація
11. Підсумок
12. Source Code

Вступ

У своїй роботі я постійно використовую AI-агентів, і більшість мого коду тепер генерується LLM. Однак я маю власний погляд на автоматизацію. Я волію уважно переглядати кожен рядок коду й ретельно вивчати те, що було створено. Я твердо переконаний, що проєкт, який легко підтримувати та читати, потребує уважного перегляду людиною й не може бути просто «vibe-coded».

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

Я досі пишу код і досі читаю код, тому що мені це подобається й тому що це допомагає мені підтримувати навички читання та написання коду.

Найбільша цінність цієї технології полягає в її симбіозі з людським інтелектом.

Я також помітив, що велика кількість розробників досі уникає використання LLM у своїй роботі з багатьох різних причин. Одна з таких причин — нерозуміння того, як працювати з LLM-агентами та яку цінність вони можуть принести.

Моя сьогоднішня мета — показати на практиці, як можна використовувати LLM-агента та які переваги він може надати.

Передумови

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

VS Code — це основна IDE, яку я використовую, коли мені потрібно зробити щось вручну. Це також просто зручний редактор для перегляду того, що зробив LLM-агент. Я також використовую наступні розширення VS Code:

• AL Language — надає formatters, linters та LSP для розробки під Business Central.
• Useful support extensions for AL — для кращого досвіду при написання коду на AL.
• Markdown Preview — для перегляду markdown-файлів.

Claude Code — це AI-агент, якому я особисто віддаю перевагу над іншими. У вашому випадку це може бути Codex, Copilot CLI, Open Code тощо. Це основа для роботи з LLM.

Окрім того, я використовую наступні додаткові інструменти в Claude Code:

• AL LSP. Я використовую версію Torben, але зовсім нещодавно Microsoft випустила і власну реалізацію. Саме це дозволяє агенту краще розуміти codebase, залежності та linters.
• Microsoft Learn MCP — цей MCP дозволяє агенту ефективно шукати інформацію в документації Microsoft Learn.
• AL Development Tools package — цей пакет містить AL .NET Tool, який забезпечує зручний доступ до поширених AL Development Tools для pipelines та автоматизує процеси через термінал.

Оскільки моєю задачею буде реалізація додаткової функціональності в модулі System Application для Dynamics 365 Business Central, я також використовую два агентські Skills. Вони значно покращують feedback loop між агентом і рішенням задачі. Їх можна викликати безпосередньо командою або просто на основі контексту вашого запиту до агента, як я згадував у попередніх постах. До речі, ці Skills також були створені за допомогою Claude Code, про що ми поговоримо пізніше.

• Compile System App — skill і скрипт для запуску компіляції AL-Go проєктів System Application без контейнера через функцію Build-Apps у build\scripts\DevEnv\NewDevEnv.psm1. Він використовує CompilerFolder (BC artifacts у package cache), тому жоден Docker-контейнер не створюється й не потрібен.
• Run Tests — skill і скрипт для запуску конкретних тестових codeunits проти запущеного BC-контейнера через Run-TestsInBcContainer.

Додатково — BCQuality, спеціалізована база знань для Business Central, яку я використовуватиму для code review.

І, звичайно, нам знадобиться Docker-контейнер з Dynamics 365 Business Central. Для цього ми використаємо скрипти з репозиторію BCApps.

.\build\scripts\DevEnv\NewDevEnv.ps1 -ContainerName bcserver -AlGoProject "build\projects\System Application"

Тепер ми готові перейти безпосередньо до обговорення та реалізації задачі.

Задача

Раніше я реалізував підтримку SharePoint Graph API у Business Central. Це було досить велика задача, яка вимагала від мене багато часу та зусиль. Під час реалізації цього модуля я дещо упустив. А саме:

1. Mock handler у Test Library не підтримував multi-step операції. Деякі методи містять кілька послідовних API-викликів. Наприклад, CopyItemByPath() спочатку має виконати GET-запит, щоб отримати ID вихідного та цільового drive items, і лише потім виконати власне операцію копіювання. На практиці це означає три API-виклики в межах одного методу. Тому потрібно додати підтримку multi-step операцій.
2. Був відсутній метод для перейменування файлів і папок та оновлення їхніх properties після створення.
3. Був відсутній метод для зміни полів наявних list item. Наразі підтримується лише створення, але оновлення metadata — один із найпоширеніших сценаріїв інтеграції з SharePoint.

Тому я вирішив поєднати саму реалізацію з написанням цього посту.

Таким чином я не лише доповнюю модуль SharePoint Graph API, а й ділюсб практичним прикладом використання AI-агента.

Планування

Я рекомендую починати великі задачі зі стадії планування. Звісно, кожен із цих пунктів можна було б опрацювати як окреме задача. Однак я навмисно хочу зімітувати більш велику задачу, щоб показати, як працювати з таким сценарієм.

Отже, спершу переходимо до папки репозиторію BCApps у вашому локальному клоні репозиторію та ініціалізуємо Claude Code:

cd "C:\Users\Drakonian\Documents\AL\BCApps\"
claude

Далі я пишу prompt, у якому описую суть задачі, додаю посилання на документацію, посилання на конкретні місця в коді тощо.

Я хотів би звернути вашу увагу на кілька моментів:

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

Можливо, це не найкращий prompt, але він дає загальне уявлення про принципи та підходи, які можна використовувати при створенні prompts.

Your task is to prepare detailed plan for extending SharePoint Graph implementation in Business Central with new functionality.

SharePoint module have two implementations, REST legacy located at @"src/System Application/App/SharePoint"

Our target is MS Graph API SharePoint implementation located in child folder of module @"src/System Application/App/SharePoint/src/graph/"
this implementation re-use other existing module @"src/System Application/App//MicrosoftGraph"

MS Graph API SharePoint tests located at: @"src/System Application/Test/SharePoint/src/graph"
MS Graph API SharePoint test libraries located at: @"src/System Application/Test Library/SharePoint/src/graph"

Here is list of points to implement, always read references to documentation or objects. Each point must have tests. Follow SharePoint Graph style.

## 1.0 Add method to allow renaming files and folders and updating their properties after creation. Currently, once a file is uploaded, its name and metadata cannot be changed through the module.

Endpoint: PATCH /sites/{id}/drive/items/{id} with updated name or properties
Documentation URL: https://learn.microsoft.com/en-us/graph/api/driveitem-update

## 2.0 Add method to modify existing list item fields. Currently only creation is supported — but updating metadata is one of the most common SharePoint integration scenarios.

Endpoint: PATCH /sites/{site-id}/lists/{list-id}/items/{item-id}/field
Documentation URL: https://learn.microsoft.com/en-us/graph/api/listitem-update

## 3.0 Improve Test Library for Multi-Step Operations.

The current mock handler @"src/System Application/Test Library/SharePoint/src/graph/SharePointGraphTestLibrary.Codeunit.al" supports only a single request-response pair. Operations like CopyItemByPath or MoveItemByPath require consecutive HTTP calls — resolve path, then execute action. The test library needs indexed response lists to properly test these flows. Implement a response queue — enqueue multiple responses in order, handler dequeues on each call, enabling proper testing of consecutive HTTP operations

Example of how it was implemented for MicrosoftGraph module: @"src/System Application/Tes/MicrosoftGraph/src/MockHttpClientHandlerMulti.Codeunit.al"

Але планування на цьому не закінчується. Далі нам потрібно перевірити результат і за потреби внести корективи. Зазвичай я роблю це, переглядаючи згенерований .md файл у VS Code за допомогою розширення Markdown preview.

Але навіть швидкого погляду в терміналі мені вистачило, щоб помітити, що план не містив посилань на конкретні об’єкти з codebase, тож я просто попросив агента додати їх:

А потім я перейшов до повного перегляду плану у VS Code:

І, звичайно, було кілька речей, які потрібно було виправити. Наприклад, Telemetry ID має бути порожнім, оскільки цей ідентифікатор присвоюється Microsoft. Агент не міг цього знати, бо я не надав йому необхідного контексту, оскільки сам не пам’ятав про це під час написання prompt. Загалом таке правило можна винести в CLAUDE.md або AGENTS.md, тому що воно дійсне для будь-якого нового коду в репозиторії BCApps.

Цей процес перегляду та покращення плану може ітеративно повторюватись.

Наприклад, переглядаючи план уважніше ще раз, я помітив, що модель запропонувала створити новий Http Client Handler. Однак у цьому не було потреби, тому що наявний можна було просто переробити. Це не порушило б backward compatibility, і в будь-якому разі це тестовий об’єкт.

Після кількох ітерацій я був задоволений отриманим планом реалізації.

Однак контекст уже виріс приблизно до 200k tokens, тож продовжувати в тій самій сесії більше не мало сенсу. Адже, за моїм досвідом, я помічаю регресію якості приблизно після 200k tokens. Крім того це просто неефективне використання токенів, оскільки ці токени будуть відправлятись при продовженні діалогу в поточній сессії. На цьому етапі ви можете або почати нову сесію, або виконати /compact у поточній.

Реалізація

Для стадії реалізації я зберіг початковий prompt і план реалізації в окремі файли. Це дозволяє мені надати необхідний контекст AI-агенту в новій сесії. Мені потрібно було лише послатися на ці файли за допомогою @ і попросити його почати реалізацію першої фази.

Під час процесу реалізації AI-агент проактивно самостійно викликав Skill для компіляції, хоча я явно не просив його про це.

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

Я підготував обидва ці Skills в окремих сесіях і не тестував їх у реальному використанні. Тож, природно, я натрапив на деякі помилки. Я перервав процес за допомогою Ctrl + C, щоб дослідити причину.

І, звичайно, я також використав Claude Code, щоб виправити проблему зі скриптами Skill.

Головна ідея тут така:

Використовуйте AI-агентів для створення інструментів, які вирішують ваші проблеми. Зосереджуйтесь не лише на розв’язанні самої задачі, а й на створенні інструментів, які допоможуть вам вирішувати подібні задачі в майбутньому. Не вагайтеся використовувати LLM навіть для одноразових інструментів — це справді зручно.

У моєму прикладі проактивні Skills для компіляції та запуску тестів значно покращили якість результату та швидкість агента.

Автоматизоване тестування

Повернімося до реалізації першої фази. Як ви могли помітити, у розмові з агентом ми трохи відійшли від власне задачі й переключилися на виправлення Skills. Усе це займає місце в контексті.

Рішення досить просте: подвійне натискання Esc у Claude Code дозволяє відновити розмову до певної точки. Ви можете повернути лише розмову, лише код або обидва пункта разом. У моєму випадку було зручно відновити розмову, але зберегти весь код, тому що ті виправлення покращили Skills.

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

Code Review

Перш ніж переглядати код самостійно, я використовую agentic code review. Це допомагає знайти та виправити багато проблем ще до того, як я почну вивчати код вручну. Зазвичай я роблю три типи code review.

Перший code review — стандартний і базується на знаннях моделі та загальноприйнятих принципах написання коду. У більшості випадків для цього не потрібно надавати нічого додаткового.

Другий code review базується на спеціалізованій базі знань, пов’язаній із нюансами розробки для Dynamics 365 Business Central. У прикладі я використовую свіжу базу знань BCQuality. Це база знань нова, вона все ще активно розвивається й розташована в репозиторії BCQuality.

Третій — це, звичайно, мануальний code review.

Щоб скористатися цим code review зі спеціалізованими знаннями, я просто використовую простий prompt із посиланням на папку з репозиторієм:

Do additional detailed code review for AL code from finished phase 
using the AL code review skill at C:\Users\Drakonian\Documents\AL\BCQuality\microsoft\skills\review\al-code-review.md

Тут потрібно дуже уважно переглянути кожен пункт, наданий LLM, тому що для будь-якого типу code review можливі false positives.

Лише після цього я переглядаю код самостійно. Це набагато зручніше робити у VS Code за допомогою Git changes, ніж безпосередньо в терміналі.

І дуже часто саме під час ручного code review я знаходжу речі, які були зроблені неправильно або не зовсім правильно.

Наприклад, після реалізації першої фази я попросив агента прибрати TestCopyItemByPath зі списку виключених тестів. Він був вимкнений, тому що вимагав multi-step HTTP handler.

Однак я не помітив, як саме це було зроблено.

Під час ручного code review я одразу побачив, що замість повного видалення файлу SharePointGraphAdvancedTest.json агент вирішив залишити його як порожній масив. Так, звичайно, я не вказав точно, як саме це слід зробити, але також важко пам’ятати кожну дрібну деталь.

Якщо подивитися на папку, де розташовані ці файли disabledTests, одразу стає зрозуміло: якщо немає вимкнених тестів, то файл не потрібен.

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

Ручне тестування

Я твердо переконаний, що автоматизоване тестування не замінює ручне, і навпаки. Вони доповнюють одне одного, і саме це поєднання дає найкращий результат. Тому для мене це обов’язкова частина процесу.

Це особливо важливо, коли ви працюєте з API або використовуєте будь-які mocks. У реальному середовищі цих mocks немає. Реальне середовище може накопичувати різні комбінації станів, які не відтворюються автоматизованим тестуванням, і так далі.

Продовження реалізації

Після цього ми можемо перейти до реалізації наступної фази. Суть процесу абсолютно та сама. Ми починаємо нову сесію, посилаємося на наш початковий prompt і план реалізації та просимо агента почати реалізацію наступної фази.

Документація

Після завершення реалізації, code review та тестування всіх частин задачі ми можемо перейти до документації. Вона може дуже відрізнятися залежно від вимог або методології, що використовується у вашому проєкті. У моєму випадку всі публічні інтерфейси вже містять XML-документацію, тож мені потрібно лише створити описи для Pull Request.

Для цього в новій сесії я посилаюся на план реалізації та початковий prompt і прошу агента переглянути внесені зміни.

Як бачите, агент цілком здатний порівнювати зміни між вашою branch і main.

Звичайно, саму документацію все одно слід переглянути.

LLM часто додають речі, які насправді не потрібні. Наприклад, в одній з ітерацій модель вирішила додати розділ Totals із підрахунком commits, методів, тестів тощо.

Підсумок

Спробуймо підсумувати деякі результати. Спершу пропоную поглянути на діаграму того, як я підходив до розв’язання цьої задачі за допомогою AI-агента.

Як бачите, тут немає нічого складного.

Також пропоную переглянути основні ідеї зі статті. Ось ключові тези:

• Симбіоз понад автоматизацію. Більшість коду тепер генерується LLM, але кожен рядок усе одно переглядається. Максимальне цінність AI-агентів полягає в їх поєднанні з людським судженням, а не в усуненні людини з процессу.
• Термінальний агент і VS Code працюють у тандемі. Claude Code відповідає за генерацію, компіляцію та запуск тестів із термінала. VS Code — це місце, де ви читаєте результат: Markdown Preview для плану, Git diff view для code review, AL Language для LSP та лінтерів. Увесь workflow — це ритм перемикання між ними двома.
• Починайте великі задачі з планування. Попросіть агента створити детальний план у вигляді Markdown-файлу, а потім перегляньте та доопрацюйте його у VS Code, перш ніж писати будь-який код. Ітеруйте, доки план не стане правильним — на цій стадії виправляти набагато дешевше.
• Prompts: короткі, конкретні, з посиланнями через @. Вказуйте на конкретні об’єкти в codebase, додавайте посилання на відповідну документацію, наводьте приклад того, як було вирішено подібну проблему. Не намагайтеся розписати все суцільним текстом.
• Зберігайте prompt і план у файли. Context windows заповнюються (~300k tokens — практична межа). Збереження їх як файлів означає, що нова сесія може посилатися на них через @ і продовжити саме з того місця, де ви зупинилися.
• Використовуйте агента для створення власних інструментів. Skills з автоматичним викликом (компіляція, запуск тестів) кардинально покращують feedback loop. Навіть одноразові допоміжні скрипти варто створювати, коли агент може написати їх за лічені хвилини.
• Esc Esc — це ваша страховка. Відновлює розмову до будь-якої попередньої точки, за бажанням залишаючи код без змін. Дозволяє відволіктися, щоб виправити щось інше, а потім повернутися до власне задачі, не засмічуючи контекст.
• Три рівні code review. Загальний agentic review → review на основі доменної бази знань (наприклад, BCQuality для BC/AL) → людський review Git diff у VS Code. Кожен рівень виловлює те, що пропускають інші, і саме під час ручного review все ще знаходяться неочевідні проблеми.
• Ручне тестування нікуди не зникає. Автоматизовані тести можуть мати моки, а в реальності та ж функціональність може накопичувати комбінації станів, які не завжди відтворюються . Тому це обов’язковий крок, перш ніж вважати фазу завершеною.
• KISS Keep it simple — вам не потрібні тисячі skills чи багатомільйонні промпти, щоб досягти хорошого результату з LLM.

Source Code

У результаті роботи з агентом я створив Pull Request до репозиторію Microsoft, щоб ці зміни могли стати частиною Dynamics 365 Business Central:

github.com/...​icrosoft/BCApps/pull/8318

Я також підготував репозиторій, який містить агентські Skills з прикладів, початковий prompt, план реалізації та опис PR.

github.com/...​/CLI-agents-practical-use