154 lines
11 KiB
Markdown
154 lines
11 KiB
Markdown
# Правила работы агента
|
||
|
||
## Общий принцип
|
||
|
||
Работа ведется этапами.
|
||
|
||
После завершения каждого смыслового этапа агент:
|
||
- кратко фиксирует, что сделано
|
||
- предлагает пользователю название коммита
|
||
- ждет явного подтверждения на коммит
|
||
- только после подтверждения выполняет `git commit`
|
||
|
||
Коммиты не должны идти бессистемным потоком.
|
||
|
||
Каждый коммит должен визуально читаться по заголовку и сразу показывать:
|
||
- какой это слой изменений
|
||
- к какому направлению относится этап
|
||
- что именно сделано на этом этапе
|
||
|
||
## Формат названия коммита
|
||
|
||
Формат:
|
||
|
||
```text
|
||
<ТИП> - <КОНТЕКСТ РАБОТ>: <НАЗВАНИЕ ЭТАПА>
|
||
```
|
||
|
||
`КОНТЕКСТ РАБОТ` выбирается по фактическому направлению этапа: `NAS DEPLOY`, `AUTH`, `LAUNCHER`,
|
||
`TASKER`, `BACKEND`, `FRONTEND`, `DESIGN SYSTEM`, `DATA MIGRATION`, `INFRA` и т.п.
|
||
|
||
## Типы коммитов
|
||
|
||
Использовать верхний уровень по смыслу изменений:
|
||
|
||
- `UI` — если изменения в интерфейсе, текстах, навигации, отображении, UX
|
||
- `FEAT` — если изменения в прикладной логике, API, действиях, синхронизации, обработчиках
|
||
- `FIX` — если исправляется конкретный дефект или regression
|
||
- `ARCH` — если изменения в архитектуре, структуре данных, инфраструктурных правилах, каркасе реализации
|
||
- `CHORE` — если изменения обслуживающие: сборка, конфиги, скрипты, зависимости, регламенты
|
||
- `DOCS` — если меняется только документация
|
||
|
||
Если этап затрагивает несколько слоев, выбирать доминирующий.
|
||
|
||
## Правило предложения коммита
|
||
|
||
После каждого завершенного этапа агент должен предлагать пользователю готовое название коммита.
|
||
|
||
Перед предложением названия коммита агент должен отдельным коротким блоком указывать следующую задачу.
|
||
|
||
Порядок вывода в конце этапа:
|
||
- что сделано
|
||
- следующая задача
|
||
- предлагаемое название коммита
|
||
|
||
Пример:
|
||
|
||
```text
|
||
Следующая задача:
|
||
добрать source-side индикатор изменений в списке внешних контуров
|
||
|
||
UI - TASKER: переименование модуля во внутренний контур
|
||
```
|
||
|
||
Пользователь отвечает подтверждением в духе:
|
||
- `коммитить`
|
||
- `да, коммить`
|
||
- `ок, коммит`
|
||
|
||
Только после этого агент делает коммит.
|
||
|
||
## Примеры
|
||
|
||
```text
|
||
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 смотреть результат
|
||
- не считать этап завершенным, пока пользователь не сможет открыть измененную страницу в браузере, если этому не мешают внешние технические ограничения
|