docs(agents): настройка трекера, меток триажа и доменных доков для скиллов

- AGENTS.md: блок «Agent skills» со ссылками на docs/agents/ - docs/agents/issue-tracker.md: Gitea через tea CLI - docs/agents/triage-labels.md: стандартные пять меток - docs/agents/domain.md: один контекст, CONTEXT.md + docs/adr/ - CLAUDE.md: секция «Читабельность языка» Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-20 11:59:47 -04:00
1 parent 98030f8b0d
commit 77d72b08c6
@@ -77,3 +77,17 @@
 - Избегайте больших рефакторингов и сложных паттернов — студенты только начинают.
 - Ошибки и логи — дружелюбные и понятные (лучше с подсказкой «что сделать дальше»).
 - Перед релевантными правками валидируйте локально: `make up`, затем откройте DAG в UI и/или прогоните `make test`.
+
+## Agent skills
+
+### Issue tracker
+
+Issues живут в Gitea (`git.dementev.space/ddmitry/airflow-greenplum`), работа через `tea` CLI. См. `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Стандартный набор: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. См. `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Один контекст: `CONTEXT.md` и `docs/adr/` в корне репо. См. `docs/agents/domain.md`.
@@ -1 +1,7 @@
@AGENTS.md
+
+# Читабельность языка
+
+Пиши легко для чтения. Сокращай количество мыслей, а не количество слов, которыми выражена каждая мысль.
+
+Please remove all mannered prose.
@@ -0,0 +1,51 @@
+# Доменная документация
+
+Как скиллам читать доменную документацию этого репо перед работой с кодом.
+
+## Что читать перед началом
+
+- **`CONTEXT.md`** в корне репо, или
+- **`CONTEXT-MAP.md`** в корне, если он есть: указывает на отдельный `CONTEXT.md` для каждого контекста. Читайте те, что относятся к теме.
+- **`docs/adr/`**: читайте ADR, которые касаются области, с которой собираетесь работать. В мультиконтекстных репо также проверяйте `src/<context>/docs/adr/`.
+
+Если каких-то из этих файлов нет — **работайте молча**. Не отмечайте их отсутствие и не предлагайте создать заранее. Скилл `/domain-modeling` (через `/grill-with-docs` и `/improve-codebase-architecture`) создаёт их по мере того, как термины и решения реально фиксируются.
+
+## Структура файлов
+
+Один контекст (этот репо и большинство других):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Несколько контекстов (признак — `CONTEXT-MAP.md` в корне):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← решения уровня системы
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← решения этого контекста
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Используйте словарь глоссария
+
+Когда в выводе называете доменное понятие (в заголовке issue, предложении по рефакторингу, гипотезе, имени теста), берите термин из `CONTEXT.md`. Не съезжайте на синонимы, которых глоссарий избегает.
+
+Если нужного понятия в глоссарии нет — это сигнал: либо вы придумываете слова, которых проект не использует (пересмотрите), либо в глоссарии пробел (отметьте для `/domain-modeling`).
+
+## Отмечайте конфликты с ADR
+
+Если ваш вывод противоречит существующему ADR, скажите об этом явно, а не переопределяйте молча:
+
+> _Противоречит ADR-0007 (event-sourced orders), но стоит пересмотреть, потому что…_
@@ -0,0 +1,51 @@
+# Трекер задач: Gitea
+
+Issues и спеки этого репо живут в Gitea:
+`https://git.dementev.space/ddmitry/airflow-greenplum`.
+Все операции — через CLI [`tea`](https://gitea.com/gitea/tea).
+`gh` и `glab` с этим хостом не работают.
+
+`tea` сам определяет репо и логин по `git remote -v`, если запущен внутри клона
+(логин `dementev`, пользователь `ddmitry`). Для машиночитаемого вывода
+добавляйте `-o json` к любой команде `list`.
+
+## Команды
+
+- **Создать issue**: `tea issues create --title "..." --description "..."`. Для многострочного описания используйте heredoc или `"$(cat file.md)"`. `--labels a,b` вешает метки сразу при создании.
+- **Прочитать issue**: `tea issues <номер> --comments`.
+- **Список issues**: `tea issues list --state open -o json --fields index,title,state,labels,assignees,body`. Фильтры: `--labels`, `--state all|open|closed`, `--keyword`, `--assignee`.
+- **Прокомментировать**: `tea comments add <номер> "..."` (короткая форма: `tea comment <номер> "..."`).
+- **Добавить / снять метки**: `tea issues edit <номер> --add-labels "a,b"` / `--remove-labels "a,b"`. Метка должна существовать в репо: `tea labels create --name "..." --color "..." --description "..."`.
+- **Закрыть**: `tea issues close <номер>`. Комментарий при закрытии команда не принимает — сначала `tea comments add`, потом `close`.
+- **Pull requests**: `tea pulls create`, `tea pulls <номер>`, `tea pulls list`, `tea pulls merge` — тот же набор, что у `tea issues`. Комментарии к PR — через тот же `tea comments add <номер>`.
+
+## PR как источник запросов
+
+**PR как источник запросов: нет.** _(Поставьте `да`, если внешние PR нужно рассматривать как feature request; `/triage` читает этот флаг.)_
+
+Если стоит `да`, PR проходят те же метки и состояния, что и issues, через `tea pulls`:
+
+- **Прочитать PR**: `tea pulls <номер> --comments`; diff — `tea pulls checkout <номер>` и `git diff main...`.
+- **Список внешних PR для триажа**: `tea pulls list --state open -o json --fields index,title,author,labels,body`, дальше оставить только PR от авторов, которые не являются участниками репо.
+- **Комментарий / метки / закрытие**: `tea comments add`, `tea issues edit --add-labels`/`--remove-labels` (работает и для номеров PR), `tea pulls close`.
+
+В Gitea issues и PR нумеруются в одном пространстве: `#42` может быть и тем, и другим. `tea issues 42` показывает поле `kind`; ещё можно смотреть `tea issues list --kind all`.
+
+## Когда скилл говорит «опубликовать в трекер»
+
+Создать issue в Gitea: `tea issues create`.
+
+## Когда скилл говорит «взять тикет»
+
+Выполнить `tea issues <номер> --comments`.
+
+## Операции wayfinding
+
+Используется `/wayfinder`. **Карта** — одна issue, **дочерние** issues — тикеты.
+
+- **Карта**: одна issue с меткой `wayfinder:map`, в теле — Notes / Decisions-so-far / Fog. `tea issues create --labels wayfinder:map`.
+- **Дочерний тикет**: issue со строкой `Part of #<карта>` в начале описания и меткой `wayfinder:<тип>` (`research`/`prototype`/`grilling`/`task`). После взятия в работу тикет назначается на исполнителя.
+- **Блокировки**: в Gitea есть встроенные зависимости между issues, но `tea` их не поддерживает. Используйте строку `Blocked by: #<n>, #<n>` в начале описания дочернего тикета. Тикет разблокирован, когда все блокирующие закрыты.
+- **Поиск фронтира**: `tea issues list --state open --labels wayfinder:task -o json` (повторить для каждого типа), оставить только детей этой карты, отбросить те, у кого есть открытый блокер в `Blocked by` или назначенный исполнитель; первый по порядку в карте.
+- **Взять в работу**: `tea issues edit <n> --add-assignees ddmitry` — первая запись в сессии.
+- **Закрыть**: `tea comments add <n> "<ответ>"`, затем `tea issues close <n>`, затем дописать указатель на контекст (суть + ссылка) в Decisions-so-far карты.
@@ -0,0 +1,18 @@
+# Метки триажа
+
+Скиллы оперируют пятью ролями триажа. Эта таблица сопоставляет роли с реальными метками в трекере этого репо.
+
+| Роль в mattpocock/skills | Метка в нашем трекере | Значение                                       |
+| ------------------------ | --------------------- | ---------------------------------------------- |
+| `needs-triage`           | `needs-triage`        | Мейнтейнеру нужно оценить issue                |
+| `needs-info`             | `needs-info`          | Ждём уточнений от автора                       |
+| `ready-for-agent`        | `ready-for-agent`     | Полностью описано, можно отдавать AFK-агенту   |
+| `ready-for-human`        | `ready-for-human`     | Требует реализации человеком                   |
+| `wontfix`                | `wontfix`             | Делать не будем                                |
+
+Когда скилл упоминает роль (например, «повесить метку готовности для агента»), берите строку из правой колонки.
+
+Правую колонку можно менять под свой словарь.
+
+В Gitea-репо меток пока нет. При первом `/triage` создайте их:
+`tea labels create --name needs-triage --color "#e4e669" --description "..."` и так далее для каждой строки таблицы.