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

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

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): там - общий принцип поведения, здесь - процедура выбора решения.

Модель и текущие назначения

Перед новым заданием и запуском применяй маршрутизацию моделей: свежий MODELS выше канонического дефолта. Границы данных и полномочий этого навыка сохраняются.