My Architect, частина 4: робочий цикл агента

Це четверта стаття серії про My Architect. У частині 1 я показав цикл агента одним код-блоком і пообіцяв розібрати його докладно. Частини 2 і 3 були про сховище на YAML-файлах і про модель планування. Сьогодні про сам робочий цикл: як агент бере задачу, працює і закриває її так, що проєкт залишається живим джерелом правди, а не журналом постфактум.

Старт сесії: один виклик замість переказу

Раніше кожну нову сесію я починав із переказу: що зроблено, що вирішили, на чому зупинилися. Тепер це один виклик:

get_project_context({ pid })
→ meta + hierarchy + backlog + diagrams + stats

Агент отримує всю ієрархію зі статусами, релізи і статистику за раз замість п'яти окремих запитів.

Залишається питання, звідки агент знає pid. Хардкодити його в skill не можна, skill універсальний. Тому в ньому прописана драбина спроб. Спершу агент шукає в локальному CLAUDE.md проєкту патерн pid: "..." поруч зі згадкою my_architect. Не знайшов — викликає list_projects: якщо проєкт рівно один, він і є; якщо кілька, агент питає людину, а не вгадує. Якщо проєктів нуль, агент пропонує scaffold_project, але не виконує без підтвердження. Створення проєкту — це рішення про скоуп, а не рутина.

Яку задачу брати

get_next_task обирає задачу за трьома правилами, у порядку пріоритету: спершу найраніший реліз, усередині релізу найглибший рівень дерева, при рівності — алфавіт за назвою. Вузли зі статусом done і cancelled виключаються одразу, вузли без релізу йдуть у кінець черги.

Перед сортуванням є ще один фільтр: якщо серед кандидатів є листки, тобто вузли без дітей, вибір іде лише серед них. Це і є leaf-first, і причина в нього практична. Батьківський вузол на кшталт «Auth flow» сам по собі не робиться, він закривається тоді, коли закриті всі його діти. Якщо агент візьме батька напряму, він спробує зробити кілька речей за один захід і розмаже роботу. Листок атомарний: один захід, один коміт, зрозуміле приймання. А батьки закриються самі, каскадом, про який нижче.

Алфавіт на третьому місці дає детермінізм. Той самий беклог завжди повертає ту саму задачу, і поведінку агента можна передбачити і перевірити.

Цикл задачі

Повна послідовність виглядає так:

get_next_task({ pid })            → задача зі шляхом і контекстом батьків
start_task({ pid, nodeId })       → in-progress, assignee: agent
get_node → get_doc                → читаємо доки вузла ДО коду
  ... робота; update_doc по ходу, build_hierarchy
      якщо спливло під-розбиття ...
validate_project({ pid })         → лагодимо dangling-посилання
complete_task({ pid, nodeId, summary })
                                  → done, каскад по предках,
                                    у відповіді вже наступна задача

Найцікавіше тут — complete_task. Перед оновленням він знімає снапшот усього ланцюжка предків, ставить вузлу done, записує summary і порівнює статуси предків до і після. Якщо остання задача фічі закрилася, фіча перейшла в done автоматично, і агент бачить це у відповіді явним списком: який вузол, який статус був, який став. Там само лежить next_task — окремий виклик за наступною задачею не потрібен, цикл замикається сам.

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

Доки оновлюються по ходу, а не після

На вузлах висять markdown-документи, і в них одне призначення: описувати, як фіча працює зараз. Не як планувалась і не як мала б. Тому в skill зашите жорстке правило: взяв задачу — спершу прочитай доки вузла, істина про фічу там, а не в назві. Розуміння змінилося по ходу роботи — update_doc одразу, в тому ж ході.

Вузол чи дока, які брешуть, гірші за їхню відсутність.

Перед закриттям задачі агент зобов'язаний проганяти validate_project. Валідатор повертає список проблем із типом і серйозністю: висячі посилання на доки і діаграми, цикли в ієрархії, загублені батьки. Биті посилання в джерелі правди — це не косметика, тому без чистого прогону complete_task не викликається.

«Доробимо потім» більше не губиться

Будь-який агент по ходу роботи породжує хвости: «це покриємо тестами пізніше», «ретраї поки не підключені», «при зростанні навантаження треба буде кешувати». У чаті ці фрази вмирають разом із сесією. У My Architect правило інше: кожен такий хвіст стає вузлом до кінця поточного ходу.

Куди саме він потрапляє, вирішує рубрика зі skill. Технічний борг щойно закритої фічі агент записує мовчки: той самий епік, той самий реліз, префікс на кшталт tech-debt:. Покращення з явним тригером («коли з'являться платні користувачі», «якщо частка хибних спрацьовувань вища за п'ять відсотків») теж записується без питань, але в майбутній реліз і з тригером прямо в описі, щоб потім було зрозуміло, коли вузол «спрацьовує». А ось стратегічні питання — чи потрібна фіча взагалі, чи не змінити дефолти, чи не притягнути нову залежність — агент зобов'язаний зупинити і віддати людині, показавши варіанти розміщення з trade-offs.

При сумнівах skill велить «лінуватися в бік спитати»: тридцять секунд підтвердження дешевші за вузол, що сплив не в тому релізі за місяць. І перед створенням завжди йде перевірка на дублі за вже завантаженим контекстом, бо дублікат у беклозі ламає пріоритизацію get_next_task: при leaf-first і алфавіті копія може обігнати справжню роботу.

Звірка плану з кодом

План має властивість дрейфувати від кодової бази: щось зробили повз трекер, щось закрили і забули відмітити. Для цього є slash-команда /my-architect:reconcile. Агент проходить усіма draft-вузлами, починаючи з найближчого релізу, і для кожного перевіряє по коду, чи не відвантажено це вже: шукає роути, компоненти, тести, читає їх. Що підтверджено кодом — закривається через bulk_update_nodes з перевіркою відповіді. Що зроблено частково — залишається draft з позначкою, чого саме бракує. Головне правило команди: ніколи не позначати вузол done без доказів у коді. Точність важливіша за кількість закритого.

Друга команда, /my-architect:progress, відповідає на питання «де ми»: відсотки done по релізах і епіках, поточна задача in-progress і що на ній залишилось, наступна задача з черги. Якщо команда бачить draft-вузли, які за всіма ознаками вже відвантажені, вона сама запропонує прогнати reconcile.

Що це дає

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

У п'ятій частині розповім про дистрибуцію через Claude Code marketplace: як влаштований плагін, який ставить skill і MCP-сервер однією командою, і чому skill живе в публічному репозиторії. Спробувати My Architect можна на my-architect.app.