NODEDC_TASKMANAGER/AGENTS.md

Правила работы агента

Общий принцип

Работа ведется этапами.

После завершения каждого смыслового этапа агент:

• кратко фиксирует, что сделано
• предлагает пользователю название коммита
• ждет явного подтверждения на коммит
• только после подтверждения выполняет git commit

Коммиты не должны идти бессистемным потоком.

Каждый коммит должен визуально читаться по заголовку и сразу показывать:

• какой это слой изменений
• к какому направлению относится этап
• что именно сделано на этом этапе

Формат названия коммита

Формат:

<ТИП> - <КОНТЕКСТ РАБОТ>: <НАЗВАНИЕ ЭТАПА>

КОНТЕКСТ РАБОТ выбирается по фактическому направлению этапа: NAS DEPLOY, AUTH, LAUNCHER, TASKER, BACKEND, FRONTEND, DESIGN SYSTEM, DATA MIGRATION, INFRA и т.п.

Типы коммитов

Использовать верхний уровень по смыслу изменений:

• UI — если изменения в интерфейсе, текстах, навигации, отображении, UX
• FEAT — если изменения в прикладной логике, API, действиях, синхронизации, обработчиках
• FIX — если исправляется конкретный дефект или regression
• ARCH — если изменения в архитектуре, структуре данных, инфраструктурных правилах, каркасе реализации
• CHORE — если изменения обслуживающие: сборка, конфиги, скрипты, зависимости, регламенты
• DOCS — если меняется только документация

Если этап затрагивает несколько слоев, выбирать доминирующий.

Правило предложения коммита

После каждого завершенного этапа агент должен предлагать пользователю готовое название коммита.

Перед предложением названия коммита агент должен отдельным коротким блоком указывать следующую задачу.

Порядок вывода в конце этапа:

• что сделано
• следующая задача
• предлагаемое название коммита

Пример:

Следующая задача:
добрать source-side индикатор изменений в списке внешних контуров

UI - TASKER: переименование модуля во внутренний контур

Пользователь отвечает подтверждением в духе:

• коммитить
• да, коммить
• ок, коммит

Только после этого агент делает коммит.

Примеры

UI - TASKER: переименование модуля во внутренний контур
FEAT - TASKER ROUTING: создание запроса в целевой проект
FEAT - TASKER ROUTING: синхронизация статусов источника и цели
ARCH - DATA MODEL: каркас source-target связи
CHORE - AGENT RULES: регламент этапов и именования коммитов

Дополнение

Если пользователем не сказано иное:

• не делать amend
• не переписывать историю
• не объединять несколько отдельных этапов в один коммит постфактум

Ведение карточек задач Codex

Карточка задачи должна разделять постановку, план этапов и фактическую реализацию.

Каноническая структура карточки:

• заголовок карточки
• основное описание карточки
• при необходимости текстовый блок Текущая архитектура
• для каждого этапа: текстовый блок этапа, затем чекер этапа
• после реализации этапа: текстовый блок Реализация этапа N

Заголовок карточки:

• передает основную суть задачи
• должен быть коротким, читаемым в списке и без служебного шума

Основное тело карточки:

• хранит концептуальное описание задачи, цель, контекст, ограничения и критерии приемки
• описывает, зачем делается изменение и как система должна работать на среднем уровне детализации
• не превращается в журнал работ и не дублирует чекеры
• остается читаемым входом в задачу после нескольких итераций

Текстовый блок Текущая архитектура:

• создается через Добавить подэлемент, если задача опирается на уже существующее поведение
• фиксирует, что уже реализовано, что частично реализовано, а чего в системе еще нет
• отделяет существующий baseline от будущего плана, чтобы не планировать повторную реализацию уже готовых частей
• не должен содержать рабочие чекеры или журнал выполнения

Текстовый блок этапа:

• создается через Добавить подэлемент перед чекером соответствующего этапа
• заголовок должен называться как этап, например Этап 1. Backend enforcement лимитов
• тело блока описывает цель этапа, текущий статус, границы scope, зависимости и важные ограничения
• если этап пока только планируется, в теле явно указывается Статус: не реализовано, Статус: частично реализовано или Статус: backlog
• длинные архитектурные пояснения живут здесь, а не внутри пунктов чекера

Чекер этапа:

• создается через Добавить подэлемент сразу после текстового блока этапа
• заголовок чекера должен называться Чекер этапа N. <название этапа>
• пункты внутри чекера должны быть короткими проверяемыми действиями по этапу
• пункт закрывается только после реализации и проверки, а не по намерению
• чекеры используются как рабочий план, а не как место для длинных объяснений

Текстовые блоки фактической реализации:

• создаются через Добавить подэлемент под соответствующим чекером этапа только после фактической реализации
• заголовок текстового блока должен явно связывать его с этапом, например Реализация этапа 1
• блок фиксирует, что реально сделано, какие файлы/модули затронуты, какие проверки прошли и какие ограничения остались
• важные нюансы для дальнейшего масштабирования записываются именно сюда, а не теряются в чате
• после каждого осмысленного этапа соответствующий текстовый блок обновляется

Декомпозиция задач:

• одна продуктовая или архитектурная тема должна жить в одной карточке, если этапы не имеют самостоятельного независимого scope
• не создавать пачку top-level карточек для этапов одной большой задачи; этапы ведутся текстовыми блоками и чекерами внутри основной карточки
• отдельная top-level карточка допустима только когда задача имеет отдельный результат, владельца, проверку и может выполняться независимо от родительского контекста
• если несколько старых карточек описывают один контекст, их нужно объединить в одну актуальную карточку и удалить или закрыть дубли

Статус карточки:

• В работе ставится только когда задача реально взята в исполнение
• Готово ставится после проверки результата и закрытия рабочих чекеров
• Отложено используется для задач, которые больше не входят в текущий рабочий план
• backlog не должен хранить уже сделанные или сознательно отложенные задачи как активные

Публикация фронта

После каждой правки интерфейса агент должен:

• залить изменения на локально доступный frontend
• сообщить пользователю, по какому URL смотреть результат
• не считать этап завершенным, пока пользователь не сможет открыть измененную страницу в браузере, если этому не мешают внешние технические ограничения