Обробка файлів на основі вбудованих інструкцій
Tell me your sorrows.
— Clifford D. Simak, "Crying Jag"
Вступ
Коли розробник стикається з повторюваними завданнями, він пише код для автоматизації. Проте деякі завдання не так просто запрограмувати, тому зазвичай інструкції щодо цієї роботи описують природною мовою на відповідних ресурсах та виконують вручну. І це може викликати сум.
Тепер з'явилася можливість перекласти ці турботи на те, що прийнято називати штучним інтелектом. Це дійсно потужний інструмент, та, за всієї поваги, зменшмо наші очікування й не сподіваймося, що він усе зробить за нас. Будьмо реалістами, а можливо, й трохи песимістами. Наразі ШІ — це лише досить якісний автоматичний форматувальник ваших думок із потужною функцією покращення на основі популярної в інтернеті інформації. Він чудово збагатить ваш текст загальновідомими фактами, пояснюючи те, що ви зробили, наведе різноманітні приклади, додасть посилання та розтлумачить логіку написаного коду. Це саме та рутина, на яку завжди бракує часу, коли намагаєшся створити щось нове, а витрачати сили на речі, які всім і так відомі, немає змоги. Але те, що є дійсно новим і про що модель ще не знає, вам доведеться описати самостійно, інакше нічого не вийде.
У цьому процесі можна вбачати такий самий програмний транслятор, як і багато інших. Тільки в цьому разі транслюється людська мова. І це, звісно, круто, якщо результат відповідає очікуванням.
Обробка файлів на основі вбудованих інструкцій — це як робити нотатки на полях сторінок із вказівками щодо їхнього вмісту, які згодом потрібно реалізувати. Це можна зробити власноруч або за допомогою ШІ, залишаючи за собою лише перевірку результату. Такий підхід нагадує роботу «гострайтера» (літературного помічника): він досить вправний і ерудований, але є лише асистентом, а не автором.
Вбудовані інструкції
На відміну від інтерактивних інструментів (чатів), тут йдеться суто про виконання конкретних завдань з обробки файлів, описаних природною мовою. Це може бути що завгодно: написання документації в коді, створення контенту сторінок для вебсайту проєкту чи покриття коду модульними тестами.
У такій парадигмі ваші інструкції, написані простою мовою, стають «вихідним кодом», який система інтерпретує та виконує. Це дозволяє автоматизувати та оптимізувати роботу з файлами з широкими можливостями коригування дій.
Оскільки ми використовуємо такі інструкції як код, важливо ставитися до них із такою самою обережністю, як і до традиційного вихідного коду. Інструкції слід зберігати у проєкті в структурованому й зручному для супроводу вигляді, забезпечуючи їхнє версіонування, тестування та легкий доступ для майбутніх оновлень чи спільної роботи. Такий підхід допомагає підтримувати узгодженість, відстежуваність та якість у ваших робочих процесах.
Ці інструкції розміщуються в коментарях і безпосередньо не впливають на поведінку програми під час виконання. Виконання інструкцій відбуваєт��ся за потреби, наприклад після зміни коду. І для цього планується використовувати ШІ. За бажанням ви можете пропустити етап обробки штучним інтелектом та використовувати збережені інструкції як орієнтири для ручної роботи. Однак процес стає значно ефективнішим, якщо використовувати спеціалізовані інструменти й зосередитися на тестуванні результатів їхньої роботи.
Ці інструкції позначаються тегом @guidance і розміщуються в блоках коментарів, щоб усунути їхній вплив на вихідний код чи дані, тому їх можна використовувати тільки в тих файлах, які підтримують коментарі. Наприклад, текстові файли на кшталт *.txt не можуть містити таких тегів. Винятком є файл @guidance.txt, який повністю обробляється як тег @guidance для теки, в якій він розташований. Наявність тегів @guidance жодним чином не впливає на проєкт, не тягне за собою жодних залежностей, і їх можна додати до будь-якого проєкту.
Нижче наведено приклади використання тегу для різних типів файлів.
Markdown, HTML та XML файли
Приклад:
Файл: README.md
<!-- @guidance:
**Important:** If any section or content already exists, update it with the latest and most accurate information instead of duplicating or skipping it.
1. **Project Title and Overview:**
- Provide the project name and a brief description based on `src/site/markdown/index.md` content summary.
- Add `` before the title.
- Add `[](https://central.sonatype.com/artifact/org.machanism.machai/machai)` after the title as a new paragraph.
...
-->
Java та TypeScript файли
Для вихідних файлів Java та TypeScript використовуйте анотацію @guidance у багаторядному блоці коментарів (але не всередині коментарів Javadoc або TSDoc).
Приклад для Java:
Файл: AIFileProcessor.java
/*@guidance:
* Create or update javadoc of AIFileProcessor class.
* Class javadoc description should describe supported functionality and provide examples to use it.
* If the method used as Javadoc documentation is not public or protected, the method name should not be specified.
*/
Приклад для TypeScript:
/*
* @guidance:
* - Document all exported classes, interfaces, functions, and constants using TSDoc.
* - Provide clear descriptions, parameter details, and usage examples.
* - Keep documentation up to date with code changes.
* - Do not use `@guidance` within TSDoc comments.
*/
Python файли
Для файлів Python використовуйте багаторядковий коментар (трикратні лапки) на початку файлу або у відповідному розділі:
'''
@guidance:
- Follow PEP 257 for docstrings.
- Document all public classes, methods, and functions.
- Keep comments up to date and clear.
'''
Інструкції на рівні теки (Folder Level Guidance)
Файл: @guidance.txt
У кореневому каталозі проєкту переконайтеся, що наступні файли присутні та правильно створені:
**LICENSE.txt**
- Include the full text of the project's license.
- If the license file is missing, create it using the license type defined in the pom.xml file.
- Ensure the license terms are accurate and up to date.
- Use `Copyright 2026 Machanism.org`
Інструкції для пакетів Java (Java Package Guidance)
Для пакетів Java тег @guidance можна використовувати на рівні пакета у файлі package-info.java.
Приклад:
Файл: package-info.java
package org.machanism.machai.bindex;
/*-
* @guidance:
* **IMPORTANT: ADD JAVADOC TO ALL CLASSES IN THE PACKAGE AND THIS `package-info.java`!**
* - Use Clear and Concise Descriptions:
* - Write meaningful summaries that explain the purpose, behavior, and usage of each element.
* - Avoid vague statements; be specific about functionality and intent.
* - Update `package-info.java`:
* - Analyze the source code within this package.
* - Generate comprehensive package-level Javadoc that clearly describes the package’s overall purpose and usage.
* - Do not include a "Guidance and Best Practices" section in the `package-info.java` file.
* - Ensure the package-level Javadoc is placed immediately before the `package` declaration.
* - Include Usage Examples Where Helpful:
* - Provide code snippets or examples in Javadoc comments for complex classes or methods.
* - Maintain Consistency and Formatting:
* - Follow a consistent style and structure for all Javadoc comments.
* - Use proper Markdown or HTML formatting for readability.
* - Add Javadoc:
* - Review the Java class source code and include comprehensive Javadoc comments for all classes,
* methods, and fields, adhering to established best practices.
* - Ensure that each Javadoc comment provides clear explanations of the purpose, parameters, return values,
* and any exceptions thrown.
* - Escape `<` and `>` as `<` and `>` in `<pre>` content for Javadoc.
*/
Які файли обробляються
Для роботи застосунку потрібно вказати теку проєкту та шлях сканування. Тека проєкту має вказувати на розташування проєкту (або кількох проєктів), що потребують обробки. Шлях сканування визначає, які саме файли в проєкті потрібно проаналізувати на наявність тегів @guidance для подальшого виконання дій над ними.
Шлях сканування задається як відносний або абсолютний шлях до файлу чи теки; також можна використовувати регулярні вирази (regex) або glob-шаблони.
Тека сканування визначає конкретну теку, з якої починається сканування та аналіз файлів. Цей параметр дає змогу зосередити обробку лише на певній частині вашого проєкту, забезпечуючи гнучкість та контроль над тим, які файли й підкаталоги залучено до процесу.
Пошук файлів, що потребують обробки, виконується застосунком без використання ШІ.
До обробки беруться тільки ті файли, які містять теги @guidance. Для кожного з них створюється окремий сеанс обробки з власним контекстом, тому контекстне вікно формується лише для поточного файлу, який опрацьовується. Відповідальність за визначення файлів для обробки покладено на застосунок, і ШІ зазвичай до цього не залучається.
Застосунок також розпізнає структуру проєкту й застосовує обробку файлів з урахуванням того, до якого модуля вони належать. Завдяки цьому можна сканувати розгалужені проєкти з великою кількістю модулів.
Послідовність обробки файлів
Усі проєктні файли, які відповідають шляху сканування, сортуються залежно від глибини їхнього розташування (довжини шляху). Сканування розпочинається з файлів, які мають найбільшу кількість вкладених тек.
Послідовність обробки файлів слід враховувати, якщо файли, розташовані ближче до кореня проєкту, використовують інформацію з файлів, що містяться глибше у структурі.
Якщо проєкт має дочірні модулі, вони обробляються перед файлами основного проєкту: послідовно (в порядку їхнього оголошення в проєкті) або паралельно (якщо ввімкнено багатопотоковість).
Окрім того, можливий запуск застосунку під керуванням сторонніх систем збирання, наприклад Maven у режимі per-module. У цьому разі послідовність обробки модулів визначатиметься залежностями в проєкті.
Після обробки всіх модулів застосунок переходить до опрацювання проєктних файлів.
Використання сервісів GenAI
Модель, що використовується для обробки файлів на основі вбудованих інструкцій, вказується окремо, і її вибір визначає, наскільки якісним та коштовним буде цей процес.
Інструменти (Tools)
Щоб наш «гострайтер» міг виконувати дії над файлами, використовується набір вбудованих функціональних інструментів. Саме завдяки їм GenAI взаємодіє з файловою системою, збирає проєкт, запускає тести та навіть виходить в інтернет. Для потреб обробки файлів використовуються:
- Інспектування проєкту та файлів (навігація структурою та пошук).
- Модифікація файлів (запис, редагування та автозаміна).
- Виконання команд та робота з логами (складання проєкту, запуск тестів та аналіз результатів).
- Контекст проєкту та метадані (розуміння структури та зв'язків між модулями).
Важливе зауваження щодо безпеки: Інструменти, які змінюють файли, виконують системні команди або роблять зовнішні мережеві запити, використовуються виключно тоді, коли цього безпосередньо вимагає ваше завдання. Усі ці дії суворо контролюються вашими налаштуваннями.
Ви також маєте можливість створити та додати будь-які власні інструменти для ефективного вирішення специфічних завдань або обмежити їхнє використання, вказавши лише дозволені.
Приклади використання
Теги @guidance чудово задовольняють потреби в автоматичній синхронізації пов’язаних даних — чи то документації в коді (In-Code), чи то проєктної документації, чи написання модульних тестів.
Прикладом використання Machai Ghostwriter насамперед є проєкт Machai від Machanism. Тут теги @guidance використовуються в багатьох файлах для автоматичної генерації та актуалізації документації коду та конфігурацій. Machai — це проєкт із відкритим вихідним кодом, при розробці якого увага фокусується на імплементації коду, що забезпечує потрібний функціонал.
Написання документації є вторинним процесом, але водночас украй важливим, оскільки вона необхідна сторонньому користувачеві для роботи з проєктом. Проте тут йдеться не лише про користувача-людину. У межах цього проєкту також створюються спеціалізовані описи бібліотек (bindex) для формування контексту під час використання ШІ для автоматичної генерації коду. У цьому разі автоматична інтелектуальна генерація In-Code документації стає відповідальним кроком, у якому теги @guidance визначають інформацію, яка буде використана для генерації коду.
Machai Ghostwriter
Розглянемо застосунок, який підтримує вищевикладені принципи — Machai Ghostwriter. Це легкий Java-застосунок, для роботи якого потрібна встановлена JVM Java 8, проте для оптимальної роботи наполегливо рекомендовано використовувати Java 17 або новішу версію.
Machai Ghostwriter розрахований на використання в CI/CD-пайплайнах, але його також можна запускати як CLI-інструмент.
У проєкті Machai є також Maven-плагін для запуску Ghostwriter, що робить його надзвичайно зручним для Maven-проєктів.
Дистрибутив JAR-файлу з усіма необхідними бібліотеками можна завантажити за адресою: SourceForge - Machai Ghostwriter або задіяти як Maven-плагін Ghostwriter у вигляді залежності: org.machanism.machai:gw-maven-plugin. Також можна клонувати проєкт Machai, якщо ви плануєте долучитися до його вдосконалення.
Запуск
Щоб запустити обробку файлів, досить вказати лише шлях до проєкту та шлях сканування — жодних інших параметрів не потрібно. Усі директиви, які необхідно виконати, вже містяться у файлах.
Запуск через CLI:
java -jar gw.jar
або через Maven:
mvn gw:gw
Якщо виникає необхідність звузити перелік оброблюваних файлів, слід додати шлях сканування:
java -Dgw.model=CodeMie:gpt-5.6-terra-2026-07-09 -jar gw.jar "glob:**/*.md"
або:
mvn gw:gw -Dgw.path=glob:**/*.md -Dgw.model=CodeMie:gpt-5.6-terra-2026-07-09
(або ж відповідна конфігурація задається безпосередньо в плагіні).
Конкретний провайдер ШІ та модель задаються через параметр gw.model, який застосовується до всіх файлів. Якщо необхідно використовувати різні моделі для різних шляхів, слід запускати обробку для кожного з них окремо.