Files

T

ddadmin d3bc2f7c18 docs(agents): контракт скиллов — трекер, метки триажа, доки и нейминг

- Зачем:
  - инженерные скиллы (to-tickets, triage, wayfinder, domain-modeling) ждут
    репо-локальную настройку; без неё они не знают, чем заводить issues и
    какими метками размечать. Дока трекера жила ссылкой на репозиторий
    предшественника — внешняя зависимость на месте источника истины.
- Что:
  - заведён docs/agents/: issue-tracker.md (Gitea через tea, команды,
    wayfinding, отдельный раздел про то, что «Закрывает #NN» issue не
    закрывает), triage-labels.md (пять канонических меток без переименований)
    и domain.md (один контекст, CONTEXT.md и docs/adr/).
  - в AGENTS.md добавлен раздел «Agent skills» со ссылками на эти файлы,
    ссылка на доку предшественника заменена локальной.
  - в «Структуре» закреплён нейминг: ГГГГ-ММ-ДД-слаг для docs/specs/ и
    docs/research/, NNNN-слаг для docs/adr/.
- Проверка:
  - tea labels list — все пять меток триажа заведены в репозитории;
  - tea api version — Gitea 1.27.0, команды из доки отвечают живьём.

2026-07-31 09:45:19 +03:00

6.0 KiB

Raw Blame History

AGENTS.md

Короткий контракт для работы в репозитории учебной дата-платформы кликстрима.

Цель репозитория

Проект учебный: учебная ценность разработок — одна из его базовых ценностей. Стенд строится по спеке «Боевой реализм стенда (v2)».

Язык

Пиши на ясном русском языке. Иностранные слова оставляй только там, где у термина нет устоявшегося русского аналога: имена технологий (Kafka, ClickHouse, Airflow) и названия из кода. Если для понятия есть обычное русское слово — используй его, не выдумывай транслитерации.

Документы и комментарии держи короткими и понятными читателю, который их не писал: простые слова, короткие фразы, сложную мысль поясняй при первом упоминании. Если понятность и буквальная точность спорят — выбирай понятность.

Внутренние рассуждения и промежуточные пометки по ходу работы веди на английском — он экономнее по токенам. На русском остаётся всё, что видит и хранит проект: итоговые ответы, документы, комментарии в коде и SQL, сообщения коммитов.

Код и данные

Python — только через uv.
Изменения держать минимальными и в границах задания.
Секреты не коммитить: настройки — через .env, образец — .env.example.
При изменении инфраструктуры или DDL обновлять документацию тем же PR.
Коммиты — Conventional Commits: заголовок type(scope): результат, тело на русском по схеме Зачем / Что / Проверка.
«Грязные» записи не должны валить пайплайн: ошибки разбора уходят в таблицы *_errors.
Данные не читать целиком без необходимости: по умолчанию малый срез. Для демо и тестов быстрый повторяемый прогон важнее полноты данных.

Проверка API через MCP Context7 (обязательно)

Для спорных или меняющихся API (Airflow и провайдеры, DDL ClickHouse) сначала уточнять актуальную версию: resolve-library-id -> query-docs. Принятое решение кратко фиксировать в коде или документации: что проверили и почему выбрали этот вариант.

Задачи

Трекер — Gitea на git.dementev.space, работа через CLI tea (логин по умолчанию настроен, репозиторий определяется по git remote). Команды и подводные камни — в docs/agents/issue-tracker.md.

Спека фичи — файл в docs/specs/, источник истины, версионируется с кодом.
Корневой issue фичи — тонкий: ссылка на спеку и чек-лист дочерних issues (- [ ] #NN). Содержание спеки в issue не дублируется.
Дочерние issues — самодостаточные постановки: цель, критерии приёмки чекбоксами, границы, «сначала прочитать», команды проверки.
Итоговые решения переносятся в спеку или ADR тем же PR.
Метки триажа — пять ролей: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. Карта и её тикеты — метки wayfinder:*.

Agent skills

Issue tracker

Задачи — в Gitea на git.dementev.space, все операции через CLI tea. См. docs/agents/issue-tracker.md.

Triage labels

Пять канонических меток триажа без переименований, уже заведены в трекере. См. docs/agents/triage-labels.md.

Domain docs

Один контекст: CONTEXT.md в корне и docs/adr/. См. docs/agents/domain.md.

Структура

Новые документы — в docs/ или в профильных подпапках, не в корне.
Состав доков v2 определяется по ходу этапов, набор предшественника не копируется (спека, раздел 12).
Имена файлов в docs/specs/ и docs/research/ — ГГГГ-ММ-ДД-краткое-имя.md: дата создания документа и слаг строчными латинскими буквами через дефис (2026-07-30-stand-v2-realism.md). Дата фиксирует, когда документ появился, и при правках не меняется: файлы сортируются по времени, а история живёт в git.
Имена файлов в docs/adr/ — NNNN-краткое-имя.md: сквозной номер из четырёх цифр и слаг (0001-stand-services.md). Решения нумеруются подряд, дата в имени не нужна.

6.0 KiB Raw Blame History