From 34a3cb309c50ab32389fcfca0fb05345ec5a8aea Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Tue, 15 Sep 2026 07:07:47 -0400 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=D0=B0=20=D0=BA=D0=BE=D0=BD=D1=84=D0=B8=D0=B3?= =?UTF-8?q?=D1=83=D1=80=D0=B0=D1=86=D0=B8=D1=8F=20=D0=B8=D0=BD=D0=B6=D0=B5?= =?UTF-8?q?=D0=BD=D0=B5=D1=80=D0=BD=D1=8B=D1=85=20=D0=BD=D0=B0=D0=B2=D1=8B?= =?UTF-8?q?=D0=BA=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 14 ++++++++ docs/agents/domain.md | 45 ++++++++++++++++++++++++++ docs/agents/issue-tracker.md | 63 ++++++++++++++++++++++++++++++++++++ docs/agents/triage-labels.md | 16 +++++++++ 4 files changed, 138 insertions(+) create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md create mode 100644 docs/agents/triage-labels.md diff --git a/AGENTS.md b/AGENTS.md index 15d9706..6a9c3d7 100755 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,3 +60,17 @@ - Уважай существующие изменения пользователя и не откатывай их без запроса. - Предпочитай минимальные изменения, которые делают курс проще и устойчивее для новичка. - Если непонятно, какой маршрут сейчас актуален, доверяй `START_HERE.md` и `docs/course_program.md`, а не старым HOWTO или планам. + +## Agent skills + +### Трекер задач + +Задачи ведутся в Gitea Issues этого репозитория через `tea`. Подробнее: `docs/agents/issue-tracker.md`. + +### Метки триажа + +В репозитории используются пять стандартных меток триажа. Подробнее: `docs/agents/triage-labels.md`. + +### Документация предметной области + +Документация предметной области устроена по схеме `single-context`. Подробнее: `docs/agents/domain.md`. diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..054d2eb --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,45 @@ +# Документация предметной области + +Правила работы инженерных навыков с документацией предметной области при +изучении кодовой базы. + +## Что прочитать перед изучением кодовой базы + +- **`CONTEXT.md`** в корне репозитория +- **`CONTEXT-MAP.md`** в корне репозитория, если он существует: файл указывает + на отдельные `CONTEXT.md` для разных контекстов +- **`docs/adr/`**: ADR, относящиеся к области предстоящих изменений + +Если какого-либо файла или каталога нет, продолжай работу без предупреждения. +Не отмечай его отсутствие и не предлагай создать его заранее. Навык +`/domain-modeling` создаёт такие документы по мере необходимости, когда +появляются новые термины или архитектурные решения. + +## Структура файлов + +Этот репозиторий использует схему `single-context`: + +```text +/ +├── CONTEXT.md +├── docs/adr/ +│ ├── 0001-example-decision.md +│ └── 0002-another-decision.md +└── src/ +``` + +## Используй термины из глоссария + +Когда в результате работы появляется понятие предметной области — например, в +названии задачи, предложении по рефакторингу, гипотезе или названии теста, — +используй термин из `CONTEXT.md`. Не заменяй его синонимами, которые глоссарий +явно исключает. + +Если нужного понятия в глоссарии нет, проверь, действительно ли оно относится +к проекту. Если относится, зафиксируй пробел для последующей проработки через +`/domain-modeling`. + +## Отмечай противоречия с ADR + +Если предлагаемое изменение противоречит существующему ADR, явно укажи на +конфликт, а не отменяй ранее принятое решение молча. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..337568d --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,63 @@ +# Трекер задач: Gitea + +Задачи и спецификации этого репозитория хранятся в Gitea Issues: +`git.dementev.space/ddmitry/mini-lakehouse-lab`. Для работы с ними используй +CLI `tea`. + +## Основные команды + +- **Создать задачу**: + `tea issues create --title "..." --description "..."` +- **Прочитать задачу вместе с комментариями**: + `tea issues <номер> --comments --output yaml` +- **Получить список задач**: + `tea issues list --state open --output json`; при необходимости добавь + фильтры, например `--labels` +- **Добавить комментарий**: + `tea comments add <номер> --description "..."` +- **Добавить или удалить метки**: + `tea issues edit <номер> --add-labels "..."` или + `tea issues edit <номер> --remove-labels "..."` +- **Назначить исполнителя**: + `tea issues edit <номер> --add-assignees "<имя пользователя>"` +- **Закрыть задачу**: сначала опубликуй итоговый комментарий через + `tea comments add`, затем выполни `tea issues close <номер>` + +Запускай команды из каталога репозитория: `tea` определит Gitea-подключение и +репозиторий по Git remote. + +## Pull request как источник задач для триажа + +**Обрабатывать pull request как входящие задачи: нет.** + +Измени значение на `да`, если в будущем репозиторий начнёт рассматривать +внешние pull request как запросы на изменение. Навык `/triage` читает эту +настройку. + +## Когда навык просит опубликовать задачу в трекере + +Создай Gitea Issue с помощью `tea issues create`. + +## Когда навык просит получить связанную задачу + +Выполни `tea issues <номер> --comments --output yaml`. + +## Операции Wayfinder + +Навык `/wayfinder` использует одну задачу-карту и связанные с ней дочерние +задачи. + +- **Карта**: задача с меткой `wayfinder:map`, содержащая разделы Notes, + Decisions-so-far и Fog +- **Дочерняя задача**: задача, описание которой начинается со строки + `Part of #<номер карты>` и содержит метку типа `wayfinder:<тип>`: + `research`, `prototype`, `grilling` или `task` +- **Блокировка**: строка `Blocked by: #<номер>, #<номер>` в начале описания; + задача разблокирована, когда закрыты все перечисленные задачи +- **Фронтир**: найди открытые дочерние задачи карты, исключи назначенные и + заблокированные, затем выбери первую по порядку в карте +- **Взять в работу**: назначь исполнителя командой + `tea issues edit <номер> --add-assignees "<имя пользователя>"`; это первая + запись в трекер в рамках сессии +- **Завершить**: опубликуй ответ в комментарии, закрой дочернюю задачу и добавь + в раздел Decisions-so-far карты ссылку на сохранённый контекст diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..75ba4e5 --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,16 @@ +# Метки триажа + +Навыки используют пять стандартных ролей триажа. Таблица связывает эти роли с +метками трекера данного репозитория. + +| Роль в mattpocock/skills | Метка в нашем трекере | Значение | +| ------------------------ | --------------------- | -------- | +| `needs-triage` | `needs-triage` | Сопровождающий должен оценить задачу | +| `needs-info` | `needs-info` | Для продолжения нужен ответ автора | +| `ready-for-agent` | `ready-for-agent` | Задача полностью описана и готова для автономного агента | +| `ready-for-human` | `ready-for-human` | Задачу должен выполнить человек | +| `wontfix` | `wontfix` | Задача не будет выполняться | + +Когда навык упоминает роль, используй соответствующую метку из этой таблицы. + +Если набор меток репозитория изменится, обнови правый столбец.