engineering-principles

name

engineering-principles

description

Pragmatic coding principles: SOLID, KISS, DRY, YAGNI in balance. Use when writing code, refactoring, reviewing, or designing architecture. Prevents over-engineering while maintaining code quality. Триггеры: "напиши код", "рефактори", "code review", "архитектура", "engineering principles", "SOLID", "KISS", "DRY", "YAGNI", "design this", "how to structure", "разбей на модули", "спроектируй архитектуру", "создай проект", "структура проекта", "объясни архитектуру"

Engineering Principles — Pragmatic Balance

Priority (when in conflict)

1. Работает → решает задачу пользователя
2. Просто (KISS) → простейшее рабочее решение, можно понять и поддерживать
3. Не усложняй заранее (YAGNI) → сначала работающий простой код, не усложнять заранее
4. Убери настоящий дубль (DRY) → только когда реально нужно (3+ места), настоящая одинаковая логика
5. SOLID → когда система уже растёт; маленький скрипт ≠ нужна абстракция

Что даёт каждый принцип (цель, не догма)

Принцип	Зачем	Стоп-сигнал
SRP — одна ответственность	Меняешь одно → не ломает другое	Функция > 40 строк или 3+ причин менять → раздели
OCP — расширяй, не меняй	Новая фича → старое работает	Не создавай абстракции "на будущее" (см. YAGNI)
LSP — замена без сюрпризов	Подставил реализацию → работает	instanceof, if type → плохой дизайн, переделай
ISP — минимум зависимостей	Не тяни лишнее	Интерфейс > 5 методов → разбей
DIP — завись от абстракций	Меняешь деталь → бизнес-логика не знает	Не абстрагируй то что не будет меняться
KISS — простота	Код понятен с первого чтения	if/else на 3 ветки ≠ нужна фабрика
DRY — без дублирования	Баг в одном месте → починил везде	Похожий код, разная логика → НЕ трогай
YAGNI — фокус	Не тратишь время на ненужное	"Конфиг на будущее", "generic для всего" → стоп

Product-first Checks

Перед финальной реализацией спроси:

1. Какую видимую пользователю проблему это решает?
2. Как пользователь поймёт что это сработало?
3. Что сломается если входные данные, сеть, зависимость или данные — плохие?
4. Можно ли это наблюдать, тестировать, откатить, объяснить?
5. Это простейший код который оставляет будущие изменения продукта дешёвыми?

Product Engineering Priorities

1. Correct user outcome — правильный результат для пользователя
2. Clear surfaced behavior — ясные API/UI/контракты/ошибки
3. Safe changeability — безопасно менять
4. Operational visibility — можно наблюдать и дебажить
5. Code elegance — красота кода (последний приоритет)

Before writing code — 3 вопроса

1. Какую задачу пользователя это решает?
2. Есть ли проще способ?
3. Что если это изменится — легко ли переделать?

Complexity gates

• Cyclomatic complexity ≤ 15 (функции > 20 → рефактори или обоснуй в PR)
• Вложенность > 3 уровней → early return / guard clauses
• Файл > 400 строк → раздели если логически делится

✅/❌ Quick Reference

KISS

✅ Простая коллекция вместо сложной структуры ✅ Одна функция 40 строк понятнее чем 3 по 15 ❌ Фабрика + стратегия + декоратор для if/else на 3 ветки

DRY

✅ Одинаковая бизнес-логика в 3 местах → вынеси ❌ Две функции с 2 общими строками → не объединяй ❌ Совпадение структуры ≠ дублирование (accidental duplication)

YAGNI

❌ "Интерфейс пригодится когда будет вторая реализация" ❌ "Generic решение для всех возможных случаев" ❌ "Конфиг на будущее" ✅ Делаешь под задачу → рефакторишь когда задачи меняются

SOLID

✅ SRP: одна причина менять → один класс/функция ❌ SRP: 10 классов для 10 строк кода → over-engineering ✅ DIP: бизнес-логика не знает про базу данных ❌ DIP: абстракция над каждым console.log ✅ OCP: новый тип через композицию, не правка существующего ❌ OCP: 5 уровней наследования "на всякий случай"

Practical Guidelines

Когда применять SOLID

• Код > 100 строк в одном файле
• Уже есть 2+ места где используется
• Команда > 1 человека или долгоживущий проект
• Частые изменения в одной области

Когда остановиться (KISS wins)

• Скрипт < 50 строк
• Одноразовая утилита
• Прототип / spike
• if/else на 2-3 ветки
• Нет признаков что будет расти

DRY — прагматичный подход

• True duplication: одинаковая логика, одинаковая причина менять → выноси
• Accidental similarity: похожая структура, разная причина менять → НЕ трогай
• Rule of 3: нашёл в 3 местах → время вынести

YAGNI — красные флаги over-engineering

• "Потом пригодится"
• "На случай если..."
• "Может быть вторая реализация"
• "Generic для всех случаев"
• Абстракция без конкретного второго пользователя

What this gives

Principle	Real benefit
KISS	Readability — understand code on first read
YAGNI	Focus — spend time on what's needed now, no over-engineering
DRY	Consistency — fix bugs once, everywhere fixed (when truly duplicated)
SRP	Stability — change one thing without breaking another
OCP	Safe extensions — new features don't break old code
LSP	Predictability — swap implementations without surprises
ISP	Minimal deps — depend only on what you use
DIP	Modularity — swap infrastructure freely

