From b97339782734ac5c4bf1af433d53201bcddee028 Mon Sep 17 00:00:00 2001 From: Lacky1234union Date: Mon, 12 Oct 2026 18:05:12 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=81=D0=BA=D0=B5=D0=BB=D0=B5=D1=82=20?= =?UTF-8?q?=D0=BF=D1=80=D0=BE=D0=B5=D0=BA=D1=82=D0=B0=20=E2=80=94=20CLAUDE?= =?UTF-8?q?.md,=20=D1=80=D0=B5=D0=B3=D0=BB=D0=B0=D0=BC=D0=B5=D0=BD=D1=82,?= =?UTF-8?q?=20=D1=88=D0=B0=D0=B1=D0=BB=D0=BE=D0=BD=20issue,=20=D1=87=D0=B5?= =?UTF-8?q?=D1=80=D0=BD=D0=BE=D0=B2=D0=B8=D0=BA=20=D0=A2=D0=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- .gitignore | 25 +++++++++++++++++ CLAUDE.md | 43 +++++++++++++++++++++++++++++ README.md | 11 +++++++- docs/ARCHITECTURE.md | 15 +++++++++++ docs/DECISIONS.md | 23 ++++++++++++++++ docs/QUESTIONS_IDEAS.md | 17 ++++++++++++ docs/SPEC.md | 32 ++++++++++++++++++++++ docs/dev/ISSUE_TEMPLATE.md | 34 +++++++++++++++++++++++ docs/dev/WORKFLOW.md | 55 ++++++++++++++++++++++++++++++++++++++ 9 files changed, 254 insertions(+), 1 deletion(-) create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/DECISIONS.md create mode 100644 docs/QUESTIONS_IDEAS.md create mode 100644 docs/SPEC.md create mode 100644 docs/dev/ISSUE_TEMPLATE.md create mode 100644 docs/dev/WORKFLOW.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ce098f2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,25 @@ +# secrets +.env +.env.* +!.env.example +*.pem +id_* + +# python +__pycache__/ +*.py[cod] +.venv/ +.pytest_cache/ +.ruff_cache/ +.mypy_cache/ +.coverage +htmlcov/ +dist/ +build/ +*.egg-info/ + +# editors / tools +.idea/ +.vscode/ +.claude/worktrees/ +.DS_Store diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5de2628 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,43 @@ +# CLAUDE.md — Руководство для Claude Code + +## Что мы строим + +Telegram-бот (учебный проект НИУ ВШЭ, курс Python): принимает `.py`-файлы, коммитит их в отдельный +репозиторий на SourceCraft, где автоматически запускается CI/CD. Бот сообщает статус CI, присылает +алерты о падениях/перегрузке, отдаёт логи и умеет отвечать на вопросы по логам через LLM. + +**ТЗ:** [`docs/SPEC.md`](docs/SPEC.md) · **Архитектура:** [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) + +--- + +## Процесс работы + +- Перед кодом — подход в 2–3 предложениях при архитектурных развилках. +- Код по модулям; пользователь проверяет после каждого; комментарии — только когда WHY неочевиден. +- Язык общения — русский. + +--- + +## Карта документации + +> Задачи — в Issues на SourceCraft, не в файлах. + +| Файл | О чём | +|------|-------| +| [`docs/SPEC.md`](docs/SPEC.md) | ТЗ: требования, сценарии, критерии приёмки | +| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Компоненты, потоки данных, деплой | +| [`docs/DECISIONS.md`](docs/DECISIONS.md) | ADR: архитектурные решения (что и почему) | +| [`docs/QUESTIONS_IDEAS.md`](docs/QUESTIONS_IDEAS.md) | Открытые вопросы, бэклог идей | +| [`docs/dev/WORKFLOW.md`](docs/dev/WORKFLOW.md) | Регламент: ветки, коммиты, PR, жизненный цикл задачи | +| [`docs/dev/ISSUE_TEMPLATE.md`](docs/dev/ISSUE_TEMPLATE.md) | Шаблон тела issue | + +--- + +## TL;DR — работа + +1. **Задача = Issue.** Нет issue — нет кода. +2. **Ветка от `dev`:** `/-`. PR в `dev`; `dev → main` — только человек. +3. **Гейт зелёный:** lint + тесты перед PR. +4. **Завершил → push + PR** сразу. +5. **Лог выполнения** — в issue (`### YYYY-MM-DD`), архитектурные решения — в `DECISIONS.md`. +6. **Секреты** (токен бота, deploy-ключ, ключи LLM) — только в `.env`, в чат и git не попадают. diff --git a/README.md b/README.md index 21ded81..715a0fc 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,12 @@ # tgit -Телеграмм бот для закгрузки кода в репозиторий и работы с ним. Простыми словами расширенный git внутри telegram-бота +Телеграм-бот для загрузки кода в репозиторий и работы с ним. Простыми словами — расширенный git внутри Telegram-бота. + +Бот принимает `.py`-файлы и коммитит их в репозиторий на SourceCraft, где автоматически запускается CI/CD; +сообщает статус пайплайна, присылает алерты, отдаёт логи и отвечает на вопросы по ним через LLM. + +Учебный проект, курс Python, НИУ ВШЭ. + +- ТЗ: [`docs/SPEC.md`](docs/SPEC.md) +- Архитектура: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- Как работаем: [`docs/dev/WORKFLOW.md`](docs/dev/WORKFLOW.md) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..43eb73b --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,15 @@ +# Архитектура + +> Заполняется после согласования ТЗ. + +## Компоненты + +_TODO: бот, git-интеграция с SourceCraft, наблюдатель за CI, сбор логов/метрик, LLM-ассистент, хранилище._ + +## Потоки данных + +_TODO: загрузка файла → коммит → CI → уведомление._ + +## Деплой + +_TODO._ diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md new file mode 100644 index 0000000..32a4dfd --- /dev/null +++ b/docs/DECISIONS.md @@ -0,0 +1,23 @@ +# Архитектурные решения (ADR) + +Формат записи: + +``` +## ADR-NNN: <заголовок> +**Дата:** YYYY-MM-DD · **Статус:** принято | отменено | заменено ADR-MMM + +**Контекст:** почему возник вопрос. +**Решение:** что выбрали. +**Альтернативы:** что отвергли и почему. +**Последствия:** что это меняет. +``` + +--- + +## ADR-001: Хостинг кода и задач — SourceCraft +**Дата:** 2026-10-12 · **Статус:** принято + +**Контекст:** нужен репозиторий проекта, трекер задач и CI. +**Решение:** код бота, issues и CI — на SourceCraft. Загрузки пользователей — в отдельный репозиторий там же. +**Альтернативы:** GitHub/Gitea — не соответствует постановке преподавателя. +**Последствия:** CI описывается в формате SourceCraft; бот ходит в SourceCraft по своему deploy-ключу. diff --git a/docs/QUESTIONS_IDEAS.md b/docs/QUESTIONS_IDEAS.md new file mode 100644 index 0000000..5619278 --- /dev/null +++ b/docs/QUESTIONS_IDEAS.md @@ -0,0 +1,17 @@ +# Открытые вопросы и идеи + +## Вопросы + +- [ ] Что именно делает CD: куда «доставляется» загруженный `.py` (запуск как сервис? проверка тестами?) +- [ ] Есть ли на SourceCraft container registry, или пушим образы в другое место? +- [ ] Где деплоим: VPS или локально? Нужна ли БД (пользователи, история загрузок)? +- [ ] Как бот узнаёт статус CI: polling SourceCraft API или webhook? +- [ ] Кто может загружать файлы: любой пользователь или whitelist? +- [ ] Какой LLM-провайдер для чата по логам? +- [ ] Нужна ли интеграция с anytask и в каком виде? + +## Идеи + +- Команда `/logs` с фильтрами (сервис, уровень, период). +- LLM формирует `grep`/запрос к логам, выполняет его в песочнице, суммирует результат. +- Алерты: падение пайплайна, рестарт контейнера, CPU/RAM выше порога. diff --git a/docs/SPEC.md b/docs/SPEC.md new file mode 100644 index 0000000..e09bc92 --- /dev/null +++ b/docs/SPEC.md @@ -0,0 +1,32 @@ +# ТЗ — черновик + +> Статус: **черновик**. Ждём официальное ТЗ от преподавателя (обещано 2026-10-12), затем сверяем и детализируем. + +## Исходная постановка (от преподавателя) + +- Telegram-бот, который загружает `.py`-файлы в репозиторий на SourceCraft. +- После загрузки автоматически запускается CI/CD. +- Репозиторий для загрузок — отдельный (не репозиторий с домашками). +- У бота свой SSH/deploy-ключ. +- Развёртывание: VPS или локально на ноутбуке. +- Опционально: настроить anytask. +- Вайбкодинг разрешён. + +## Согласованные расширения + +- Уведомления об успешности/падении CI. +- Алерты о падении и перегрузке сервиса. +- Удобное получение логов. +- Чат с LLM, который строит `grep`-запросы по логам и отвечает на вопросы. + +## Функциональные требования + +_TODO — после получения ТЗ._ + +## Нефункциональные требования + +_TODO._ + +## Критерии приёмки + +_TODO._ diff --git a/docs/dev/ISSUE_TEMPLATE.md b/docs/dev/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..d39230f --- /dev/null +++ b/docs/dev/ISSUE_TEMPLATE.md @@ -0,0 +1,34 @@ +# Шаблон тела issue + +Задача должна быть самодостаточной: открыв её через неделю, должно быть понятно, что делать, без дополнительных вопросов. + +```markdown +## Описание +Контекст: почему задача возникла, какую проблему решает. Ссылки на связанные issue и ADR. + +## Желаемый результат +Конкретно и проверяемо. Пример: +- «На отправку `.py`-файла бот отвечает ссылкой на коммит в течение 5 с» + +## Подзадачи +- [ ] Подзадача 1 — конкретный шаг, указать файл/модуль +- [ ] Подзадача 2 + +## Анализ +### Затрагиваемые файлы +| Файл | Что меняется | +|------|--------------| + +### Ограничения и риски +Edge cases, безопасность (чужой код!), секреты, лимиты Telegram API. + +## Как проверить +Шаги/команды и ожидаемый результат. + +--- + +## Лог выполнения +``` + +> Лог дополняется секцией `### YYYY-MM-DD` при каждой рабочей сессии. +> Issue закрывается, когда все подзадачи выполнены и ветка смержена. diff --git a/docs/dev/WORKFLOW.md b/docs/dev/WORKFLOW.md new file mode 100644 index 0000000..5fb871e --- /dev/null +++ b/docs/dev/WORKFLOW.md @@ -0,0 +1,55 @@ +# Регламент работы + +## Откуда задачи + +- Только из Issues на SourceCraft. Нет issue → завести → потом код. +- Атрибуты issue: исполнитель, метка зоны (`bot` / `ci` / `infra` / `llm` / `docs`), + тип (`feature` / `fix` / `refactor` / `docs`), размер (`size/0.5` ≈ 2ч · `size/1` ≈ 4ч · `size/2` ≈ 1д). +- Тело — по [`ISSUE_TEMPLATE.md`](ISSUE_TEMPLATE.md). + +## Жизненный цикл задачи + +``` +1. Взял issue +2. git fetch origin && git switch -c /- origin/dev +3. Код по модулям; коммиты с Refs #N +4. git rebase origin/dev +5. lint + тесты +6. Лог в issue: ### YYYY-MM-DD +7. PR в dev с Closes #N +8. Мерж → ветку удалить +``` + +## Ветки + +``` +main (сдаваемая версия) ←── мержит только человек +dev (интеграция) ←── сюда все PR +/- ←── от dev +``` + +## Коммиты — Conventional Commits + +``` +feat(bot): принимать .py-файлы и коммитить в репозиторий загрузок + +Refs #12 +``` + +## Шаблон PR + +```markdown +## Что меняется +1–3 предложения. + +Closes # + +## Как проверить +шаги/команды + +## Чек-лист +- [ ] rebase на origin/dev +- [ ] lint + тесты зелёные +- [ ] секретов в диффе нет +- [ ] лог в issue дописан +```