From 8508405b0f0dc293437de2dcde08fcf0e14278f8 Mon Sep 17 00:00:00 2001 From: Lacky1234union Date: Wed, 14 Oct 2026 18:08:31 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20guardrails=20=D0=B2=20CLAUDE.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs #21 Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index c3e91b6..507bbe8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -52,11 +52,30 @@ Telegram-бот «git в телеграме» для команды (учебн --- +## Guardrails + +Мнемоника: **пусти по приглашению, запри чужой код, не дай LLM команд, спрячь секреты, повтори запрос, держи гейт зелёным.** + +| # | Правило | Где живёт правда | +|---|---------|------------------| +| 1 | **Доступ — только участникам.** Новый роутер/хэндлер не обходит `AccessMiddleware` (outer, на `message` и `callback_query`); без приглашения — ни одного действия | `app/bot/middlewares/access.py`, ADR-011 | +| 2 | **Чужой код — только в песочнице `tgit-runner`.** Бот не получает `docker.sock` напрямую: чтение — через read-only proxy, запуск — через runner с forced command | `infra/runner/`, ADR-005/006 | +| 3 | **LLM не исполняет ничего.** Только JSON по схеме (`LogQuery`, вердикт стража) → валидация → выполнение ботом в Python; grep — не в shell; логи в LLM не передаются | `app/agent/`, ADR-007/013 | +| 4 | **Провайдер — за протоколом.** Вендорский код только в `app/llm/.py`, остальные зависят от `LLMProvider` | `app/llm/provider.py`, ADR-008 | +| 5 | **Конфиг типизирован.** Только `app/config.py` (`pydantic-settings` по подсистемам), без `os.getenv` вразброс; тексты, пороги, промпты — `config/*.yaml` | `app/config.py` | +| 6 | **Секреты — только в `.env`.** Не логируются, не уходят в LLM, не попадают в git и в чат | `.env.example` | +| 7 | **Внешние вызовы — с ретраями.** SourceCraft API и Gitea рвут соединения: повторы с задержкой, перед повторным POST проверить, не создалось ли | `app/sourcecraft/client.py`, `docs/dev/*_API.md` | +| 8 | **Схема БД — только миграциями.** Изменил модель → `alembic revision --autogenerate` + ручное ревью (импорты, дубли CHECK); тест дрейфа должен быть зелёным | `app/db/`, `tests/db/test_migrations.py` | +| 9 | **Гейт зелёный:** `make lint && make test` перед PR; порог покрытия (`fail_under`) только растёт | `pyproject.toml` | +| 10 | **В SourceCraft не пушим и не мержим** — это зеркало Gitea; `.sourcecraft/` и `.tgit/` в `tgit-uploads` правим через шаблон `infra/uploads-template/` | ADR-010, ADR-014 | + +--- + ## TL;DR — работа 1. **Задача = Issue в Gitea.** Нет issue — нет кода. 2. **Ветка от `dev`:** `/-`. PR в `dev` (в Gitea); `dev → main` — только человек. -3. **Гейт зелёный:** lint + тесты перед PR. +3. **Гейт зелёный:** `make lint && make test` перед PR; guardrails выше — не нарушать. 4. **Завершил → push + PR** сразу. 5. **Лог выполнения** — в issue (`### YYYY-MM-DD`), архитектурные решения — в `DECISIONS.md`. 6. **Секреты** (токен бота, deploy-ключ, ключи LLM) — только в `.env`, в чат и git не попадают.