agent-quality-kit 0.2.2

package/kit/docs/ai/stream-2026-08-ai-coding-panel.md

@@ -0,0 +1,304 @@
+<!-- источник: audit_project/docs/ai/stream-2026-08-ai-coding-panel.md -->
+# Разбор стрима «Инструментарий AI-кодинга» (2026-08-24)
+
+> **Что это.** Конспект панельного стрима + **сверка каждого тезиса с нашим проектом**: что у нас
+> уже есть, чего нет, что стоит взять, а что — маркетинг. Плюс словарь терминов, прозвучавших в
+> эфире, с переводом на язык этого проекта.
+>
+> **Участники:** Андрей Бреслав (один из создателей Kotlin, делает инструмент CodeSpec —
+> «вечно живая спека» поверх агента) · Валера Ковальский (Neural Deep; инфраструктура, флот
+> агентов, консультирует enterprise по внедрению) · Максим Ключников (техлид, работа с агентами в
+> корпоративной среде) · ведущий.
+>
+> **Как читать пометки:**
+> 🎙 — тезис из стрима: это **мнение практика, а не измерение**. Верификация — на нас.
+> 📏 — измерено/проверено на нашем проекте (дата рядом).
+> ⚖️ — место, где мнения спикеров расходятся или где тезис спорный.
+>
+> **Чем отличается от соседей по корпусу:** [`agent-harness-playbook.md` §18](agent-harness-playbook.md) — наша дисциплина
+> (правило = свой инцидент) · [`harness-best-practices.md`](harness-best-practices.md) — каталог
+> приёмов из чужих харнесов.
+> **Здесь — срез практики индустрии на август 2026 и то, что из него применимо нам.**
+>
+> Дата разбора: **2026-08-24**.
+
+---
+
+## 0. Главный вывод в одну фразу
+
+**Никто из трёх практиков не строит сложный харнес. Все трое строят одно и то же: способ понижать
+размерность — чтобы человек и агент смотрели не на код, а на компактное правдивое представление
+системы — и способ доказывать корректность внешним арбитром, который нельзя подогнать.**
+
+Всё остальное (скиллы, MCP, память, тесты, ревью) — инструменты этих двух целей. Если приём не
+служит ни одной из них — он украшение.
+
+> **📐 Понижение размерности (dimensionality reduction)**
+> **Простыми словами:** заменить 200 000 строк кода на 2 000 строк описания, по которым можно
+> ориентироваться и принимать решения, не открывая код.
+> **Зачем тебе:** кода уже больше, чем человек способен прочитать. Не понизив размерность, ты
+> обязан либо верить агенту на слово, либо не спать.
+> **В твоём проекте:** это `specs/memory/project-map.md` (карта «что где лежит»), `structure.md`,
+> `specs/decisions/` (ADR) и скиллы. Свежесть карты стережёт `scripts/check-map.sh` в pre-commit.
+> **Как проверить:** «могу ли я по карте назвать место правки, ни разу не открыв код?»
+
+Ключевое уточнение Андрея, которое легко пропустить: **сжатое представление тоже нельзя делать
+спагетти**. Модули, границы, SOLID/DRY нужны не только в коде — они нужны в документах и спеках,
+потому что теперь именно документы читает человек.
+
+---
+
+## 1. Словарь: 30 терминов из эфира
+
+### 1.1 Про обвязку агента
+
+| Термин | Простыми словами | У нас |
+|---|---|---|
+| **Харнес (harness)** | вся обвязка вокруг модели: правила, скиллы, хуки, гейты, пайплайн агентов | `.claude/` целиком |
+| **Скилл (skill)** | пакет «инструкция + инструменты + данные» по одной теме, грузится по решению агента | 📏 26 скиллов в `.claude/skills/` |
+| **MCP-сервер** | стандартный способ дать агенту доступ к внешней системе (протокол) | codegraph, codebase_memory, Playwright, ag-mcp |
+| **CLI-инструмент** | то же самое, но обычной консольной командой (`gh`, `aws`, свой скрипт) | 🎙 Андрей: **предпочитает CLI, а не MCP** — дешевле по контексту |
+| **Хук (hook)** | скрипт, который харнес запускает сам при событии; агент не может его обойти | `.claude/hooks/`, pre-commit гейты |
+| **Гейт (gate)** | автоматическая проверка, блокирующая плохое | `scripts/arch-lint.sh`, `check-map.sh`, `test-lock.sh` |
+| **Статуслайн** | строка состояния: модель, остаток лимита, заполнение контекста | 🎙 Валера: минимальный обязательный сетап |
+| **Компакшн (compaction)** | автосжатие переписки, когда контекст переполнен; часть деталей теряется | наблюдается в длинных сессиях |
+| **Контекстное окно** | сколько текста модель держит одновременно | ⚖️ Валера: «жить можно на 256k; миллион — неконтролируемо» |
+
+### 1.2 Про знание и память
+
+| Термин | Простыми словами | У нас |
+|---|---|---|
+| **Memory bank / банк памяти** | структурированное хранилище знаний о проекте в маркдауне | `specs/memory/`, `.claude/agent-memory/`, скиллы |
+| **Слой знаний** | то же самое, но включая «почему так решили» | `specs/decisions/` (ADR) + `docs/` |
+| **Дрифт контекста** | расхождение между тем, что в головах/документах, и тем, что в коде | 📏 наше правило: код — источник истины, статусы task-файлов врут |
+| **Проекция кодовой базы** | компактное представление кода для навигации | `project-map.md`, `structure.md`, `feature-map.md` |
+| **Индексирование / семантический поиск** | быстрый поиск по смыслу, а не по grep | codegraph + codebase_memory (MCP) |
+| **Локализация** | найти место, которое надо править | 🎙 Валера: **90–95% времени агента уходит именно на это** |
+
+### 1.3 Про доказательство корректности
+
+> **📐 Арбитр корректности**
+> **Простыми словами:** то, что говорит «правильно/неправильно» вместо тебя. Тест, сверка с 1С,
+> живой прогон, реальный пользователь.
+> **Зачем тебе:** сила арбитра решает, можно ли доверять «зелёному». Слабый арбитр = зелёный ничего
+> не значит.
+> **В твоём проекте:** сверка отчётов с 1С до копейки — сильный внешний арбитр, поэтому DirectPG
+> идёт по lightweight-треку. Бизнес-логика без такого арбитра — full track с ревью и человеком.
+> **Как проверить:** «может ли агент сделать это зелёным, не сделав работу?» Может → арбитр слабый.
+
+| Термин | Простыми словами | У нас |
+|---|---|---|
+| **Mutation testing** | инструмент портит код специально; если тесты не покраснели — тесты бесполезны | `scripts/mutation-test.sh` (advisory, DirectPG casts) |
+| **Архитектурные тесты** | тест не на поведение, а на структуру: «слой A не смеет импортировать B» | eslint `boundaries` (FSD), `arch-lint.sh`, `check-app-gate-coverage.py` |
+| **Holdout-тесты** | тесты, которых Builder не видит — проверка, что он не подогнал результат | агент `auditor` есть, 📏 по умолчанию **отключён** |
+| **Anti-gaming / reward hacking** | агент добивается «зелёного», не делая работу: правит тест, мокает, удаляет проверку | `scripts/test-lock.sh` — снимок тестов до/после Builder |
+| **Golden-тест** | эталон от авторитетного источника, с которым сверяется вывод | сверка отчётов 1С 1-в-1 |
+| **Eval (эвал)** | проверка **промпта/скилла** на датасете: срабатывает ли, когда надо, и не срабатывает ли, когда не надо | 📏 17 датасетов в `.claude/skills/trigger-evals/`, **прогонщика нет** |
+| **Целевая функция** | формальный критерий «результат хороший» | 🎙 Андрей: автономность работает **только** там, где она есть |
+
+### 1.4 Про людей и процессы
+
+| Термин | Простыми словами | Замечание |
+|---|---|---|
+| **Human-in-the-loop / HumanOp** | человек обязателен в точке решения | ⚖️ все трое: **полностью автономный SDLC — маркетинг** |
+| **Cognitive surrender** | когнитивная капитуляция: человек перестаёт думать и отдаёт решения модели | самый опасный эффект по мнению Максима |
+| **Decision fatigue** | усталость от плотного потока решений: агент пишет быстро, решения нужны часто | 🎙 Андрей: главный источник выгорания в новой работе |
+| **Sycophancy / податливость** | агент соглашается вместо спора; не приходит сказать «твоя идея плоха» | лечится только явным промптом «спорь» |
+| **Размывание ответственности** | «это агент сделал» вместо «я сделал» | 🎙 Максим: командная проблема №1 |
+| **Zero-shot удача** | сложная задача разово удалась с первого раза → человек расслабляется | ловушка: не повторяется |
+| **AI-readiness кодовой базы** | готовность проекта к работе агента: контракты, типы, границы, воспроизводимый прогон | ниже §4 — наш чек-лист |
+| **Explainability** | объяснимость системы человеку: схема, диаграмма, отчёт вместо чтения кода | у нас частично: карты + ADR |
+
+### 1.5 Про инфраструктуру моделей (контекст, а не работа)
+
+**SLM** — маленькие модели для узких задач (классификация, поиск, суммаризация); внутри больших
+агентов они делают львиную долю служебной работы. **Квантование** — сжатие модели ради скорости и
+цены (побочный эффект — падение качества). **MoE (mixture of experts)** — архитектура, где на
+запрос работает часть модели. **Cerebras / Groq** — железо ради очень быстрого инференса.
+🎙 Валера: ближайшие два года прогресса — это цена и скорость инференса, а не «ещё умнее».
+⚖️ «Модели тупеют перед выкаткой новой» — сетевая молва, не измерение; относиться как к гипотезе.
+
+---
+
+## 2. Тезисы, ради которых стоило смотреть
+
+### 2.1 Что говорят все трое (сходятся)
+
+1. **Автономная «фабрика софта» не работает.** Работает только там, где ты умеешь формально
+   отличить хороший результат от плохого. Не умеешь — человек в петле обязателен.
+2. **Архитектура стала важнее, а не менее важна.** Она переезжает из кода в документы и в
+   архитектурные тесты — но никуда не девается.
+3. **Тесты, написанные агентом, — слабый сигнал.** Нужен внешний арбитр либо мутационное
+   тестирование, иначе «зелёное» ничего не доказывает.
+4. **Главная проблема больших репозиториев — не контекст, а навигация.** Агенту нужно за что
+   зацепиться: контракты, типы, границы, карта.
+5. **Скорость (латентность) — главный раздражитель.** Ожидание ломает поток; переключение контекста
+   выжигает больше, чем сама работа.
+
+### 2.2 Где расходятся
+
+| Вопрос | Андрей | Валера | Максим |
+|---|---|---|---|
+| Сложность харнеса | минимальный: голый Claude Code + мало скиллов | средний: флот агентов, скиллы под роль, свой memory-подход | блоки прозы + **детерминированные скрипты** между ними |
+| MCP | не любит, предпочитает CLI | использует | «в enterprise приходится — это стандарт поставки» |
+| Куда вкладываться | новый «язык» выше кода (спеки как инженерный артефакт) | инфраструктура и стоимость инференса | эвалы, трейсы, аналитика по трейсам |
+
+### 2.3 Отдельно ценное
+
+- 🎙 **Андрей:** «Заголовок скилла — это тоже промпт, и его надо эвалить. Самое сложное в скилле —
+  не тело, а описание: чтобы он вызывался, когда надо». Ровно наша боль: автоподхвата нет.
+- 🎙 **Андрей:** «Я написал промпт, он сработал два раза, значит работает» — так рассуждают даже
+  ML-инженеры. Система недетерминированная: два прогона — не проверка.
+- 🎙 **Максим:** агенты **не удаляют код**. Пост-тренинг награждает за написанное, не за удалённое.
+  Отсюда мёртвые области, которые не ловит даже статический анализ (код задублирован).
+- 🎙 **Максим:** «Понижайте размерность того, что передаёте другому человеку». Пять экранов
+  сгенерированного текста коллеге — это перекладывание работы, а не коммуникация.
+- 🎙 **Андрей:** «В интернете все врут: у кого «всё автоматизировано» — не автоматизировано».
+  Поезд не ушёл; время есть, тратить его на инструменты.
+- 🎙 **Валера:** учиться надо базе (как работает сеть, процессор, сервис, сборка) — она и есть то,
+  что позволяет проверять агента.
+
+---
+
+## 3. Сверка с нашим проектом (что уже есть)
+
+Значки строгие: ✅ — сделано **и доказано**; ⬜ — решено, не сделано; ❌ — отсутствует/сломано.
+
+| Тезис стрима | У нас | Доказательство |
+|---|---|---|
+| Понижение размерности: карта проекта | ✅ | `specs/memory/project-map.md` + гейт `scripts/check-map.sh` в pre-commit |
+| Индексаторы вместо grep | ✅ | MCP codegraph + codebase_memory, скиллы `codegraph-mcp`, `codebase-memory-mcp`, правило в `CLAUDE.md` |
+| Архитектура зафиксирована решениями | ✅ | `specs/decisions/` + правило «отступление от ADR — вопрос владельцу» |
+| Архитектурные гейты | ✅ | `arch-lint.sh` (антипаттерны тестов, размер файлов), eslint `boundaries` на error, `check-queue-consumers.py` |
+| Внешний неподгоняемый арбитр | ✅ | сверка отчётов с 1С до копейки; live-stack e2e; Playwright MCP по живому UI |
+| Защита от подгонки тестов | ✅ | `scripts/test-lock.sh` (snapshot/verify вокруг Builder) |
+| Тесты пишет не тот, кто пишет код | ✅ | Tester ≠ Builder — железно |
+| Мутационное тестирование | ⬜ | `scripts/mutation-test.sh` есть, но **advisory и только DirectPG casts** — не гейт |
+| Централизованные логи | ✅ | Loki + Alloy (task-221) |
+| Error tracking (Sentry-класс) | ❌ | нет — числится P0 в `docs/rebuild/10-open-work-register.md` |
+| Эвалы скиллов (срабатывание) | ❌ | 📏 17 датасетов лежат с 2026-06-16, **прогонщика нет**; 9 скиллов вообще без датасета |
+| Трейсы прогонов + метрики агентов | ❌ | 📏 `specs/memory/metrics.json`, `learnings/`, `evolution-archive.jsonl` **отсутствуют**, хотя `CLAUDE.md` и агенты `analyzer`/`evolver` на них ссылаются |
+| Holdout / anti-gaming тесты | ⬜ | агент `auditor` есть, по умолчанию отключён (осознанно) |
+| Изоляция Builder'а (контракты) | ❌ | отключена: `scripts/extract-contracts.py` ломает файлы (📏 воспроизведено 2026-08-03) |
+| Общая среда «люди + агенты» (чат) | ❌ | нет; работа one-to-one с агентом |
+| Учёт стоимости / FinOps токенов | ❌ | не измеряется |
+| Поиск мёртвого кода | ⬜ | `/sentinel` и `arch-audit.sh` есть, запуск ручной и нерегулярный |
+
+**Честный итог сверки:** по «арбитрам корректности» мы сильнее среднего из услышанного — сверка с 1С
+и live-stack e2e жёстче, чем у большинства. По «наблюдаемости самого харнеса» (эвалы, трейсы,
+метрики, стоимость) у нас **дыра, описанная в правилах как работающая система**. Это ровно тот
+случай из [`agent-harness-playbook.md` §18](agent-harness-playbook.md) §3 — документация врёт по умолчанию.
+
+---
+
+## 4. Что взять (кандидаты, по цене/пользе)
+
+Ни один пункт не выполняется без отдельной задачи и апрува — `.claude/**` вне scope продуктовых
+задач. Здесь — обоснование, а очередь работ живёт в
+`../rebuild/10-open-work-register.md`.
+
+### Дёшево и сразу полезно
+
+1. **Прогонщик эвалов скиллов.** Датасеты уже лежат. Нужен скрипт: даёт формулировку → смотрит,
+   загрузился ли скилл → считает точность срабатывания и ложные срабатывания. Закрывает тезис
+   Андрея «заголовок скилла — это промпт, его надо эвалить» и наш собственный инцидент 2026-07-29
+   (скилл не загрузился, решение переоткрыли заново). *Уже стоит в реестре как P3 — поднять.*
+2. **Маркерные слова агента как гейт.** Из эфира: агент отклоняется от курса, называя это `fallback`
+   / `MVP` / «пока замокаем» / «упростим». Дешёвый grep по диффу и по рассуждению → предупреждение
+   в ревью. Это перенос мягкого в жёсткое (`agent-harness-playbook.md` §18 §0).
+3. **Правило «понижай размерность отчёта человеку».** Итоги — таблицей и галочками, а не пятью
+   экранами. У нас это уже формализовано в скилле `engineering-literacy`; распространить требование
+   на отчёты Reviewer/Analyzer.
+
+### Средняя цена, большая отдача
+
+4. **Мутационное тестирование как периодический гейт на расчётных модулях.** Сейчас advisory и
+   только для DirectPG casts. Кандидаты: расчёт прогресса задач (`tracker/progress.py`), кастинг и
+   маппинг DirectPG, денежные расчёты зарплатных отчётов. Медленно — значит по расписанию, не в
+   pre-commit.
+5. **Регулярный охотник за мёртвым кодом.** Тезис Максима: агенты пишут и не удаляют, мёртвые
+   области не ловятся статическим анализом, потому что задублированы. У нас есть `codebase_memory`
+   с детектором дублей (`SIMILAR_TO`) — это ровно тот инструмент. Нужен ритм, а не разовый запуск.
+6. **Сбор трейсов и стоимости прогонов.** Без него `analyzer`/`evolver` — фикция: они читают файлы,
+   которых нет. Либо поднять сбор, либо честно вычеркнуть эволюционную петлю из `CLAUDE.md`.
+   **Одно из двух — обязательно.**
+
+### Дорого / отложить
+
+7. Общая среда «люди + агенты» в одном чате — интересно, но у нас команда из одного человека;
+   выгоды нет.
+8. Своя «вечно живая спека» уровня CodeSpec — большая инженерия; ждать, пока это станет продуктом.
+
+---
+
+## 5. Что НЕ брать (и почему)
+
+- **Оркестрация десятков агентов.** ⚖️ Валера прямо: «в оркестрацию не верю, она не работает».
+  Наш опыт того же класса: укороченный пайплайн работает лучше полного (память
+  `shortened-pipeline-preference`).
+- **Гнаться за миллионным контекстом.** Чем больше окно, тем меньше контроль над тем, что в нём.
+  Наша ставка — компактная правдивая карта, а не «загрузить весь проект».
+- **Плодить скиллы.** 📏 26 скиллов уже съедают около 80% бюджета листинга описаний. Новый скилл —
+  только вместо старого либо с укорачиванием чужих описаний.
+- **Верить «всё автоматизировано» из интернета.** По прямому свидетельству участников — врут.
+- **Оценивать промпт по паре удачных прогонов.** Система недетерминированная; два прогона — анекдот.
+
+---
+
+## 6. Правила-кандидаты (мягкое) и гейты-кандидаты (жёсткое)
+
+По принципу `agent-harness-playbook.md` §18 §0: повторилось нарушение → переносим из мягкого в жёсткое.
+
+**Мягкое (в правила/скиллы):**
+- Промпт, скилл и описание скилла — это код без тестов, пока не прогнаны на датасете.
+- Отчёт другому человеку понижает размерность, а не перекладывает чтение.
+- «Сработало два раза» — не доказательство работоспособности недетерминированной системы.
+- Агент не приходит сам сказать «твоя идея плоха» — спрашивать возражения явно.
+
+**Жёсткое (кандидаты в гейты):**
+- grep по маркерам ухода от курса в диффе (`fallback`, `MVP`, `mock`, `упростим`, `пока что`).
+- порог mutation score на списке критичных модулей (по расписанию).
+- проверка «датасет эвала существует для каждого скилла» при добавлении нового скилла.
+- проверка «файлы, на которые ссылается `CLAUDE.md`, существуют» — она бы поймала отсутствующие
+  `metrics.json` и `learnings/` в тот же день.
+
+---
+
+## 7. Учебный план (для владельца проекта)
+
+Совет из эфира, дословно по смыслу: **качать инженерию высокого уровня, а не синтаксис.**
+Для аудитора, который управляет агентами, это конкретно:
+
+1. **System design крупными блоками:** что такое сервис, очередь, кэш, база, воркер, и как они
+   отказывают. Без этого нельзя оценить «что сломается».
+2. **Границы и контракты:** где у системы швы, кто с кем говорит и по какому соглашению.
+   Это язык, на котором ставится задача агенту.
+3. **Арбитры:** для каждой части системы уметь назвать, чем доказывается её корректность — и честно
+   помечать места, где арбитра нет. Это и есть карта реальной слепоты.
+4. **Критическое мышление как процедура:** любое утверждение агента → «чем проверено?».
+   Три источника (официальная дока × наши правила и интернет × живая система) — уже наше правило.
+5. **Понятия отказов:** идемпотентность, транзакция, гонка, таймаут, ретрай, блокировка.
+   Их разбор с привязкой к проекту — скилл `engineering-literacy` и его `references/concepts.md`.
+
+Проверка усвоения — не «понятно?», а ситуация с выбором. Пример из эфира, годный как упражнение:
+*агент предлагает захардкодить фолбэк, потому что «это же MVP». Что здесь может пойти не так и чем
+это ловится?*
+
+---
+
+## 8. Статус этого документа
+
+Это **конспект мнений практиков**, а не исследование. Тезисы с 🎙 не измерены ни ими, ни нами —
+проверять по мере применения. Сверка с нашим проектом (§3) — 📏 проверена по файлам 2026-08-24:
+наличие скриптов, скиллов, датасетов и отсутствие `metrics.json` / `learnings/` подтверждены
+непосредственно, а не по документации.
+
+---
+
+## Связанное
+
+- Наша дисциплина — [`agent-harness-playbook.md` §18](agent-harness-playbook.md)
+- Каталог приёмов харнесов — [`harness-best-practices.md`](harness-best-practices.md)
+- Процесс по этапам — [`ai-sdlc.md`](ai-sdlc.md)
+- Научная база по анти-геймингу и оценке — [`deep-research-2026-07.md`](deep-research-2026-07.md)
+- Очередь работ проекта

