NODEDC_TASKMANAGER/AGENTS.md

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

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

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

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

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

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

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

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

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

Формат:

<ТИП> - МЕЖПРОЕКТНАЯ КОММУНИКАЦИЯ: <НАЗВАНИЕ ЭТАПА>

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

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

• UI — если изменения в интерфейсе, текстах, навигации, отображении, UX
• ФУНКЦИИ — если изменения в прикладной логике, API, действиях, синхронизации, обработчиках
• АРХ — если изменения в архитектуре, структуре данных, инфраструктурных правилах, каркасе реализации

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

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

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

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

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

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

Пример:

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

UI - МЕЖПРОЕКТНАЯ КОММУНИКАЦИЯ: переименование модуля во внутренний контур

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

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

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

Примеры

UI - МЕЖПРОЕКТНАЯ КОММУНИКАЦИЯ: переименование модуля во внутренний контур
ФУНКЦИИ - МЕЖПРОЕКТНАЯ КОММУНИКАЦИЯ: создание запроса в целевой проект
ФУНКЦИИ - МЕЖПРОЕКТНАЯ КОММУНИКАЦИЯ: синхронизация статусов источника и цели
АРХ - МЕЖПРОЕКТНАЯ КОММУНИКАЦИЯ: каркас source-target связи
АРХ - МЕЖПРОЕКТНАЯ КОММУНИКАЦИЯ: регламент этапов и именования коммитов

Дополнение

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

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

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

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

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

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

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

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

Подэлементы-чекеры:

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

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

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

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

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

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

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

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