Minimal Code

---
name: minimal-code
description: Перед правкой кода, когда есть выбор решения (абстракция, зависимость, копипаста) - минимальное: переиспользование, stdlib, потом новое. Тривиальная правка без выбора - избыточен.
---

# Минимализм кода

Перед тем как писать код, пройди лестницу молча (без пошагового нарратива) и остановись на первой подходящей ступени:

1. Это нужно прямо сейчас? Нет -> не пиши (YAGNI).
2. Уже есть в кодовой базе -> переиспользуй или расширь.
3. Есть в stdlib или нативных возможностях платформы (HTML, CSS, ОС) -> используй.
4. Есть в установленных зависимостях -> используй.
5. Иначе -> минимальное ясное изменение в стиле проекта.

Если остановился на ступени 5 не самоочевидным образом - одной строкой скажи пользователю, почему предыдущие ступени не подошли.

Новая зависимость - вне лестницы: не добавляй молча. Предложи ее явно с одной строкой обоснования, почему ступени 2-4 не покрывают (например: security-чувствительный или сложный домен, где свой код хуже проверенной библиотеки).

## Когда НЕ применять

- **Решение уже принято и реализовано** - лестница ступеней нужна на развилке, а не как повод переписать работающий код. Переписывание ради простоты это отдельная задача с отдельным обоснованием.
- **Сложность требуется по существу** - криптография, транзакции, обработка отказов в распределенной системе. Здесь "минимально" не равно "проще": срезанная ступень оборачивается дефектом.
- **Чужой код в чужом стиле** - правка в существующем проекте следует его конвенциям, даже если они сложнее нужного (см. `karpathy-guidelines.md` про хирургичность).

## Багфикс: чини общую функцию, а не путь из тикета

Тикет называет симптом - место, где проблема всплыла. Прежде чем ставить guard там, найди функцию, в которой дефект на самом деле, и прогреби ее вызывающих (`grep`). Один фикс в общей функции - меньший диф, чем guard на каждом вызове, а патч только по пути из тикета оставляет соседние вызовы сломанными.

Свип вызывающих - это разведка, а не фронт работ, и решает он ровно один вопрос: **что функция обещает**.

- Обещает нужную гарантию - чини внутри нее, вызовы не трогай. Обещание бывает и параметром: `resolve_path(path, sandbox_root=None)` уже заявляет, что при переданном `sandbox_root` результат не выйдет за него; если не выходит - дефект внутри функции, и guard'ы у вызывающих его не закрывают, а размазывают (следующий вызов снова забудут).
- Не обещает, а гарантия нужна части вызывающих - чини у них, на границе доверия. Тот же `resolve_path()` без такого параметра зовут и HTTP-контроллер с путем от пользователя, и backup-CLI с доверенным абсолютным путем; sandbox-проверка внутри общей функции закроет дыру и сломает бэкап. Диф в общей функции короче, но поведенчески шире запроса - это уже не минимализм, а поломка соседей.

Вопрос "чего ждут вызывающие" сам по себе развилку не решает: ждать они могут разного как раз потому, что функция обещает разное поведение по флагу.

Это ступень 2, примененная к багфиксу: сначала посмотри, что уже есть, потом решай, где чинить.

## Осознанное упрощение помечай в коде

Срезал реальный угол с известным потолком (глобальный лок вместо пула, перебор вместо индекса, наивная эвристика) - оставь рядом маркер-комментарий: что упрощено, где потолок, чем заменить, когда упрется.

```
# SIMPLIFIED: глобальный лок вместо пула - хватает до ~10 rps, дальше нужен пул соединений
```

Без пометки срезанный угол неотличим от недосмотра: ни ревьюер, ни ты через месяц не отличите "решили так осознанно" от "не подумали". Единый маркер по проекту дает реестр техдолга одним `grep`.

Маркер подчиняется конвенциям проекта, а не наоборот: принят свой (`HACK:`, `NOTE:`) - используй его, не заводи второй; проект запрещает такие комментарии (линтер вроде `no-warning-comments`, генерируемые файлы, код под checksum) - зафиксируй упрощение там, где проект ведет учет: в описании PR, тикете, CHANGELOG. Требование - чтобы потолок был записан, а не чтобы он был записан именно комментарием.

## Никогда не режь ради краткости

Корректность, читаемость, необходимые тесты, валидацию на границах доверия (внешний ввод, API), security, защиту от потери данных, доступность (a11y).

Из двух решений одного размера выбирай edge-case-корректное: минимализм - это меньше кода, а не более хлипкий алгоритм.

## Принцип

Ленивый в решении - не ленивый в чтении: сначала изучи существующий код.

См. также `rules/karpathy-guidelines.md` (Simplicity First): там - общий принцип поведения, здесь - процедура выбора решения.