ddadmin
6c9d986114
- Зачем:
- GitHub-аккаунт заблокирован, работа идёт в Gitea на git.dementev.space,
а инструкции для агентов всё ещё описывали GitHub Issues и gh.
- Что:
- docs/agents/issue-tracker.md переписан под Gitea и tea 0.15.0: установка,
вход, скоупы токена, обход прокси, команды для issues/комментариев/меток;
- блокировки переведены на нативные зависимости Gitea через tea api,
текстовые строки Blocked by из тел тикетов убраны;
- GitHub ушёл одной строкой в раздел «Архив»;
- docs/agents/triage-labels.md и блок «Agent skills» в AGENTS.md
переобвязаны на Gitea.
- Проверка:
- tea issues list, tea labels list — читают трекер;
- граф блокировок карты #10 собран заново и прочитан обратно через
tea api repos/{owner}/{repo}/issues/<n>/dependencies.
68 lines
6.1 KiB
Markdown
68 lines
6.1 KiB
Markdown
# AGENTS.md
|
|
|
|
Короткий контракт для работы в репозитории мини-демо DWH кликстрима.
|
|
|
|
## Цель репозитория
|
|
|
|
Данный проект - учебный для менти. Учебная ценность разработок - одна из его базовых ценностей.
|
|
|
|
## Обязательные правила
|
|
|
|
Пиши на ясном русском языке. Иностранные слова оставляй только там, где у термина нет устоявшегося русского аналога: имена технологий и инструментов (Kafka, ClickHouse, Airflow) и названия из кода. Если для понятия есть обычное русское слово — используй его, не выдумывай транслитерации (пиши «приведение в соответствие», а не «реконсиляция»; «точка отсчёта», а не «origin»).
|
|
|
|
Документы, комментарии и объяснения держи короткими и понятными читателю, который их не писал: простые слова, короткие фразы, сложную мысль поясняй при первом упоминании (помни про менти-неспециалиста). Если понятность и буквальная точность спорят — выбирай понятность. Правило касается и текста, и заголовков разделов.
|
|
|
|
Внутренние рассуждения и промежуточные пометки по ходу работы веди на английском — он экономнее по токенам (кириллица занимает примерно в 1,5–2 раза больше). На русском остаётся всё, что видит и хранит проект: итоговые ответы пользователю, документы, комментарии в коде и сообщения коммитов.
|
|
|
|
Для работы с python использовать uv.
|
|
|
|
### Данные
|
|
|
|
- Не загружать `*.jsonl` целиком без необходимости: по умолчанию использовать малый срез (`head -n 20..50`).
|
|
- Для демо и тестов важнее быстрый и повторяемый прогон, чем полнота данных.
|
|
- "Грязные" записи не должны валить пайплайн: ошибки парсинга фиксируются в ODS.
|
|
|
|
### Изменения в коде
|
|
|
|
- Изменения держать минимальными и в скоупе задания (инфра, ingest, трансформации, витрины, мониторинг).
|
|
- Не коммитить секреты. Использовать `.env` и `.env.example`.
|
|
- При изменении инфраструктуры или DDL обновлять документацию в этом же PR.
|
|
- Комментарии в SQL и Bash писать на русском языке.
|
|
|
|
### Проверка API через MCP Context7 (обязательно)
|
|
|
|
- Для спорных или меняющихся API (особенно Airflow/operators/providers) сначала уточнять актуальную версию через MCP Context7.
|
|
- Минимальный порядок: `resolve-library-id` -> `query-docs`.
|
|
- Принятое решение фиксировать в коде и/или документации (кратко: что проверили и почему выбрали именно этот вариант).
|
|
|
|
## Agent skills
|
|
|
|
Конфигурация для инженерных скиллов (набор Matt Pocock). Подробности — в `docs/agents/`.
|
|
|
|
### Issue tracker
|
|
|
|
Gitea на `git.dementev.space` (через CLI `tea`). Спека фичи — файлом в `docs/specs/` (источник истины), корневой issue — тонкий, со ссылкой на спеку и чек-листом дочерних issues. См. `docs/agents/issue-tracker.md`.
|
|
|
|
### Triage labels
|
|
|
|
Пять канонических ролей как метки Gitea, имена совпадают (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). См. `docs/agents/triage-labels.md`.
|
|
|
|
### Domain docs
|
|
|
|
Single-context: `CONTEXT.md` и `docs/adr/` в корне репозитория. См. `docs/agents/domain.md`.
|
|
|
|
## Навигация по документации
|
|
|
|
- [README.md](./README.md) — пользовательский quick start и обзор.
|
|
- [docs/REPO_MAP.md](./docs/REPO_MAP.md) — карта исполняемых артефактов и где что менять.
|
|
- [docs/OPERATIONS.md](./docs/OPERATIONS.md) — запуск, DAG-параметры, проверки и troubleshooting.
|
|
- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — детали по слоям STG/ODS/DDS/DM.
|
|
- [docs/COMMIT_RULES.md](./docs/COMMIT_RULES.md) — правила оформления коммитов.
|
|
- [docs/course/](./docs/course/) — продвинутый учебный курс «со звёздочкой» на базе стенда (PRD, план обучения, стандарт уроков); начинать с [docs/course/README.md](./docs/course/README.md).
|
|
- [plans/](./plans/) — legacy-планы (использовать как исторический контекст, не как источник истины).
|
|
- `.scratch/handoffs/YYYYMMDD-HHMM-<slug>.md` — handoff'ы для продолжения работы в новой сессии (одноразовые, коммитятся, уборка best-effort; скилл `handoff` пишет сюда). См. [docs/adr/0003-handoffs-in-scratch.md](./docs/adr/0003-handoffs-in-scratch.md).
|
|
|
|
## Ограничения по структуре
|
|
|
|
- Новые документы создавать в `docs/` (или в профильных подпапках), не в корне репозитория.
|