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.