# 🔴 КАЧЕСТВО КОДА — между over-engineering и монки-патчем (минимальная правильная архитектура)

Два полюса одного дефекта качества. **Over-engineering** (лишнее) и **монки-патч / костыль**
(срезанный угол в ущерб стабильности) — оба плохи. Sweet spot между ними = **минимальная
правильная архитектура**, затем **обязательная верификация** (тест/запуск/чтение diff — durable
artifact, не слова). Прямое следствие «Quality of Solutions», не противопоставление.

Ориентир: **«500 строк там, где задача чинится в 5 — это не усердие, это долг»** — и одновременно
**«костыль, который "работает", — это долг с процентами»**.

## Полюс 1 — БЕЗ монки-патчей (не срезать угол в ущерб стабильности)
- Монки-патч / hack запрещён без **КРАЙНЕЙ** нужды. Между костылём и чистым переписыванием —
  **переписываем чисто, с пониманием причины**, потом верифицируем.
- Между быстрым хаком и правильной архитектурой — правильная архитектура.
- «Крайняя нужда» (тогда патч можно, с пометкой): прод горит → немедленный hot-fix + **сразу**
  заведённый follow-up на чистое решение; внешняя библиотека, которую нельзя править → точечный
  shim с комментарием-обоснованием. В остальном — переписываем нормально.
- Override костыля — только явный OK пользователя на конкретный случай. «Так быстрее» / «и так
  сойдёт» — не основания.

## Полюс 2 — БЕЗ over-engineering (YAGNI: лучший код — ненаписанный)
Лишняя абстракция, спекулятивная обобщённость, boilerplate «на будущее», новая зависимость ради
пары строк — увеличивают поверхность багов, стоимость чтения, хрупкость. Меньше кода, делающего
ровно требуемое и корректного на краях, = **больше** стабильности.

**Лесенка** (останавливаемся на первой сработавшей ступени; это рефлекс, не ресёрч-проект):
1. **Это вообще нужно?** Спекулятивная потребность → пропустить, сказать одной строкой. (YAGNI)
2. **Стандартная библиотека уже умеет?** Используем.
3. **Нативная фича платформы покрывает?** (`<input type="date">` вместо пикер-либы, CSS вместо JS,
   constraint в БД вместо кода приложения.)
4. **Уже установленная зависимость решает?** Используем. **Не** тащим новую ради пары строк.
5. **Можно одной строкой?** Делаем одной строкой.
6. **Только теперь** — минимум кода, который работает.

## Помечаем намеренные упрощения (комментарий = потолок + путь апгрейда)
Сознательный shortcut с известным потолком (global lock, O(n²)-скан, наивная эвристика) **обязан**
нести комментарий, называющий потолок И путь апгрейда — чтобы упрощение читалось как **намерение**,
а не невежество (смыкается с `no-guessing`: комментарий-обоснование у каждой неочевидной развилки):
```python
# simplification: глобальный лок; per-account локи, если упрёмся в throughput
# simplification: линейный скан N<10k ок; индекс, когда станет горячим путём
```
(держимся одного префикса `simplification:` внутри файла.)

## Когда НЕ ленимся (жёсткие исключения)
Никогда не упрощаем прочь: **валидацию входа на границах доверия, обработку ошибок против потери
данных, безопасность, доступность, калибровку под реальное железо** (часы плывут, сенсор врёт —
оставляем ручку калибровки, не только «меньше кода»), и **всё явно запрошенное**. User просит
полную версию → строим, без переспоров.

**Ленивый код без проверки — недоделан.** Нетривиальная логика (ветка, цикл, парсер, денежный/
секьюрный путь) оставляет ОДНУ запускаемую проверку — наименьшее, что падает, если логика сломана
(assert-демо/`__main__` self-check или один маленький тест). Тривиальный one-liner проверки не требует.

## 🔴 ГРАНИЦА — НЕ путать с экономией токенов и НЕ срезать полноту
Это правило про «не добавляй незапрошенную сложность» и «не срезай угол хаком». Оно **НЕ** про
«делай меньше работы / экономь токены / срежь ветки». Оси ортогональны и обе обязательны → цель =
**«минимально, но полно и правильно»**:
- **`finish-the-task` P3** (качество, НЕ экономия токенов) имеет приоритет: меньший diff —
  *побочный продукт* отказа от over-building, **никогда не цель**. Нельзя ссылаться на это правило,
  чтобы оправдать недоделку, пропуск верификации или «shortest diff» в ущерб корректности.