package/kit/docs/ready-made-rules.md

@@ -0,0 +1,170 @@
+# Готовые правила: где искать, прежде чем писать свой гейт
+
+> **Зачем этот файл.** У AQK есть правило «сперва ищи готовое, потом пиши своё». Без карты
+> «где искать» оно неисполнимо. Здесь карта.
+>
+> **Данные не по памяти.** Разбивка по группам получена из самого инструмента:
+> `ruff rule --all --output-format json` (версия 0.15.20) — **964 правила в 61 группе**.
+> Проверить у себя: та же команда.
+
+---
+
+## Правило целиком, обеими половинами
+
+**Сперва ищи готовое.** Готовое лучше не потому, что чужое, а потому что его поддерживают без
+вас, оно подробнее и его знают в лицо в чужих проектах.
+
+📏 Цена пропуска измерена: разбор синтаксического дерева по всему проекту искал час места, где
+ошибку пишут в лог без трейса, — 80 находок. Правило `TRY400` находит их одной строкой конфига,
+нашло 47 и не дало ложных.
+
+**Свой гейт законен, когда он про решение конкретного проекта.** Паритет очередей между средами,
+свежесть карты проекта, неизменяемость применённой миграции, реестр долга — этого в библиотеках
+нет и быть не может: они не знают, как устроен ваш проект.
+
+📏 Проверять надо оба направления: неразрывный пробел не ловит **ни одно** из 964 правил — там
+свой гейт единственный способ.
+
+**«Не искал» и «нет» — разные утверждения.** В `README` записи каталога это отдельный раздел.
+
+## Как проверить за минуту
+
+```bash
+ruff rule --all | grep -i «что ищете»        # есть ли такое правило вообще
+ruff rule TRY400                              # что именно оно делает и как чинить
+ruff check --select TRY400 --statistics .     # сколько находок У ВАС
+```
+
+Третья команда — главная. Она превращает «наверное, полезно» в число, и по этому числу решают:
+ноль находок — включать бесплатно прямо сейчас; десятки — заход на один вечер; тысячи — сначала
+храповик, потом разбор.
+
+---
+
+## Ruff: 61 группа
+
+### Ядро — включать всегда
+
+| Группа | Правил | Что ловит |
+|---|---|---|
+| `F` | 43 | Pyflakes: неиспользуемые импорты и переменные, обращение к несуществующему |
+| `E` `W` | 67 | pycodestyle. ⚠️ подгруппы `E1xx–E3xx` спорят с форматтером — их отключают |
+| `B` | 43 | bugbear: мутабельные значения по умолчанию и прочие классические ловушки |
+| `SIM` | 30 | упрощения: код, который делает лишнее |
+| `UP` | 47 | устаревший синтаксис — агент тянет его из старых данных |
+| `RUF` | 76 | правила самого ruff, включая опознание похожих юникод-символов |
+| `C4` | 20 | лишние преобразования списков и словарей |
+| `PERF` `FURB` | 42 | производительность и современные идиомы |
+
+### Ошибки и отказы — самая ценная группа для кода, который пишет агент
+
+| Группа | Правил | Что ловит |
+|---|---|---|
+| `BLE` | 1 | ловля голого исключения |
+| `TRY` | 10 | tryceratops. **`TRY400`** — запись в лог без трейса. ⚠️ `TRY003` спорное, отключают отдельно |
+| `LOG` `G` | 15 | корректность записи в лог: потерянный трейс, форматирование внутри вызова |
+| `SIM105` | — | перехват ради тишины (замена на подавление явное) |
+| `EM` | 3 | сообщение исключения строкой прямо в конструкторе |
+| `RET` `RSE` | 9 | лишнее перед возвратом, лишние скобки при возбуждении |
+
+### Долг и мусор
+
+| Группа | Правил | Что ловит |
+|---|---|---|
+| `ERA` | 1 | закомментированный код |
+| `FIX` `TD` | 11 | маркеры «доделать потом» и требования к их оформлению |
+| `ARG` | 5 | неиспользуемые аргументы. ⚠️ обычно тысячи находок, нужен храповик |
+| `T` | 3 | отладочная печать (`T201`) и забытая точка останова (`T100`) |
+
+### Размер и сложность
+
+| Правило | Что ловит |
+|---|---|
+| `C901` | цикломатическая сложность функции, порог настраивается |
+| `PLR0912` | слишком много ветвлений |
+| `PLR0913` | слишком много аргументов |
+| `PLR0915` | слишком много инструкций |
+
+**Предела на размер файла среди 964 правил нет.** Это тот случай, где нужен свой гейт.
+
+### Безопасность
+
+| Группа | Правил | Замечание |
+|---|---|---|
+| `S` | 73 | flake8-bandit. **Полностью перекрывает отдельный `bandit`** — держать оба незачем |
+| `PGH` | 5 | в том числе запрет подавления без указания правила |
+| `SLF` | 1 | обращение к приватному снаружи |
+
+### Пути, время, типы
+
+| Группа | Правил | Что ловит |
+|---|---|---|
+| `PTH` | 35 | старая работа с путями вместо `pathlib` |
+| `DTZ` | 10 | время без часового пояса — бомба в любом дат-домене |
+| `TC` | 9 | импорты, нужные только для типов |
+| `ANN` | 11 | отсутствующие аннотации. ⚠️ если стоит `mypy`, это дубль |
+
+### Тесты и стек
+
+`PT` (31) — стиль pytest · `DJ` (7) Django · `FAST` (3) FastAPI · `PD` (13) pandas ·
+`NPY` (4) NumPy · `AIR` (13) Airflow · `PYI` (55) файлы типов · `ASYNC` (16) асинхронность.
+
+Берутся только под свой стек. Остальные — мёртвые правила.
+
+### Спорные — решать осознанно
+
+| Группа | Почему спорная |
+|---|---|
+| `D` (48) | докстринги по формату. Если они содержательные, а не форматные — шум |
+| `Q` `COM` `ISC` | кавычки, запятые, склейка строк — спорят с форматтером |
+| `FBT` (3) | булев аргумент как ловушка. Полезно, но ломает много чужих сигнатур |
+| `CPY` (1) | требование заголовка об авторских правах |
+
+### Мелкие, но дешёвые
+
+`A` (6) имя затеняет встроенное · `PIE` (8) мелкие бессмыслицы · `N` (16) именование ·
+`ICN` (3) общепринятые сокращения импортов · `TID` (5) порядок импортов ·
+`SLOT` (3) · `FLY` (1) · `YTT` (10) · `INP` (1) · `EXE` (5) · `INT` (3) · `FA` (2) · `DOC` (7).
+
+---
+
+## Другие стеки: где искать
+
+| Язык | Инструмент | Как посмотреть список |
+|---|---|---|
+| JavaScript, TypeScript | eslint | `npx eslint --print-config file.js`; правила — на сайте eslint |
+| TypeScript | typescript-eslint | отдельный набор поверх eslint |
+| Go | `go vet`, staticcheck | `staticcheck -list-checks` |
+| Rust | clippy | `cargo clippy -- -W help` |
+| Ruby | rubocop | `rubocop --show-cops` |
+| Java, Kotlin | detekt, SpotBugs | `detekt --generate-config` |
+| PHP | PHPStan, Psalm | уровни строгости вместо групп |
+| Shell | shellcheck | `shellcheck --list-optional` |
+| SQL | sqlfluff | `sqlfluff rules` |
+| Dockerfile | hadolint | список в документации |
+| Любой | semgrep | реестр чужих правил: `semgrep --config auto` |
+
+**Кроссязыковое:** `gitleaks` — секреты · `trivy` — уязвимости образов ·
+`jscpd` — дубли и Python, и TypeScript одним прогоном.
+
+---
+
+## А если проект не на Python?
+
+Ничего не меняется. Запись каталога держит **одно намерение и несколько исполнителей**, и
+программа выбирает в три ступени: готовый инструмент под ваш язык → переносимая проверка без
+зависимостей → честно скрыть запись, если нечем.
+
+Так что проект на Rust, Go или C++ получает сторожа сразу — переносимого. А когда кто-то принесёт
+строку `rust: cargo clippy …`, он уступит место более точному.
+
+**Одна строка в существующей записи — самый дешёвый и самый ценный вклад.** Намерение уже
+доказано отказом, образцы уже лежат, проверять нечего кроме самой команды.
+
+## Если готового нет
+
+Тогда свой гейт — и в его `README.md` пишется, **что именно проверено**: какой инструмент
+смотрели и какой командой. Это не бюрократия: через год кто-то захочет выкинуть самописное как
+дубль, и разница между «не искал» и «нет» решает, выкинуть или оставить.
+
+Норма записи — `kit/gates/README.md`.