docs(agents): добавлена конфигурация инженерных навыков

2026-09-15 07:07:47 -04:00
1 parent 2e961fd0c7
commit 34a3cb309c
@@ -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`.
@@ -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, явно укажи на
+конфликт, а не отменяй ранее принятое решение молча.
@@ -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 карты ссылку на сохранённый контекст
@@ -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` | Задача не будет выполняться |
+
+Когда навык упоминает роль, используй соответствующую метку из этой таблицы.
+
+Если набор меток репозитория изменится, обнови правый столбец.