- **`finish-the-task` P2** (все связанные ветки, не минимум): «минимально» относится к *коду на
  ветку*, а не к *числу пройденных веток*. Все ветки проходим и верифицируем.

Тест перед действием: «я убираю **лишнее** / отказываюсь от **костыля** (хорошо) — или я недоделываю
**нужное** (нарушение P2/P3)?»

## Интенсив по запросу
Базовый уровень — это правило (мягкий always-on). Усиление — наш скилл `/lean-code
[lite|full|ultra]` (lite = назвать ленивую альтернативу, выбор за user; ultra = YAGNI-экстремист,
оспорить саму потребность). Триггеры: «be lazy», «simplest solution», «yagni», жалобы на
over-engineering/bloat/boilerplate. Блокирующий always-on хук минимализма НЕ ставим — только
advisory (`over-engineering-advisor`), иначе дрался бы с каноном полноты.

## Механический энфорсмент (постоянно, «на код»)
Правило грузится always-on, но под давлением контекста забывается → добавлен PostToolUse-хук
**`over-engineering-advisor.py`** (Write|Edit|MultiEdit): на НАДЁЖНЫХ сигналах (большое добавление в
код-файл / новая зависимость в манифесте) выдаёт **advisory-нудж** «это минимум? stdlib/native/одна
строка?» — **НИКОГДА не блок** (блок дрался бы с `finish-the-task`: легитимно большую ПОЛНУЮ фичу
гейтить нельзя). Размытые smells (factory-for-one, интерфейс-с-одной-реализацией) хук НЕ
автоклассифицирует — это судит модель + ревью (`/lean-code` / `/simplify`). Тюнинг `CLAUDE_BLOAT_EDIT_LINES` /
`CLAUDE_BLOAT_NEWFILE_LINES`, bypass `CLAUDE_ALLOW_BLOAT=1`. Сам энфорсер минимален: один advisory-хук,
без дублирующей SessionStart-инъекции (правило и так грузится) — YAGNI к самому YAGNI-энфорсеру.

## Доказательная база (ресёрч 2026-06-16)
- ИИ-агенты **измеримо** раздувают код (GitClear, 211М строк: дубли↑/рефактор↓; Faros: +98% PR, +91%
  ревью без прироста скорости) — проблема реальная, лесенка YAGNI оправдана.
- **Always-on минимализм non-monotonic** (arXiv 2601.22025 «When better prompts hurt»: может уронить
  полноту/точность) → энфорсмент **advisory, не блок**; минимализм держим **on-demand-скиллом
  (`/lean-code`) + advisory-хуком, без блокирующего always-on** (ресёрч подтвердил это решение).
- Цифры **80-94% = непроверенный маркетинг**; реальная цель — «наименьшее, что **ПОЛНОСТЬЮ** решает
  задачу» (метрика успеха — rewrite/churn-rate, не голый LOC). Перед урезанием **подать контекст**
  (окружающий код/требования), не слепые правила.

## Anti-patterns
- ❌ Интерфейс с одной реализацией, фабрика для одного продукта, конфиг для неизменного значения.
- ❌ Новая зависимость ради того, что = несколько строк или есть в stdlib.
- ❌ Boilerplate/скаффолд «на потом» — потом само себя наскаффолдит.
- ❌ Монки-патч/костыль без крайней нужды или без follow-up на чистое решение.
- ❌ «Минимализм» как предлог недоделать ветку / пропустить verify (нарушение P2/P3).
- ❌ Упрощение без комментария-потолка → читается как невежество.
- ❌ Объяснение длиннее кода: каждый абзац, защищающий упрощение, = сложность, протащенная прозой.

## Related
- `finish-the-task.md` — канон дисциплины; P2 (полнота) / P3 (качество не токены) **имеют приоритет**.
- `no-pre-existing-evasion.md` — найденный по пути баг чиним, «минимализм» ≠ повод отложить.
- `edit-formats-and-tiering.md` — «shortest working diff» как формат правок (search/replace), не алиби недоделки.
- `no-guessing.md` — комментарий-потолок = частный случай комментария-обоснования; после правки — verify.
- `lean-code` (skill) — наш on-demand интенсивер минимализма; `over-engineering-advisor` (hook) — advisory-энфорсмент.
