docs: скелет проекта — CLAUDE.md, регламент, шаблон issue, черновик ТЗ

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 18:11:22 +03:00
parent a5d1e90aab
commit b973397827
9 changed files with 254 additions and 1 deletions
@@ -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
@@ -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`:** `<type>/<issue#>-<slug>`. PR в `dev`; `dev → main` — только человек.
+3. **Гейт зелёный:** lint + тесты перед PR.
+4. **Завершил → push + PR** сразу.
+5. **Лог выполнения** — в issue (`### YYYY-MM-DD`), архитектурные решения — в `DECISIONS.md`.
+6. **Секреты** (токен бота, deploy-ключ, ключи LLM) — только в `.env`, в чат и git не попадают.
@@ -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)
@@ -0,0 +1,15 @@
+# Архитектура
+
+> Заполняется после согласования ТЗ.
+
+## Компоненты
+
+_TODO: бот, git-интеграция с SourceCraft, наблюдатель за CI, сбор логов/метрик, LLM-ассистент, хранилище._
+
+## Потоки данных
+
+_TODO: загрузка файла → коммит → CI → уведомление._
+
+## Деплой
+
+_TODO._
@@ -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-ключу.
@@ -0,0 +1,17 @@
+# Открытые вопросы и идеи
+
+## Вопросы
+
+- [ ] Что именно делает CD: куда «доставляется» загруженный `.py` (запуск как сервис? проверка тестами?)
+- [ ] Есть ли на SourceCraft container registry, или пушим образы в другое место?
+- [ ] Где деплоим: VPS или локально? Нужна ли БД (пользователи, история загрузок)?
+- [ ] Как бот узнаёт статус CI: polling SourceCraft API или webhook?
+- [ ] Кто может загружать файлы: любой пользователь или whitelist?
+- [ ] Какой LLM-провайдер для чата по логам?
+- [ ] Нужна ли интеграция с anytask и в каком виде?
+
+## Идеи
+
+- Команда `/logs` с фильтрами (сервис, уровень, период).
+- LLM формирует `grep`/запрос к логам, выполняет его в песочнице, суммирует результат.
+- Алерты: падение пайплайна, рестарт контейнера, CPU/RAM выше порога.
@@ -0,0 +1,32 @@
+# ТЗ — черновик
+
+> Статус: **черновик**. Ждём официальное ТЗ от преподавателя (обещано 2026-10-12), затем сверяем и детализируем.
+
+## Исходная постановка (от преподавателя)
+
+- Telegram-бот, который загружает `.py`-файлы в репозиторий на SourceCraft.
+- После загрузки автоматически запускается CI/CD.
+- Репозиторий для загрузок — отдельный (не репозиторий с домашками).
+- У бота свой SSH/deploy-ключ.
+- Развёртывание: VPS или локально на ноутбуке.
+- Опционально: настроить anytask.
+- Вайбкодинг разрешён.
+
+## Согласованные расширения
+
+- Уведомления об успешности/падении CI.
+- Алерты о падении и перегрузке сервиса.
+- Удобное получение логов.
+- Чат с LLM, который строит `grep`-запросы по логам и отвечает на вопросы.
+
+## Функциональные требования
+
+_TODO — после получения ТЗ._
+
+## Нефункциональные требования
+
+_TODO._
+
+## Критерии приёмки
+
+_TODO._
@@ -0,0 +1,34 @@
+# Шаблон тела issue
+
+Задача должна быть самодостаточной: открыв её через неделю, должно быть понятно, что делать, без дополнительных вопросов.
+
+```markdown
+## Описание
+Контекст: почему задача возникла, какую проблему решает. Ссылки на связанные issue и ADR.
+
+## Желаемый результат
+Конкретно и проверяемо. Пример:
+- «На отправку `.py`-файла бот отвечает ссылкой на коммит в течение 5 с»
+
+## Подзадачи
+- [ ] Подзадача 1 — конкретный шаг, указать файл/модуль
+- [ ] Подзадача 2
+
+## Анализ
+### Затрагиваемые файлы
+| Файл | Что меняется |
+|------|--------------|
+
+### Ограничения и риски
+Edge cases, безопасность (чужой код!), секреты, лимиты Telegram API.
+
+## Как проверить
+Шаги/команды и ожидаемый результат.
+
+---
+
+## Лог выполнения
+```
+
+> Лог дополняется секцией `### YYYY-MM-DD` при каждой рабочей сессии.
+> Issue закрывается, когда все подзадачи выполнены и ветка смержена.
@@ -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 <type>/<issue#>-<slug> 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
+<type>/<issue#>-<slug>       ←── от dev
+```
+
+## Коммиты — Conventional Commits
+
+```
+feat(bot): принимать .py-файлы и коммитить в репозиторий загрузок
+
+Refs #12
+```
+
+## Шаблон PR
+
+```markdown
+## Что меняется
+1–3 предложения.
+
+Closes #<N>
+
+## Как проверить
+шаги/команды
+
+## Чек-лист
+- [ ] rebase на origin/dev
+- [ ] lint + тесты зелёные
+- [ ] секретов в диффе нет
+- [ ] лог в issue дописан
+```