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.