ousterhout-build-deep

SKILL.md

---
name: ousterhout-build-deep
description: Используйте при написании или изменении кода, перед тем как считать задачу выполненной, всякий раз, когда изменение добавляет экспортируемое или импортируемое имя, создает модуль, класс, компонент, хелпер, хук, сервис или обертку, либо централизует повторяющийся код. Контрольный список для автора при создании глубоких модулей: назовите решение, которое скрывает граница, пройдите тесты глубины и инвариантности, исправляйте проблемы вместо их перемещения, никогда не разделяйте только по размеру и завершайте короткой заметкой о дизайне. Компактный компаньон к ousterhout-quality-program, который остается полным обзорным инструментом.
---

# Build it deep (Ousterhout, author-time)

Вы пишете код, а не проверяете его. Запустите это на своих изменениях, прежде чем считать задачу выполненной.

## 1. Ворота

Добавляет ли изменение экспортируемое/импортируемое имя, создает модуль, класс, компонент, хелпер, хук, сервис или обертку, либо централизует повторяющийся код? Если нет, пропустите этот навык. Переименования, codemods, правки конфигураций/данных и однострочные исправления не считаются.

## 2. Прежде чем писать границу

- Найдите, как этот репозиторий уже решает проблему такой формы, и следуйте этому, если не можете объяснить, почему нет. Читайте текущую документацию и типы зависимости: API, вызванный по памяти: это утверждение, а не источник.
- Сначала напишите комментарий к интерфейсу: что он обещает, что скрывает. Если вы не можете назвать скрытое решение (формат, политика, правило, выбор схемы), граница не должна существовать. Впишите это внутрь.
- Назовите это на языке предметной области. Если единственное честное имя: `utils`, `helpers` или `manager`, значит, разрез сделан не там.

## 3. Два теста

- **Глубина.** Интерфейс должен скрывать существенно больше, чем открывать. Обертка, которая просто передает аргументы,: это издержка без пользы; удалите её.
- **Инвариант.** Выделяйте общий код только тогда, когда он защищает общее правило. Доказательство: совместное изменение: копии исправлялись или менялись вместе в истории. Похожие, но меняющиеся независимо, остаются дублированными.

## 4. Исправление должно устранять проблему, а не переносить её

- Шесть кастов, собранных в один универсальный хелпер, всё равно остаются шестью кастами. Напишите типизированный маппер, который эти касты маскировали.
- Не добавляйте параметр или флаг, который перекладывает решение на вызывающих, если только вызывающие действительно не знают чего-то, чего не знаете вы. Впитайте сложный случай внутрь.
- Предпочитайте семантику, при которой ошибка не может возникнуть, вместо того, чтобы заставлять каждого вызывающего её обрабатывать.
- Перенос существенной доменной сложности в другой файл: это не упрощение.

## 5. Под давлением «почистить это» или «этот файл слишком большой»

Никогда не делите только из-за размера. Один модуль на 400 строк, скрывающий одно решение, лучше четырёх модулей по 100 строк, которые протекают теми же соединениями. Спросите, какое решение скрывает каждый разрез; если никакого: не делите.

## 6. Безопасность

Существующий код: закрепите текущее поведение тестом перед углублением. Новый код: напишите тест, который определяет желаемое поведение.

## 7. Отчет

Если ворота сработали, завершите итоговое сообщение 2-4 строками заметок по дизайну: каждая добавленная граница и скрытое ею решение; дублирование, оставленное намеренно, и почему; всё поверхностное, что вы приняли, и почему.

Для спорных решений или полного обзора загрузите `ousterhout-quality-program`.

Теги