---

Project Structure Standards

Стандартная структура (адаптируй под стек)

project/
├── src/              # Бизнес-логика, компоненты, сервисы
│   ├── modules/      # Функциональные модули (SRP: один модуль = одна зона)
│   ├── shared/       # Переиспользуемые утилиты (общие helpers, types)
│   └── index         # Entry point
├── config/           # Конфигурации (дефолтные, примеры, env templates)
├── scripts/          # Утилиты: билд, деплой, миграции, генераторы
├── tests/            # Тесты: unit, integration, e2e
├── docs/             # Доки: API, архитектура, runbooks
└── .env.example      # Шаблон переменных окружения

Зоны ответственности папок

Папка	Что внутри	Что НЕ внутри
src/	Бизнес-логика, компоненты, API handlers	Конфиги, скрипты деплоя, тесты
config/	Дефолтные конфиги, .env.example, templates	Секреты, хардкод значений
scripts/	Автоматизация, CLI-утилиты, генераторы	Бизнес-логика приложения
tests/	Unit, integration, e2e, fixtures, mocks	Production код
docs/	README, API specs, architecture decisions	Устаревшие доки без даты

SRP на уровне файлов

• Файл > 400 строк → раздели если логически делится
• Один класс/функция/модуль = одна причина менять
• Entry point (index.ts, main.py) = только wiring, без логики

---

Architecture Explanation Guide

После проектирования — объясни:

1. Ключевые решения

• Что решил → почему так → какие альтернативы отверг
• Формат: Решение: X. Причина: Y. Альтернатива Z отвергнута потому что W.

2. Последовательность компонентов

• Что за чем идёт и почему
• Формат: A → B → C с пояснением зачем каждый шаг
• Пример: CLI (парсинг args) → Config (валидация) → Service (логика) → Output (результат)

3. Зона ответственности каждого компонента

• Каждый модуль/файл: что делает, что НЕ делает
• Формат: Компонент X: делает Y. Не делает Z. Зависит от W.

4. Потоки данных

• Откуда данные приходят, куда уходят, где трансформируются
• Формат: Input → [Transform] → Output
• Укажи контракты: типы данных, форматы, ошибки

5. Связи и зависимости

• Кто кого вызывает, кто от кого зависит
• Стрелки зависимостей: модуль A → модуль B (A зависит от B)
• Покажи где DIP/абстракции, где прямые зависимости

Правило: кратко, без воды

• Связь → Причина → Следствие
• Не "этот компонент очень важен" → "Config валидирует env → сервис падает рано с понятной ошибкой"

---

Pre-implementation Checklist

Перед написанием кода — пройдись по чеклисту:

1. План (Todos ≤ 10 пунктов)

• Составь todo-лист ≤ 10 конкретных действий
• Каждый пункт — действие, не абстракция ("создать src/config/parser.ts" не "настроить парсинг")
• Порядок: от фундамента к фичам

2. Проектирование

• Структура папок определена
• Зоны ответственности разделены (SRP)
• Контракты между модулями понятны
• Entry point определён

3. Объяснение

• Ключевые архитектурные решения зафиксированы
• Последовательность компонентов описана
• Потоки данных понятны

4. Complexity gates

• Cyclomatic complexity ≤ 15
• Вложенность ≤ 3 уровней (guard clauses)
• Файл ≤ 400 строк (разделить если больше)

---

Syntax & Smoke Test Checklist

После написания — проверь:

Проверка синтаксиса (по стеку)

Язык	Команда
JavaScript/Node.js	node -c file.js
TypeScript	npx tsc --noEmit
Python	python -m py_compile file.py
Bash	bash -n script.sh
Go	go build ./...
Rust	cargo check

Базовая работоспособность

• Запускается без краша (если есть entry point — запусти)
• Smoke test: основной сценарий работает
• Конфиги валидны (если есть config loader — проверь загрузку)
• Ошибки понятны (если падает — сообщение говорит что не так)

---

Configuration Standards

Обязательные конфиги

• .env.example — шаблон всех переменных с комментариями
• Дефолтный конфиг с безопасными значениями (fail-safe defaults)
• Пример config файла с пояснениями каждого поля

Правила

• Никогда не коммить реальные секреты — токены, ключи, пароли
• .env.example показывает структуру, не значения
• Дефолты = безопасные (localhost, пустые строки, тестовые значения)
• Документируй откуда брать значения (ссылки на API, сервисы)

Формат .env.example

# API ключ (получить на https://example.com/api-keys)
API_KEY=your-api-key-here

# URL базы данных (format: postgresql://user:pass@host:port/db)
DATABASE_URL=postgresql://localhost:5432/mydb

# Порт приложения (default: 3000)
PORT=3000

# Лог уровень: debug, info, warn, error (default: info)
LOG_LEVEL=info

---

Implementation Workflow

Полный цикл создания проекта/фичи:

1. Прочитай этот скилл — загрузи engineering-principles
2. Составь Todos ≤ 10 — конкретные действия, порядок
3. Спроектируй структуру — папки, модули, контракты
4. Объясни архитектуру — решения, последовательность, потоки
5. Реализуй — код, конфиги, скрипты, примеры
6. Проверь синтаксис — по языку (см. таблицу выше)
7. Smoke test — запусти, убедись работает
8. Зафиксируй — README, примеры использования