diff --git a/AGENTS.md b/AGENTS.md index 0856d13..2f270ad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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`. diff --git a/CLAUDE.md b/CLAUDE.md index 43c994c..7da0307 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1 +1,7 @@ @AGENTS.md + +# Читабельность языка + +Пиши легко для чтения. Сокращай количество мыслей, а не количество слов, которыми выражена каждая мысль. + +Please remove all mannered prose. diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..86a4aa2 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,51 @@ +# Доменная документация + +Как скиллам читать доменную документацию этого репо перед работой с кодом. + +## Что читать перед началом + +- **`CONTEXT.md`** в корне репо, или +- **`CONTEXT-MAP.md`** в корне, если он есть: указывает на отдельный `CONTEXT.md` для каждого контекста. Читайте те, что относятся к теме. +- **`docs/adr/`**: читайте ADR, которые касаются области, с которой собираетесь работать. В мультиконтекстных репо также проверяйте `src//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), но стоит пересмотреть, потому что…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..8742ac5 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -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: #, #` в начале описания дочернего тикета. Тикет разблокирован, когда все блокирующие закрыты. +- **Поиск фронтира**: `tea issues list --state open --labels wayfinder:task -o json` (повторить для каждого типа), оставить только детей этой карты, отбросить те, у кого есть открытый блокер в `Blocked by` или назначенный исполнитель; первый по порядку в карте. +- **Взять в работу**: `tea issues edit --add-assignees ddmitry` — первая запись в сессии. +- **Закрыть**: `tea comments add "<ответ>"`, затем `tea issues close `, затем дописать указатель на контекст (суть + ссылка) в Decisions-so-far карты. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..412e913 --- /dev/null +++ b/docs/agents/triage-labels.md @@ -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 "..."` и так далее для каждой строки таблицы.